Fixed doc to clarify how label parts work

Signed-off-by: Pieter Hintjens <ph@imatix.com>
Signed-off-by: Martin Sustrik <sustrik@250bpm.com>

6 files changed, 134 insertions, 115 deletions

diff --git a/doc/zmq_getsockopt.txt b/doc/zmq_getsockopt.txt
index 5e3051e..ba85ab3 100644
--- a/doc/zmq_getsockopt.txt
+++ b/doc/zmq_getsockopt.txt
@@ -39,16 +39,11 @@ Default value:: N/A
 Applicable socket types:: all
 
 
-ZMQ_RCVMORE: More message parts to follow
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The 'ZMQ_RCVMORE' option shall return a boolean value indicating if the
-multi-part message currently being read from the specified 'socket' has more
-message parts to follow. If there are no message parts to follow or if the
-message currently being read is not a multi-part message a value of zero shall
-be returned. Otherwise, a value of 1 shall be returned.
-
-Refer to linkzmq:zmq_send[3] and linkzmq:zmq_recv[3] for a detailed description
-of sending/receiving multi-part messages.
+ZMQ_RCVLABEL: Inquires whether last message received was a label
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The 'ZMQ_RCVLABEL' option shall return True (1) if the message part last
+received from the 'socket' was an address label. Otherwise, this option
+shall return False (0).
 
 [horizontal]
 Option value type:: int
@@ -57,10 +52,14 @@ Default value:: N/A
 Applicable socket types:: all
 
 
-ZMQ_RCVLABEL: Inquires whether last message received was a label
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The 'ZMQ_RCVLABEL' option shall return a boolean value indicating whether the
-last message part received was a label. Labels are used internally by 0MQ.
+ZMQ_RCVMORE: More message data parts to follow
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The 'ZMQ_RCVMORE' option shall return True (1) if the message part last
+received from the 'socket' was a data part with more parts to follow. If there
+are no data parts to follow, this option shall return False (0).
+
+Refer to linkzmq:zmq_send[3] and linkzmq:zmq_recv[3] for a detailed description
+of multi-part messages.
 
 [horizontal]
 Option value type:: int
diff --git a/doc/zmq_recv.txt b/doc/zmq_recv.txt
index f09d298..c9c3ce8 100644
--- a/doc/zmq_recv.txt
+++ b/doc/zmq_recv.txt
@@ -4,7 +4,7 @@ zmq_recv(3)
 
 NAME
 ----
-zmq_recv - receive a message from a socket
+zmq_recv - receive a message part from a socket
 
 
 SYNOPSIS
@@ -29,19 +29,18 @@ function shall fail with 'errno' set to EAGAIN.
 
 Multi-part messages
 ~~~~~~~~~~~~~~~~~~~
-A 0MQ message is composed of 1 or more message parts. 0MQ ensures atomic
+A 0MQ message is composed of 1 or more message parts, starting with zero or
+more address 'label' parts, followed by 1 or more 'data' parts. Each message
+part is an independent 'zmq_msg_t' in its own right. 0MQ ensures atomic
 delivery of messages; peers shall receive either all _message parts_ of a
-message or none at all.
-
-The total number of message parts is unlimited.
-
-An application wishing to determine if a message is composed of multiple parts
-does so by retrieving the value of the _ZMQ_RCVMORE_ socket option on the
-'socket' it is receiving the message from. If there are no message parts to
-follow, or if the message is not composed of multiple parts, _ZMQ_RCVMORE_
-shall report a value of zero. Otherwise, _ZMQ_RCVMORE_ shall report a value of
-1, indicating that more message parts are to follow.
+message or none at all. The total number of message parts is unlimited except
+by available memory.
 
+An application that processes multipart messages must use the _ZMQ_RCVMORE_
+linkzmq:zmq_getsockopt[3] option after calling _zmq_recv()_ to determine if
+there are further parts to receive. An application that manipulates address
+labels must use _ZMQ_RCVLABEL_ to determine the zero or more label parts
+that precede the data part(s).
 
 RETURN VALUE
 ------------
@@ -93,5 +92,6 @@ linkzmq:zmq[7]
 
 AUTHORS
 -------
-The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
-Martin Lucina <mato@kotelna.sk>.
++This man page was written by Martin Sustrik <sustrik@250bpm.com>, Martin
++Lucina <mato@kotelna.sk> and Pieter Hintjens <ph@imatix.com>.
+
diff --git a/doc/zmq_recvmsg.txt b/doc/zmq_recvmsg.txt
index 640768a..358ea3f 100644
--- a/doc/zmq_recvmsg.txt
+++ b/doc/zmq_recvmsg.txt
@@ -4,7 +4,7 @@ zmq_recvmsg(3)
 
 NAME
 ----
-zmq_recvmsg - receive a message from a socket
+zmq_recvmsg - receive a message part from a socket
 
 
 SYNOPSIS
@@ -14,12 +14,12 @@ SYNOPSIS
 
 DESCRIPTION
 -----------
-The _zmq_recvmsg()_ function shall receive a message from the socket referenced
-by the 'socket' argument and store it in the message referenced by the 'msg'
-argument. Any content previously stored in 'msg' shall be properly deallocated.
-If there are no messages available on the specified 'socket' the _zmq_recvmsg()_
-function shall block until the request can be satisfied. The 'flags' argument
-is a combination of the flags defined below:
+The _zmq_recvmsg()_ function shall receive a message part from the socket
+referenced by the 'socket' argument and store it in the message referenced by
+the 'msg' argument. Any content previously stored in 'msg' shall be properly
+deallocated. If there are no message parts available on the specified 'socket'
+the _zmq_recvmsg()_ function shall block until the request can be satisfied.
+The 'flags' argument is a combination of the flags defined below:
 
 *ZMQ_DONTWAIT*::
 Specifies that the operation should be performed in non-blocking mode. If there
@@ -29,19 +29,18 @@ function shall fail with 'errno' set to EAGAIN.
 
 Multi-part messages
 ~~~~~~~~~~~~~~~~~~~
-A 0MQ message is composed of 1 or more message parts; each message part is an
-independent 'zmq_msg_t' in its own right. 0MQ ensures atomic delivery of
-messages; peers shall receive either all _message parts_ of a message or none
-at all.
+A 0MQ message is composed of 1 or more message parts, starting with zero or
+more address 'label' parts, followed by 1 or more 'data' parts. Each message
+part is an independent 'zmq_msg_t' in its own right. 0MQ ensures atomic
+delivery of messages; peers shall receive either all _message parts_ of a
+message or none at all. The total number of message parts is unlimited except
+by available memory.
 
-The total number of message parts is unlimited.
-
-An application wishing to determine if a message is composed of multiple parts
-does so by retrieving the value of the _ZMQ_RCVMORE_ socket option on the
-'socket' it is receiving the message from. If there are no message parts to
-follow, or if the message is not composed of multiple parts, _ZMQ_RCVMORE_
-shall report a value of zero. Otherwise, _ZMQ_RCVMORE_ shall report a value of
-1, indicating that more message parts are to follow.
+An application that processes multipart messages must use the _ZMQ_RCVMORE_
+linkzmq:zmq_getsockopt[3] option after calling _zmq_recvmsg()_ to determine if
+there are further parts to receive. An application that manipulates address
+labels must use _ZMQ_RCVLABEL_ to determine the zero or more label parts
+that precede the data part(s).
 
 
 RETURN VALUE
@@ -120,5 +119,6 @@ linkzmq:zmq[7]
 
 AUTHORS
 -------
-The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
-Martin Lucina <mato@kotelna.sk>.
+This man page was written by Martin Sustrik <sustrik@250bpm.com>, Martin
+Lucina <mato@kotelna.sk> and Pieter Hintjens <ph@imatix.com>.
+
diff --git a/doc/zmq_send.txt b/doc/zmq_send.txt
index c631113..133de97 100644
--- a/doc/zmq_send.txt
+++ b/doc/zmq_send.txt
@@ -4,7 +4,7 @@ zmq_send(3)
 
 NAME
 ----
-zmq_send - send a message on a socket
+zmq_send - send a message part  on a socket
 
 
 SYNOPSIS
@@ -23,15 +23,16 @@ Specifies that the operation should be performed in non-blocking mode. If the
 message cannot be queued on the 'socket', the _zmq_send()_ function shall
 fail with 'errno' set to EAGAIN.
 
+*ZMQ_SNDLABEL*::
+Specifies that the message part being sent is an address label, and that
+further message parts are to follow. Refer to linkzmq:zmq_socket[3] for the
+semantics of address labels in each socket pattern.
+
 *ZMQ_SNDMORE*::
 Specifies that the message being sent is a multi-part message, and that further
 message parts are to follow. Refer to the section regarding multi-part messages
 below for a detailed description.
 
-*ZMQ_SNDLABEL*::
-Specifies that the message being sent is a label. Labels are used internally
-by 0MQ.
-
 NOTE: A successful invocation of _zmq_send()_ does not indicate that the
 message has been transmitted to the network, only that it has been queued on
 the 'socket' and 0MQ has assumed responsibility for the message.
@@ -39,19 +40,16 @@ the 'socket' and 0MQ has assumed responsibility for the message.
 
 Multi-part messages
 ~~~~~~~~~~~~~~~~~~~
-A 0MQ message is composed of 1 or more message parts; each invocation of
-_zmq_send()_ creates an independent message part in its own right. 0MQ ensures
-atomic delivery of messages; peers shall receive either all _message parts_ of
-a message or none at all.
-
-The total number of message parts is unlimited.
+A 0MQ message is composed of 1 or more message parts, starting with zero or
+more address 'label' parts, followed by 1 or more 'data' parts. Each message
+part is an independent 'zmq_msg_t' in its own right. 0MQ ensures atomic
+delivery of messages; peers shall receive either all _message parts_ of a
+message or none at all. The total number of message parts is unlimited except
+by available memory.
 
-An application wishing to send a multi-part message does so by specifying the
-'ZMQ_SNDMORE' flag to _zmq_send()_. The presence of this flag indicates to
-0MQ that the message being sent is a multi-part message and that more message
-parts are to follow. When the application wishes to send the final message part
-it does so by calling _zmq_send()_ without the 'ZMQ_SNDMORE' flag; this
-indicates that no more message parts are to follow.
+An application that sends multipart messages must use the _ZMQ_SNDMORE_ flag
+when sending each data part except the final one. An application that sends
+address labels must use _ZMQ_SNDLABEL_ when sending each label.
 
 
 RETURN VALUE
@@ -109,5 +107,6 @@ linkzmq:zmq[7]
 
 AUTHORS
 -------
-The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
-Martin Lucina <mato@kotelna.sk>.
++This man page was written by Martin Sustrik <sustrik@250bpm.com>, Martin
++Lucina <mato@kotelna.sk> and Pieter Hintjens <ph@imatix.com>.
+
diff --git a/doc/zmq_sendmsg.txt b/doc/zmq_sendmsg.txt
index 7995304..244c0bd 100644
--- a/doc/zmq_sendmsg.txt
+++ b/doc/zmq_sendmsg.txt
@@ -4,7 +4,7 @@ zmq_sendmsg(3)
 
 NAME
 ----
-zmq_sendmsg - send a message on a socket
+zmq_sendmsg - send a message part on a socket
 
 
 SYNOPSIS
@@ -23,15 +23,16 @@ Specifies that the operation should be performed in non-blocking mode. If the
 message cannot be queued on the 'socket', the _zmq_sendmsg()_ function shall
 fail with 'errno' set to EAGAIN.
 
+*ZMQ_SNDLABEL*::
+Specifies that the message part being sent is an address 'label', and that
+further message parts are to follow. Refer to linkzmq:zmq_socket[3] for the
+semantics of address labels in each socket pattern.
+
 *ZMQ_SNDMORE*::
 Specifies that the message being sent is a multi-part message, and that further
 message parts are to follow. Refer to the section regarding multi-part messages
 below for a detailed description.
 
-*ZMQ_SNDLABEL*::
-Specifies that the message being sent is a label. Labels are used internally
-by 0MQ.
-
 The _zmq_msg_t_ structure passed to _zmq_sendmsg()_ is nullified during the
 call. If you want to send the same message to multiple sockets you have to copy
 it using (e.g. using _zmq_msg_copy()_).
@@ -43,20 +44,16 @@ the 'socket' and 0MQ has assumed responsibility for the message.
 
 Multi-part messages
 ~~~~~~~~~~~~~~~~~~~
-A 0MQ message is composed of 1 or more message parts; each message part is an
-independent 'zmq_msg_t' in its own right. 0MQ ensures atomic delivery of
-messages; peers shall receive either all _message parts_ of a message or none
-at all.
-
-The total number of message parts is unlimited.
-
-An application wishing to send a multi-part message does so by specifying the
-'ZMQ_SNDMORE' flag to _zmq_sendmsg()_. The presence of this flag indicates to
-0MQ that the message being sent is a multi-part message and that more message
-parts are to follow. When the application wishes to send the final message part
-it does so by calling _zmq_sendmsg()_ without the 'ZMQ_SNDMORE' flag; this
-indicates that no more message parts are to follow.
+A 0MQ message is composed of 1 or more message parts, starting with zero or
+more address 'label' parts, followed by 1 or more 'data' parts. Each message
+part is an independent 'zmq_msg_t' in its own right. 0MQ ensures atomic
+delivery of messages; peers shall receive either all _message parts_ of a
+message or none at all. The total number of message parts is unlimited except
+by available memory.
 
+An application that sends multipart messages must use the _ZMQ_SNDMORE_ flag
+when sending each data part except the final one. An application that sends
+address labels must use _ZMQ_SNDLABEL_ when sending each label.
 
 RETURN VALUE
 ------------
@@ -126,5 +123,6 @@ linkzmq:zmq[7]
 
 AUTHORS
 -------
-The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
-Martin Lucina <mato@kotelna.sk>.
++This man page was written by Martin Sustrik <sustrik@250bpm.com>, Martin
++Lucina <mato@kotelna.sk> and Pieter Hintjens <ph@imatix.com>.
+
diff --git a/doc/zmq_socket.txt b/doc/zmq_socket.txt
index 91b74ea..e138ebe 100644
--- a/doc/zmq_socket.txt
+++ b/doc/zmq_socket.txt
@@ -52,15 +52,19 @@ from multiple threads except after migrating a socket from one thread to
 another with a "full fence" memory barrier.
 
 .Socket types
-The following sections present the socket types defined by 0MQ, grouped by the
-general _messaging pattern_ which is built from related socket types.
+0MQ defines several messaging patterns which encapsulate exact semantics of
+a particular topology. For example, publush-subscribe pattern defines data
+distribution trees while request-reply defines networks of shared stateless
+services. Each pattern defines several socket types (roles in the pattern).
+
+The following sections present the socket types defined by 0MQ:
 
 
 Request-reply pattern
 ~~~~~~~~~~~~~~~~~~~~~
 The request-reply pattern is used for sending requests from a _client_ to one
-or more instances of a _service_, and receiving subsequent replies to each
-request sent.
+or more instances of a stateless _service_, and receiving subsequent replies
+to each request sent.
 
 
 ZMQ_REQ
@@ -77,6 +81,11 @@ any linkzmq:zmq_send[3] operations on the socket shall block until the
 exceptional state ends or at least one _service_ becomes available for sending;
 messages are not discarded.
 
+'ZMQ_REQ' socket adds a unique 'request ID' label to every outbound message.
+When receiving a reply, it checks whether the 'request ID' of the reply matches
+the last 'request ID' sent. If it does not, the message is silently dropped and
+waiting for the reply is resumed.
+
 [horizontal]
 .Summary of ZMQ_REQ characteristics
 Compatible peer sockets:: 'ZMQ_REP'
@@ -99,6 +108,10 @@ When a 'ZMQ_REP' socket enters an exceptional state due to having reached the
 high water mark for a _client_, then any replies sent to the _client_ in
 question shall be dropped until the exceptional state ends.
 
+'ZMQ_REP' socket strips all the labels from the incoming message, stores them
+and passes the remaining data parts to the user. When user sends the reply,
+the stored labels are re-attached to the reply.
+
 [horizontal]
 .Summary of ZMQ_REP characteristics
 Compatible peer sockets:: 'ZMQ_REQ'
@@ -110,8 +123,11 @@ ZMQ_HWM option action:: Drop
 
 ZMQ_XREQ
 ^^^^^^^^
-A socket of type 'ZMQ_XREQ' is an advanced pattern used for extending
-request/reply sockets. Each message sent is load-balanced among all connected
+A socket of type 'ZMQ_XREQ' is a socket type underlying 'ZMQ_REQ'. It doesn't
+impose the strict order of sends and recvs as 'ZMQ_REQ' does and it is
+intended for use in intermediate devices in request-reply topologies.
+
+Each message sent is load-balanced among all connected
 peers, and each message received is fair-queued from all connected peers.
 
 When a 'ZMQ_XREQ' socket enters an exceptional state due to having reached the
@@ -120,9 +136,7 @@ linkzmq:zmq_send[3] operations on the socket shall block until the exceptional
 state ends or at least one peer becomes available for sending; messages are not
 discarded.
 
-When a 'ZMQ_XREQ' 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_.
+'ZMQ_XREQ' socket doesn't inspect or modify the message labels.
 
 [horizontal]
 .Summary of ZMQ_XREQ characteristics
@@ -135,27 +149,26 @@ ZMQ_HWM option action:: Block
 
 ZMQ_XREP
 ^^^^^^^^
-A socket of type 'ZMQ_XREP' is an advanced pattern used for extending
-request/reply sockets. When receiving messages a 'ZMQ_XREP' 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_XREP' 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.
+A socket of type 'ZMQ_XREP' is a socket type underlying 'ZMQ_REP'. It doesn't
+impose the strict order of sends and recvs as 'ZMQ_REQ' does and it is
+intended for use in intermediate devices in request-reply topologies.
+
+Messages received are fair-queued from among all connected peers. The outbound
+messages are routed to a specific peer, as explained below.
 
 When a 'ZMQ_XREP' socket enters an exceptional state due to having reached the
 high water mark for all peers, or if there are no peers at all, then any
 messages sent to the socket shall be dropped until the exceptional state ends.
-Likewise, any messages routed to a non-existent peer or a peer for which the
-individual high water mark has been reached shall also be dropped.
+Likewise, any messages to be routed to a non-existent peer or a peer for which
+the individual high water mark has been reached shall also be dropped.
+
+When receiving messages a 'ZMQ_XREP' socket attaches a label uniquely
+identifying the originating peer to the message before passing it to the
+application. 
 
-When a 'ZMQ_REQ' socket is connected to a 'ZMQ_XREP' 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.
+When sending messages a 'ZMQ_XREP' socket removes the first label from the
+message and uses it to determine which the peer the message shall be routed to.
+If the peer does not exist anymore the message is silently discarded.
 
 [horizontal]
 .Summary of ZMQ_XREP characteristics
@@ -183,6 +196,8 @@ high water mark for a _subscriber_, then any messages that would be sent to the
 _subscriber_ in question shall instead be dropped until the exceptional state
 ends. The _zmq_send()_ function shall never block for this socket type.
 
+This socket type doesn't use message labels.
+
 [horizontal]
 .Summary of ZMQ_PUB characteristics
 Compatible peer sockets:: 'ZMQ_SUB', 'ZMQ_XSUB'
@@ -200,6 +215,8 @@ any messages, use the 'ZMQ_SUBSCRIBE' option of linkzmq:zmq_setsockopt[3] to
 specify which messages to subscribe to. The _zmq_send()_ function is not
 implemented for this socket type.
 
+This socket type doesn't use message labels.
+
 [horizontal]
 .Summary of ZMQ_SUB characteristics
 Compatible peer sockets:: 'ZMQ_PUB', 'ZMQ_XPUB'
@@ -216,6 +233,8 @@ in form of incoming messages. Subscription message is a byte 1 (for
 subscriptions) or byte 0 (for unsubscriptions) followed by the subscription
 body.
 
+This socket type doesn't use message labels.
+
 [horizontal]
 .Summary of ZMQ_XPUB characteristics
 Compatible peer sockets:: 'ZMQ_SUB', 'ZMQ_XSUB'
@@ -231,6 +250,8 @@ Same as ZMQ_SUB except that you subscribe by sending subscription messages to
 the socket. Subscription message is a byte 1 (for subscriptions) or byte 0
 (for unsubscriptions) followed by the subscription body.
 
+This socket type doesn't use message labels.
+
 [horizontal]
 .Summary of ZMQ_XSUB characteristics
 Compatible peer sockets:: 'ZMQ_PUB', 'ZMQ_XPUB'
@@ -261,7 +282,7 @@ _nodes_ at all, then any linkzmq:zmq_send[3] operations on the socket shall
 block until the exceptional state ends or at least one downstream _node_
 becomes available for sending; messages are not discarded.
 
-Deprecated alias: 'ZMQ_DOWNSTREAM'.
+This socket type doesn't use message labels.
 
 [horizontal]
 .Summary of ZMQ_PUSH characteristics
@@ -280,7 +301,7 @@ 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.
 
-Deprecated alias: 'ZMQ_UPSTREAM'.
+This socket type doesn't use message labels.
 
 [horizontal]
 .Summary of ZMQ_PULL characteristics
@@ -309,6 +330,8 @@ high water mark for the connected peer, or if no peer is connected, then
 any linkzmq:zmq_send[3] operations on the socket shall block until the peer
 becomes available for sending; messages are not discarded.
 
+This socket type doesn't use message labels.
+
 NOTE: 'ZMQ_PAIR' sockets are experimental, and are currently missing several
 features such as auto-reconnection.