Clarify socket types in documentation, reinstate ZMQ_PAIR

1 files changed, 56 insertions, 35 deletions

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