diff options
| -rw-r--r-- | doc/Makefile.am | 2 | ||||
| -rw-r--r-- | doc/zmq.txt | 4 | ||||
| -rw-r--r-- | doc/zmq_deviced.txt | 145 |
3 files changed, 149 insertions, 2 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am index 05cb3dc..44dcfdf 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,4 +1,4 @@ -MAN1 = +MAN1 = zmq_deviced.1 MAN3 = zmq_bind.3 zmq_close.3 zmq_connect.3 zmq_init.3 \ zmq_msg_close.3 zmq_msg_copy.3 zmq_msg_data.3 zmq_msg_init.3 \ zmq_msg_init_data.3 zmq_msg_init_size.3 zmq_msg_move.3 zmq_msg_size.3 \ diff --git a/doc/zmq.txt b/doc/zmq.txt index 362f907..54c7ba1 100644 --- a/doc/zmq.txt +++ b/doc/zmq.txt @@ -144,7 +144,9 @@ nodes in complex messaging topologies. Devices can act as brokers that other nodes connect to, proxies that connect through to other nodes, or any mix of these two models. -You can start a device in an application thread, see linkzmq:zmq_device[3]. +You can start a device in an application thread, see linkzmq:zmq_device[3], +and you can also start devices externally, as standalone processes, see +linkzmq:zmq_deviced[1]. ERROR HANDLING diff --git a/doc/zmq_deviced.txt b/doc/zmq_deviced.txt new file mode 100644 index 0000000..fd94c96 --- /dev/null +++ b/doc/zmq_deviced.txt @@ -0,0 +1,145 @@ +zmq_deviced(1) +============== + +NAME +---- +zmq_deviced - start built-in 0MQ devices + +SYNOPSIS +-------- + +*zmq_deviced _DEVICE_ _FRONTEND_ _BACKEND_* + +*zmq_deviced [_CONFIGFILE_]* + +DESCRIPTION +----------- +Starts one or more 0MQ devices. If you specify a DEVICE, FRONTEND, and BACKEND +then _zmq_device_ starts a single device acting as a mini-broker. If you +specify a CONFIGFILE, you can configure _zmq_device_ to start multiple +concurrent devices with arbitrary configurations. + +*Note* - zmq_deviced is not yet implemented. This is a design. + +MINI-BROKER USAGE +----------------- +Runs as a mini-broker that accepts connects to both frontend and backend. This +creates a hub-and-spoke topology in which all peers connect to the device. This +is a robust and easy to manage topology. + +DEVICE is one of: *queue*, *forwarder*, or *streamer*. See +linkzmq:zmq_device[3] for a specification of these device types. + +FRONTEND and BACKEND are endpoints in the format 'transport'`://`'address', See +linkzmq:zmq_bind[3] for a specification of valid transports and addresses. + + +CONFIGURED USAGE +---------------- +CONFIGFILE is the name of an XML file, readable by 'zmq_device'. This file +provides a specification of the devices to start and how to connect and/or bind +their frontends and backends. If CONFIGFILE is absent or *-* then the +configuration is read from standard input. + +The configuration file has this general syntax: + +---- +<?xml?> +<config [ iothreads="..." ] > + <device type="..."> + <frontend [ type="..." ] > + <set name = "..." value = "..." />... + <bind endpoint="..." /> ... + <connect address="..." /> ... + </frontend> + <backend [ type="..." ] > + <set name = "..." value = "..." />... + <bind address="..." /> ... + <connect address="..." /> ... + </backend> + </device> +</config> +---- + +*iothreads*:: + specifies the number of I/O threads for the process. Specify this only for + high-volume scenarios. See linkzmq:zmq_init[3]. +*device*:: + defines one device. For each device element you define, 'zmq_device' will + start a thread. +*frontend*:: + defines the frontend for the device. Occurs once per device element. You + may override the default socket type. +*backend*:: + defines the backend for the device. Occurs once per device element. You +may override the default socket type. +*set*:: + defines a socket option for the frontend or backend. The valid names are + *hwm*, *swap*, *identity*, *subscribe*, *unsubscribe*, *rate*, + *recovery_ivl*, *mcast_loop*, *sndbuf*, and *rcvbuf*. See + linkzmq:zmq_setsockopt[3]. +*bind*:: + binds the frontend or backend to the specified endpoint. See + linkzmq:zmq_bind[3]. +*connect*:: + binds the frontend or backend to the specified endpoint. See + linkzmq:zmq_connect[3]. + +SOCKET TYPES +------------ + +By default 'zmq_device' uses these socket types: + +*queue* device:: + frontend is *xrep*, backend is *xreq*. +*forwarder* device:: + frontend is *sub*, backend is *pub*. +*streamer* device:: + frontend is *pull*, backend is *push*. + +You can override the socket type for frontend or backend. The valid types are: +*req*, *rep*, *xreq*, *xrep*, *sub*, *pub*, *pull*, *push*, and *pair*. See +linkzmq:zmq_socket[3]. + +*Note*: if you use a *sub* socket you must explicitly set a subscription filter +or your socket will not receive any data. + + +EXAMPLE +------- + +.Creating a queue broker +---- +zmq_device queue tcp://*:5050 tcp://*:5051 +---- + +.A TCP-to-multicast proxy forwarder +---- +zmq_device - +<?xml?> +<config> + <device type="forwarder"> + <frontend> + <!-- subscribe to everything --> + <set name = "subscribe" value = "" /> + <!-- connect to two publishers --> + <connect address="tcp://192.168.55.112:5055" /> + <connect address="tcp://192.168.55.114:5055" /> + </frontend> + <backend> + <!-- bind to epgm group via eth0 --> + <bind address="epgm://eth0;239.192.1.1:5555" /> + </backend> + </device> +</config> +---- + + +SEE ALSO +-------- +linkzmq:zmq_device[3] +linkzmq:zmq_init[3] +linkzmq:zmq_setsockopt[3] +linkzmq:zmq_bind[3] +linkzmq:zmq_connect[3] +linkzmq:zmq[7] |