Problem: request-reply pattern is lousy

REQ-REP barely work, and DEALER-ROUTER are misnamed. As we move to
formalizing CLIENT-SERVER, we can deprecate request-reply.

Solution: move this section to the end of the man page, and mark as
"will be deprecated".

doc/zmq_socket.txt

@@ -128,114 +128,6 @@ Incoming routing strategy:: Fair-queued
 Action in mute state:: Return EAGAIN
 
 
-Request-reply pattern
-~~~~~~~~~~~~~~~~~~~~~
-The request-reply pattern is used for sending requests from a ZMQ_REQ _client_
-to one or more ZMQ_REP _services_, and receiving subsequent replies to each
-request sent.
-
-The request-reply pattern is formally defined by http://rfc.zeromq.org/spec:28.
-
-ZMQ_REQ
-^^^^^^^
-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 round-robined among all _services_, and each reply received is
-matched with the last issued request.
-
-If no services are available, then any send operation on the socket shall
-block until at least one _service_ becomes available. The REQ socket shall
-not discard messages.
-
-[horizontal]
-.Summary of ZMQ_REQ characteristics
-Compatible peer sockets:: 'ZMQ_REP', 'ZMQ_ROUTER'
-Direction:: Bidirectional
-Send/receive pattern:: Send, Receive, Send, Receive, ...
-Outgoing routing strategy:: Round-robin
-Incoming routing strategy:: Last peer
-Action in mute state:: Block
-
-
-ZMQ_REP
-^^^^^^^
-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
-request received is fair-queued from among all _clients_, and each reply sent
-is routed to the _client_ that issued the last request. If the original
-requester does not exist any more the reply is silently discarded.
-
-[horizontal]
-.Summary of ZMQ_REP characteristics
-Compatible peer sockets:: 'ZMQ_REQ', 'ZMQ_DEALER'
-Direction:: Bidirectional
-Send/receive pattern:: Receive, Send, Receive, Send, ...
-Incoming routing strategy:: Fair-queued
-Outgoing routing strategy:: Last peer
-
-
-ZMQ_DEALER
-^^^^^^^^^^
-A socket of type 'ZMQ_DEALER' is an advanced pattern used for extending
-request/reply sockets. Each message sent is round-robined among all connected
-peers, and each message received is fair-queued from all connected peers.
-
-When a 'ZMQ_DEALER' socket enters the 'mute' state due to having reached the
-high water mark for all peers, or if there are no peers at all, then any
-linkzmq:zmq_send[3] operations on the socket shall block until the mute
-state ends or at least one peer becomes available for sending; messages are not
-discarded.
-
-When a 'ZMQ_DEALER' socket is connected to a 'ZMQ_REP' socket each message sent
-must consist of an empty message part, the _delimiter_, followed by one or more
-_body parts_.
-
-[horizontal]
-.Summary of ZMQ_DEALER characteristics
-Compatible peer sockets:: 'ZMQ_ROUTER', 'ZMQ_REP', 'ZMQ_DEALER'
-Direction:: Bidirectional
-Send/receive pattern:: Unrestricted
-Outgoing routing strategy:: Round-robin
-Incoming routing strategy:: Fair-queued
-Action in mute state:: Block
-
-
-ZMQ_ROUTER
-^^^^^^^^^^
-A socket of type 'ZMQ_ROUTER' is an advanced socket type used for extending
-request/reply sockets. When receiving messages a 'ZMQ_ROUTER' socket shall
-prepend a message part containing the _identity_ of the originating peer to the
-message before passing it to the application. Messages received are fair-queued
-from among all connected peers. When sending messages a 'ZMQ_ROUTER' socket shall
-remove the first part of the message and use it to determine the _identity_ of
-the peer the message shall be routed to. If the peer does not exist anymore
-the message shall be silently discarded by default, unless 'ZMQ_ROUTER_MANDATORY'
-socket option is set to '1'.
-
-When a 'ZMQ_ROUTER' socket enters the 'mute' state due to having reached the
-high water mark for all peers, then any messages sent to the socket shall be dropped
-until the mute state ends. Likewise, any messages routed to a peer for which
-the individual high water mark has been reached shall also be dropped.
-
-When a 'ZMQ_REQ' socket is connected to a 'ZMQ_ROUTER' socket, in addition to the
-_identity_ of the originating peer each message received shall contain an empty
-_delimiter_ message part. Hence, the entire structure of each received message
-as seen by the application becomes: one or more _identity_ parts, _delimiter_
-part, one or more _body parts_. When sending replies to a 'ZMQ_REQ' socket the
-application must include the _delimiter_ part.
-
-[horizontal]
-.Summary of ZMQ_ROUTER characteristics
-Compatible peer sockets:: 'ZMQ_DEALER', 'ZMQ_REQ', 'ZMQ_ROUTER'
-Direction:: Bidirectional
-Send/receive pattern:: Unrestricted
-Outgoing routing strategy:: See text
-Incoming routing strategy:: Fair-queued
-Action in mute state:: Drop
-
-
 Publish-subscribe pattern
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 The publish-subscribe pattern is used for one-to-many distribution of data from
@@ -445,6 +337,116 @@ Incoming routing strategy:: Fair-queued
 Action in mute state:: EAGAIN
 
 
+Request-reply pattern
+~~~~~~~~~~~~~~~~~~~~~
+The request-reply pattern is used for sending requests from a ZMQ_REQ _client_
+to one or more ZMQ_REP _services_, and receiving subsequent replies to each
+request sent.
+
+The request-reply pattern is formally defined by http://rfc.zeromq.org/spec:28.
+
+Note: this pattern will be deprecated in favor of the client-server pattern.
+
+ZMQ_REQ
+^^^^^^^
+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 round-robined among all _services_, and each reply received is
+matched with the last issued request.
+
+If no services are available, then any send operation on the socket shall
+block until at least one _service_ becomes available. The REQ socket shall
+not discard messages.
+
+[horizontal]
+.Summary of ZMQ_REQ characteristics
+Compatible peer sockets:: 'ZMQ_REP', 'ZMQ_ROUTER'
+Direction:: Bidirectional
+Send/receive pattern:: Send, Receive, Send, Receive, ...
+Outgoing routing strategy:: Round-robin
+Incoming routing strategy:: Last peer
+Action in mute state:: Block
+
+
+ZMQ_REP
+^^^^^^^
+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
+request received is fair-queued from among all _clients_, and each reply sent
+is routed to the _client_ that issued the last request. If the original
+requester does not exist any more the reply is silently discarded.
+
+[horizontal]
+.Summary of ZMQ_REP characteristics
+Compatible peer sockets:: 'ZMQ_REQ', 'ZMQ_DEALER'
+Direction:: Bidirectional
+Send/receive pattern:: Receive, Send, Receive, Send, ...
+Incoming routing strategy:: Fair-queued
+Outgoing routing strategy:: Last peer
+
+
+ZMQ_DEALER
+^^^^^^^^^^
+A socket of type 'ZMQ_DEALER' is an advanced pattern used for extending
+request/reply sockets. Each message sent is round-robined among all connected
+peers, and each message received is fair-queued from all connected peers.
+
+When a 'ZMQ_DEALER' socket enters the 'mute' state due to having reached the
+high water mark for all peers, or if there are no peers at all, then any
+linkzmq:zmq_send[3] operations on the socket shall block until the mute
+state ends or at least one peer becomes available for sending; messages are not
+discarded.
+
+When a 'ZMQ_DEALER' socket is connected to a 'ZMQ_REP' socket each message sent
+must consist of an empty message part, the _delimiter_, followed by one or more
+_body parts_.
+
+[horizontal]
+.Summary of ZMQ_DEALER characteristics
+Compatible peer sockets:: 'ZMQ_ROUTER', 'ZMQ_REP', 'ZMQ_DEALER'
+Direction:: Bidirectional
+Send/receive pattern:: Unrestricted
+Outgoing routing strategy:: Round-robin
+Incoming routing strategy:: Fair-queued
+Action in mute state:: Block
+
+
+ZMQ_ROUTER
+^^^^^^^^^^
+A socket of type 'ZMQ_ROUTER' is an advanced socket type used for extending
+request/reply sockets. When receiving messages a 'ZMQ_ROUTER' socket shall
+prepend a message part containing the _identity_ of the originating peer to the
+message before passing it to the application. Messages received are fair-queued
+from among all connected peers. When sending messages a 'ZMQ_ROUTER' socket shall
+remove the first part of the message and use it to determine the _identity_ of
+the peer the message shall be routed to. If the peer does not exist anymore
+the message shall be silently discarded by default, unless 'ZMQ_ROUTER_MANDATORY'
+socket option is set to '1'.
+
+When a 'ZMQ_ROUTER' socket enters the 'mute' state due to having reached the
+high water mark for all peers, then any messages sent to the socket shall be dropped
+until the mute state ends. Likewise, any messages routed to a peer for which
+the individual high water mark has been reached shall also be dropped.
+
+When a 'ZMQ_REQ' socket is connected to a 'ZMQ_ROUTER' socket, in addition to the
+_identity_ of the originating peer each message received shall contain an empty
+_delimiter_ message part. Hence, the entire structure of each received message
+as seen by the application becomes: one or more _identity_ parts, _delimiter_
+part, one or more _body parts_. When sending replies to a 'ZMQ_REQ' socket the
+application must include the _delimiter_ part.
+
+[horizontal]
+.Summary of ZMQ_ROUTER characteristics
+Compatible peer sockets:: 'ZMQ_DEALER', 'ZMQ_REQ', 'ZMQ_ROUTER'
+Direction:: Bidirectional
+Send/receive pattern:: Unrestricted
+Outgoing routing strategy:: See text
+Incoming routing strategy:: Fair-queued
+Action in mute state:: Drop
+
+
 RETURN VALUE
 ------------
 The _zmq_socket()_ function shall return an opaque handle to the newly created