Clarify socket types in documentation, reinstate ZMQ_PAIR

3 files changed, 65 insertions, 44 deletions

diff --git a/doc/zmq.txt b/doc/zmq.txt
index 003570a..fa15e43 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 8845a10..3bc1081 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 e01921c..ebae5e1 100644
--- a/doc/zmq_socket.txt
+++ b/doc/zmq_socket.txt
@@ -19,7 +19,31 @@ 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:
+The following sections present the socket types defined by 0MQ, grouped by the
+general _messaging pattern_ built from related socket types.
+
+
+Request-reply pattern
+~~~~~~~~~~~~~~~~~~~~~
+The request-reply pattern is used for sending requests from a _client_ to a
+_service_, and receiving subsequent replies to each request sent.
+
+Socket type:: 'ZMQ_REQ'
+Compatible peer sockets:: 'ZMQ_REP'
+
+A socket of type 'ZMQ_REQ' is used by a _client_ to send requests to and
+receive replies from a _service_. This socket type allows only an alternating
+sequence of _zmq_send(request)_ and subsequent _zmq_recv(reply)_ calls. Each
+request sent is load-balanced among all connected _services_.
+
+Socket type:: 'ZMQ_REP'
+Compatible peer sockets:: 'ZMQ_REQ'
+
+A socket of type 'ZMQ_REP' is used by a _service_ to receive requests from and
+send replies to a _client_.  This socket type allows only an alternating
+sequence of _zmq_recv(request)_ and subsequent _zmq_send(reply)_ calls. Each
+reply is routed to the _client_ that issued the last received request.
+
 
 Publish-subscribe pattern
 ~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -43,49 +67,46 @@ which messages to subscribe to. The _zmq_send()_ function is not implemented
 for this socket type.
 
 
-Request-reply pattern
-~~~~~~~~~~~~~~~~~~~~~
-The request-reply pattern is used for sending requests from a _client_ to a
-_service_, and receiving subsequent replies to each request sent.
-
-Socket type:: 'ZMQ_REQ'
-Compatible peer sockets:: 'ZMQ_REP'
+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.
 
-A socket of type 'ZMQ_REQ' is used by a _client_ to send requests to and
-receive replies from a _service_. This socket type allows only an alternating
-sequence of _zmq_send(request)_ and subsequent _zmq_recv(reply)_ calls. Each
-request sent is load-balanced among all connected _services_.
+Socket type:: 'ZMQ_DOWNSTREAM'
+Compatible peer sockets:: 'ZMQ_UPSTREAM'
 
-Socket type:: 'ZMQ_REP'
-Compatible peer sockets:: 'ZMQ_REQ'
+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.
 
-A socket of type 'ZMQ_REP' is used by a _service_ to receive requests from and
-send replies to a _client_.  This socket type allows only an alternating
-sequence of _zmq_recv(request)_ and subsequent _zmq_send(reply)_ calls. Each
-reply is routed to the _client_ that issued the last received request.
+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.
 
-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.
 
-Socket type:: 'ZMQ_UPSTREAM'
-Compatible peer sockets:: 'ZMQ_DOWNSTREAM'
+Exclusive pair pattern
+~~~~~~~~~~~~~~~~~~~~~~
+The exclusive pair pattern is used for communicating exclusively between two
+peers.
 
-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.
+Socket type:: 'ZMQ_PAIR'
+Compatible peer sockets:: 'ZMQ_PAIR'
 
-Socket type:: 'ZMQ_DOWNSTREAM'
-Compatible peer sockets:: 'ZMQ_UPSTREAM'
+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.
 
-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.
+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