3party/libzmq
0
0
Fork 0
mirror of https://github.com/zeromq/libzmq.git synced 2024-12-27 15:41:05 +08:00
Code Issues Projects Releases Wiki Activity

Fixed doc to clarify how label parts work

Browse Source 
Signed-off-by: Pieter Hintjens <ph@imatix.com>
Signed-off-by: Martin Sustrik <sustrik@250bpm.com>
This commit is contained in:
Pieter Hintjens 2011-09-03 09:02:56 +02:00 committed by Martin Sustrik
parent 9fb9fea633
commit 4138aca54b
6 changed files with 134 additions and 115 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
doc/zmq_getsockopt.txt
View File

@ -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

28
doc/zmq_recv.txt
View File

@ -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>.

42
doc/zmq_recvmsg.txt
View File

@ -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>.

37
doc/zmq_send.txt
View File

@ -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.
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 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>.

38
doc/zmq_sendmsg.txt
View File

@ -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>.

77
doc/zmq_socket.txt
View File

@ -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 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 receiving messages a 'ZMQ_XREP' socket attaches a label uniquely
identifying the originating peer to the message before passing it to the
application.
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.