diff options
| -rw-r--r-- | doc/zmq.txt | 22 | ||||
| -rw-r--r-- | doc/zmq_bind.txt | 13 | ||||
| -rw-r--r-- | doc/zmq_connect.txt | 13 | ||||
| -rw-r--r-- | doc/zmq_device.txt | 56 | ||||
| -rw-r--r-- | doc/zmq_deviced.txt | 50 | ||||
| -rw-r--r-- | doc/zmq_getsockopt.txt | 2 | ||||
| -rw-r--r-- | doc/zmq_pgm.txt | 4 | ||||
| -rw-r--r-- | doc/zmq_poll.txt | 4 | ||||
| -rw-r--r-- | doc/zmq_setsockopt.txt | 2 | ||||
| -rw-r--r-- | doc/zmq_tcp.txt | 11 |
10 files changed, 117 insertions, 60 deletions
diff --git a/doc/zmq.txt b/doc/zmq.txt index e8a3a97..0ff26e7 100644 --- a/doc/zmq.txt +++ b/doc/zmq.txt @@ -140,20 +140,14 @@ Local in-process (inter-thread) communication transport:: Devices ~~~~~~~ -Apart from the 0MQ library the 0MQ distribution includes 'devices' which are -building blocks intended to serve as intermediate nodes in complex messaging -topologies. - -The following devices are provided: - -Forwarder device for request-response messaging:: - linkzmq:zmq_queue[1] - -Forwarder device for publish-subscribe messaging:: - linkzmq:zmq_forwarder[1] - -Streamer device for parallelized pipeline messaging:: - linkzmq:zmq_streamer[1] +0MQ provides 'devices', which are building blocks that act as intermediate +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], +and you can also start devices externally, as standalone processes, see +linkzmq:zmq_deviced[1]. ERROR HANDLING diff --git a/doc/zmq_bind.txt b/doc/zmq_bind.txt index 62c4584..2678ca6 100644 --- a/doc/zmq_bind.txt +++ b/doc/zmq_bind.txt @@ -24,10 +24,15 @@ the underlying transport protocol selected. The following transports are defined: -'inproc':: local in-process (inter-thread) communication transport, see linkzmq:zmq_inproc[7] -'ipc':: local inter-process communication transport, see linkzmq:zmq_ipc[7] -'tcp':: unicast transport using TCP, see linkzmq:zmq_tcp[7] -'pgm', 'epgm':: reliable multicast transport using PGM, see linkzmq:zmq_pgm[7] +'inproc':: + local in-process (inter-thread) communication transport, see + linkzmq:zmq_inproc[7] +'ipc':: + local inter-process communication transport, see linkzmq:zmq_ipc[7] +'tcp':: + unicast transport using TCP, see linkzmq:zmq_tcp[7] +'pgm', 'epgm':: + reliable multicast transport using PGM, see linkzmq:zmq_pgm[7] With the exception of 'ZMQ_PAIR' sockets, a single socket may be connected to multiple endpoints using _zmq_connect()_, while simultaneously accepting diff --git a/doc/zmq_connect.txt b/doc/zmq_connect.txt index 47e0540..6121493 100644 --- a/doc/zmq_connect.txt +++ b/doc/zmq_connect.txt @@ -24,10 +24,15 @@ the underlying transport protocol selected. The following transports are defined: -'inproc':: local in-process (inter-thread) communication transport, see linkzmq:zmq_inproc[7] -'ipc':: local inter-process communication transport, see linkzmq:zmq_ipc[7] -'tcp':: unicast transport using TCP, see linkzmq:zmq_tcp[7] -'pgm', 'epgm':: reliable multicast transport using PGM, see linkzmq:zmq_pgm[7] +'inproc':: + local in-process (inter-thread) communication transport, see + linkzmq:zmq_inproc[7] +'ipc':: + local inter-process communication transport, see linkzmq:zmq_ipc[7] +'tcp':: + unicast transport using TCP, see linkzmq:zmq_tcp[7] +'pgm', 'epgm':: + reliable multicast transport using PGM, see linkzmq:zmq_pgm[7] With the exception of 'ZMQ_PAIR' sockets, a single socket may be connected to multiple endpoints using _zmq_connect()_, while simultaneously accepting diff --git a/doc/zmq_device.txt b/doc/zmq_device.txt index 7797693..e18d2af 100644 --- a/doc/zmq_device.txt +++ b/doc/zmq_device.txt @@ -13,7 +13,8 @@ SYNOPSIS DESCRIPTION ----------- -The _zmq_device()_ function starts a built-in 0MQ device. The 'device' argument is one of: +The _zmq_device()_ function starts a built-in 0MQ device. The 'device' +argument is one of: 'ZMQ_QUEUE':: starts a queue device @@ -22,48 +23,77 @@ The _zmq_device()_ function starts a built-in 0MQ device. The 'device' argument 'ZMQ_STREAMER':: starts a streamer device -The device connects a frontend socket to a backend socket. Conceptually, data flows from frontend to backend. Depending on the socket types, replies may flow in the opposite direction. +The device connects a frontend socket to a backend socket. Conceptually, data +flows from frontend to backend. Depending on the socket types, replies may +flow in the opposite direction. -Before calling _zmq_device()_ you must set any socket options, and connect or bind both frontend and backend sockets. The two conventional device models are: +Before calling _zmq_device()_ you must set any socket options, and connect or +bind both frontend and backend sockets. The two conventional device models +are: *proxy*:: - bind frontend socket to an endpoint, and connect backend socket to downstream components. A proxy device model does not require changes to the downstream topology but that topology is static (any changes require reconfiguring the device). + bind frontend socket to an endpoint, and connect backend socket to + downstream components. A proxy device model does not require changes to + the downstream topology but that topology is static (any changes require + reconfiguring the device). *broker*:: - bind frontend socket to one endpoint and bind backend socket to a second endpoint. Downstream components must now connect into the device. A broker device model allows a dynamic downstream topology (components can come and go at any time). + bind frontend socket to one endpoint and bind backend socket to a second + endpoint. Downstream components must now connect into the device. A + broker device model allows a dynamic downstream topology (components can + come and go at any time). -_zmq_device()_ runs in the current thread and returns only if/when the current context is closed. +_zmq_device()_ runs in the current thread and returns only if/when the current +context is closed. QUEUE DEVICE ------------ -'ZMQ_QUEUE' creates a shared queue that collects requests from a set of clients, and distributes these fairly among a set of services. Requests are fair-queued from frontend connections and load-balanced between backend connections. Replies automatically return to the client that made the original request. +'ZMQ_QUEUE' creates a shared queue that collects requests from a set of +clients, and distributes these fairly among a set of services. Requests are +fair-queued from frontend connections and load-balanced between backend +connections. Replies automatically return to the client that made the original +request. -This device is part of the 'request-reply' pattern. The frontend speaks to clients and the backend speaks to services. You should use 'ZMQ_QUEUE' with a 'ZMQ_XREP' socket for the frontend and a 'ZMQ_XREQ' socket for the backend. Other combinations are not documented. +This device is part of the 'request-reply' pattern. The frontend speaks to +clients and the backend speaks to services. You should use 'ZMQ_QUEUE' with a +'ZMQ_XREP' socket for the frontend and a 'ZMQ_XREQ' socket for the backend. +Other combinations are not documented. Refer to linkzmq:zmq_socket[3] for a description of these socket types. FORWARDER DEVICE ---------------- -'ZMQ_FORWARDER' collects messages from a set of publishers and forwards these to a set of subscribers. You will generally use this to bridge networks, e.g. read on TCP unicast and forward on multicast. +'ZMQ_FORWARDER' collects messages from a set of publishers and forwards these +to a set of subscribers. You will generally use this to bridge networks, e.g. +read on TCP unicast and forward on multicast. -This device is part of the 'publish-subscribe' pattern. The frontend speaks to publishers and the backend speaks to subscribers. You should use 'ZMQ_FORWARDER' with a 'ZMQ_SUB' socket for the frontend and a 'ZMQ_PUB' socket for the backend. Other combinations are not documented. +This device is part of the 'publish-subscribe' pattern. The frontend speaks to +publishers and the backend speaks to subscribers. You should use +'ZMQ_FORWARDER' with a 'ZMQ_SUB' socket for the frontend and a 'ZMQ_PUB' socket +for the backend. Other combinations are not documented. Refer to linkzmq:zmq_socket[3] for a description of these socket types. STREAMER DEVICE --------------- -'ZMQ_STREAMER' collects tasks from a set of pushers and forwards these to a set of pullers. You will generally use this to bridge networks. Messages are fair-queued from pushers and load-balanced to pullers. +'ZMQ_STREAMER' collects tasks from a set of pushers and forwards these to a set +of pullers. You will generally use this to bridge networks. Messages are +fair-queued from pushers and load-balanced to pullers. -This device is part of the 'pipeline' pattern. The frontend speaks to pushers and the backend speaks to pullers. You should use 'ZMQ_STREAMER' with a 'ZMQ_PULL' socket for the frontend and a 'ZMQ_PUSH' socket for the backend. Other combinations are not documented. +This device is part of the 'pipeline' pattern. The frontend speaks to pushers +and the backend speaks to pullers. You should use 'ZMQ_STREAMER' with a +'ZMQ_PULL' socket for the frontend and a 'ZMQ_PUSH' socket for the backend. +Other combinations are not documented. Refer to linkzmq:zmq_socket[3] for a description of these socket types. RETURN VALUE ------------ -The _zmq_device()_ function always returns `-1` and 'errno' set to *ETERM* (the 0MQ 'context' associated with either of the specified sockets was terminated). +The _zmq_device()_ function always returns `-1` and 'errno' set to *ETERM* (the +0MQ 'context' associated with either of the specified sockets was terminated). EXAMPLE diff --git a/doc/zmq_deviced.txt b/doc/zmq_deviced.txt index e5ba83f..fd94c96 100644 --- a/doc/zmq_deviced.txt +++ b/doc/zmq_deviced.txt @@ -14,22 +14,32 @@ SYNOPSIS 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. +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. +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. +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. +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. +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: @@ -52,19 +62,28 @@ The configuration file has this general syntax: ---- *iothreads*:: - specifies the number of I/O threads for the process. Specify this only for high-volume scenarios. See linkzmq:zmq_init[3]. + 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. + 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. + 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. + 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]. + 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]. + 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]. + binds the frontend or backend to the specified endpoint. See + linkzmq:zmq_connect[3]. SOCKET TYPES ------------ @@ -78,9 +97,12 @@ By default 'zmq_device' uses these socket types: *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]. +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. +*Note*: if you use a *sub* socket you must explicitly set a subscription filter +or your socket will not receive any data. EXAMPLE diff --git a/doc/zmq_getsockopt.txt b/doc/zmq_getsockopt.txt index e1cc014..3f131ba 100644 --- a/doc/zmq_getsockopt.txt +++ b/doc/zmq_getsockopt.txt @@ -70,7 +70,7 @@ ZMQ_SWAP: Retrieve disk offload size ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The 'ZMQ_SWAP' option shall retrieve the disk offload (swap) size for the specified 'socket'. A socket which has 'ZMQ_SWAP' set to a non-zero value may -exceed it's high water mark; in this case outstanding messages shall be +exceed its high water mark; in this case outstanding messages shall be offloaded to storage on disk rather than held in memory. The value of 'ZMQ_SWAP' defines the maximum size of the swap space in bytes. diff --git a/doc/zmq_pgm.txt b/doc/zmq_pgm.txt index 862cbd6..abc943e 100644 --- a/doc/zmq_pgm.txt +++ b/doc/zmq_pgm.txt @@ -55,7 +55,7 @@ and a port number. An 'interface' may be specified by either of the following: * The interface name as defined by the operating system. -* The primary IPv4 address assigned to the interface, in it's numeric +* The primary IPv4 address assigned to the interface, in its numeric representation. NOTE: Interface names are not standardised in any way and should be assumed to @@ -63,7 +63,7 @@ be arbitrary and platform dependent. On Win32 platforms no short interface names exist, thus only the primary IPv4 address may be used to specify an 'interface'. -A 'multicast address' is specified by an IPv4 multicast address in it's numeric +A 'multicast address' is specified by an IPv4 multicast address in its numeric representation. diff --git a/doc/zmq_poll.txt b/doc/zmq_poll.txt index 92c5efe..9761881 100644 --- a/doc/zmq_poll.txt +++ b/doc/zmq_poll.txt @@ -100,13 +100,13 @@ associated 0MQ 'context' was terminated. EXAMPLE ------- -.Polling indefinitely for input events on both a 0MQ socket and a standard socket. +.Polling indefinitely for input events on both a 0MQ socket and a TCP socket. ---- zmq_pollitem_t items [2]; /* First item refers to 0MQ socket 'socket' */ items[0].socket = socket; items[0].events = ZMQ_POLLIN; -/* Second item refers to standard socket 'fd' */ +/* Second item refers to TCP socket 'fd' */ items[1].socket = NULL; items[1].fd = fd; items[1].events = ZMQ_POLLIN; diff --git a/doc/zmq_setsockopt.txt b/doc/zmq_setsockopt.txt index 9fef404..c612247 100644 --- a/doc/zmq_setsockopt.txt +++ b/doc/zmq_setsockopt.txt @@ -48,7 +48,7 @@ Applicable socket types:: all ZMQ_SWAP: Set disk offload size ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The 'ZMQ_SWAP' option shall set the disk offload (swap) size for the specified -'socket'. A socket which has 'ZMQ_SWAP' set to a non-zero value may exceed it's +'socket'. A socket which has 'ZMQ_SWAP' set to a non-zero value may exceed its high water mark; in this case outstanding messages shall be offloaded to storage on disk rather than held in memory. diff --git a/doc/zmq_tcp.txt b/doc/zmq_tcp.txt index 29d3543..1713eb4 100644 --- a/doc/zmq_tcp.txt +++ b/doc/zmq_tcp.txt @@ -31,7 +31,8 @@ colon and the TCP port number to use. An 'interface' may be specified by either of the following: * The interface name as defined by the operating system. -* The primary IPv4 address assigned to the interface, in it's numeric representation. +* The primary IPv4 address assigned to the interface, in its numeric + representation. * The wildcard `*`, meaning that the interface address is unspecified. NOTE: Interface names are not standardised in any way and should be assumed to @@ -48,15 +49,15 @@ a colon and the TCP port number to use. A 'peer address' may be specified by either of the following: * The DNS name of the peer. -* The IPv4 address of the peer, in it's numeric representation. +* The IPv4 address of the peer, in its numeric representation. WIRE FORMAT ----------- 0MQ messages are transmitted over TCP in frames consisting of an encoded -'payload length', followed by a 'flags' field and the message body. The 'payload -length' is defined as the combined length in octets of the message body and the -'flags' field. +'payload length', followed by a 'flags' field and the message body. The +'payload length' is defined as the combined length in octets of the message +body and the 'flags' field. For frames with a 'payload length' not exceeding 254 octets, the 'payload length' shall be encoded as a single octet. The minimum valid 'payload length' |