diff --git a/doc/zmq.txt b/doc/zmq.txt index 003570ae..fa15e434 100644 --- a/doc/zmq.txt +++ b/doc/zmq.txt @@ -90,8 +90,8 @@ Standard sockets present a _synchronous_ interface to either connection-mode reliable byte streams (SOCK_STREAM), or connection-less unreliable datagrams (SOCK_DGRAM). In comparison, 0MQ sockets present an abstraction of a asynchronous _message queue_, with the exact queueing semantics depending on -the socket type (_messaging pattern_) in use. See linkzmq:zmq_socket[3] for the -_messaging patterns_ provided. +the socket type in use. See linkzmq:zmq_socket[3] for the socket types +provided. 0MQ sockets being _asynchronous_ means that the timings of the physical connection setup and teardown, reconnect and effective delivery are organized diff --git a/doc/zmq_setsockopt.txt b/doc/zmq_setsockopt.txt index 8845a105..3bc10815 100644 --- a/doc/zmq_setsockopt.txt +++ b/doc/zmq_setsockopt.txt @@ -61,13 +61,13 @@ The 'ZMQ_AFFINITY' option shall set the I/O thread affinity for connections created by subsequent _zmq_connect()_ or _zmq_bind()_ calls on the specified 'socket'. -sockets. Affinity determines which threads from the 0MQ I/O thread pool -associated with the socket's _context_ shall handle newly created connections. -A value of zero specifies no affinity, meaning that work shall be distributed -fairly among all 0MQ I/O threads in the thread pool. For non-zero values, the -lowest bit corresponds to thread 1, second lowest bit to thread 2 and so on. -For example, a value of 3 specifies that subsequent connections on 'socket' -shall be handled exclusively by I/O threads 1 and 2. +Affinity determines which threads from the 0MQ I/O thread pool associated with +the socket's _context_ shall handle newly created connections. A value of zero +specifies no affinity, meaning that work shall be distributed fairly among all +0MQ I/O threads in the thread pool. For non-zero values, the lowest bit +corresponds to thread 1, second lowest bit to thread 2 and so on. For example, +a value of 3 specifies that subsequent connections on 'socket' shall be handled +exclusively by I/O threads 1 and 2. See also linkzmq:zmq_init[3] for details on allocating the number of I/O threads for a specific _context_. diff --git a/doc/zmq_socket.txt b/doc/zmq_socket.txt index e01921c8..ebae5e15 100644 --- a/doc/zmq_socket.txt +++ b/doc/zmq_socket.txt @@ -19,28 +19,8 @@ The 'zmq_socket()' function shall create a 0MQ socket within the specified argument specifies the socket type, which determines the semantics of communication over the socket. -The following _messaging patterns_ are defined: - -Publish-subscribe pattern -~~~~~~~~~~~~~~~~~~~~~~~~~ -The publish-subscribe pattern is used for one-to-many distribution of data from -a single _publisher_ to multiple _subscribers_ in a fanout fashion. - -Socket type:: 'ZMQ_PUB' -Compatible peer sockets:: 'ZMQ_SUB' - -A socket of type 'ZMQ_PUB' is used by a _publisher_ to distribute data. -Messages sent are distributed in a fanout fashion to all connected peers. -The _zmq_recv()_ function is not implemented for this socket type. - -Socket type:: 'ZMQ_SUB' -Compatible peer sockets:: 'ZMQ_PUB' - -A socket of type 'ZMQ_SUB' is used by a _subscriber_ to subscribe to data -distributed by a _publisher_. Initially a 'ZMQ_SUB' socket is not subscribed to -any messages, use the 'ZMQ_SUBSCRIBE' option of _zmq_setsockopt()_ to specify -which messages to subscribe to. The _zmq_send()_ function is not implemented -for this socket type. +The following sections present the socket types defined by 0MQ, grouped by the +general _messaging pattern_ built from related socket types. Request-reply pattern @@ -65,27 +45,68 @@ sequence of _zmq_recv(request)_ and subsequent _zmq_send(reply)_ calls. Each reply is routed to the _client_ that issued the last received request. -Parallelized pipeline pattern -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The parallelized pipeline pattern is used for distributing work between -_components_ of a pipeline. Work travels down the pipeline and at each stage -can be processed by any number of _components_ in parallel. +Publish-subscribe pattern +~~~~~~~~~~~~~~~~~~~~~~~~~ +The publish-subscribe pattern is used for one-to-many distribution of data from +a single _publisher_ to multiple _subscribers_ in a fanout fashion. -Socket type:: 'ZMQ_UPSTREAM' -Compatible peer sockets:: 'ZMQ_DOWNSTREAM' +Socket type:: 'ZMQ_PUB' +Compatible peer sockets:: 'ZMQ_SUB' -A socket of type 'ZMQ_UPSTREAM' is used by a _component_ of a pipeline to -receive messages from upstream stages of the pipeline. Messages are fair-queued -from among all connected upstream _components_. The _zmq_send()_ function is -not implemented for this socket type. +A socket of type 'ZMQ_PUB' is used by a _publisher_ to distribute data. +Messages sent are distributed in a fanout fashion to all connected peers. +The _zmq_recv()_ function is not implemented for this socket type. + +Socket type:: 'ZMQ_SUB' +Compatible peer sockets:: 'ZMQ_PUB' + +A socket of type 'ZMQ_SUB' is used by a _subscriber_ to subscribe to data +distributed by a _publisher_. Initially a 'ZMQ_SUB' socket is not subscribed to +any messages, use the 'ZMQ_SUBSCRIBE' option of _zmq_setsockopt()_ to specify +which messages to subscribe to. The _zmq_send()_ function is not implemented +for this socket type. + + +Pipeline pattern +~~~~~~~~~~~~~~~~ +The pipeline pattern is used for distributing data to _nodes_ arranged in +a pipeline. Data always flows *down* the pipeline, and each stage of the +pipeline is connected to at least one _node_. When a pipeline stage is +connected to multiple _nodes_ data is processed by all connected _nodes_ in +parallel. Socket type:: 'ZMQ_DOWNSTREAM' Compatible peer sockets:: 'ZMQ_UPSTREAM' -A socket of type 'ZMQ_DOWNSTREAM' is used by a _component_ of a pipeline to -send messages to downstream stages of the pipeline. Messages are load-balanced -to all connected downstream _components_. The _zmq_recv()_ function is not -implemented for this socket type. +A socket of type 'ZMQ_DOWNSTREAM' is used by a pipeline _node_ to send messages +to downstream pipeline _nodes_. Messages are load-balanced to all connected +downstream _nodes_. The _zmq_recv()_ function is not implemented for this +socket type. + +Socket type:: 'ZMQ_UPSTREAM' +Compatible peer sockets:: 'ZMQ_DOWNSTREAM' + +A socket of type 'ZMQ_UPSTREAM' is used by a pipeline _node_ to receive +messages from upstream pipeline _nodes_. Messages are fair-queued from among +all connected upstream _nodes_. The _zmq_send()_ function is not implemented +for this socket type. + + +Exclusive pair pattern +~~~~~~~~~~~~~~~~~~~~~~ +The exclusive pair pattern is used for communicating exclusively between two +peers. + +Socket type:: 'ZMQ_PAIR' +Compatible peer sockets:: 'ZMQ_PAIR' + +A socket of type 'ZMQ_PAIR' can only be connected to a single peer at any one +time. No message routing or filtering is performed on messages sent over a +'ZMQ_PAIR' socket. + +NOTE: 'ZMQ_PAIR' sockets are experimental, and are currently missing several +features such as auto-reconnection. Developers should consider other patterns +in preference to the exclusive pair pattern. RETURN VALUE