generic-library/libzmq
1
0
Fork 0
mirror of https://github.com/zeromq/libzmq.git synced 2025-01-19 00:46:05 +01:00
Code Issues Projects Releases Wiki Activity

Documentation updates

Browse Source 
Multi-part messages
This commit is contained in:
Martin Lucina 2010-05-31 14:12:27 +02:00
parent 8becacf82c
commit eb9ff1e779
3 changed files with 85 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

17
doc/zmq_getsockopt.txt
View File

@ -24,6 +24,23 @@ to by 'option_value'.
The following options can be retrieved with the _zmq_getsockopt()_ function:
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.
Option value type:: int64_t
Option value unit:: boolean
Default value:: N/A
Applicable socket types:: all
ZMQ_HWM: Retrieve high water mark
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_HWM' option shall retrieve the high water mark for the _message queue_

37
doc/zmq_recv.txt
View File

@ -29,6 +29,23 @@ associated with 'socket', the _zmq_recv()_ function shall fail with 'errno' set
to EAGAIN.
Multi-part messages
~~~~~~~~~~~~~~~~~~~
A 0MQ message is composed of 1 to N message parts; each message part is an
independent 'zmq_msg_t' in its own right. Consequently, wherever this
documentation uses the term _message_ it may be substituted for _message part_.
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.
0MQ shall ensure the atomicity of a multi-part message; peers shall receive
either all _message parts_ of a multi-part message or none at all.
RETURN VALUE
------------
The _zmq_recv()_ function shall return zero if successful. Otherwise it shall
@ -47,7 +64,7 @@ to the socket not being in the appropriate state. This error may occur with
socket types that switch between several states, such as ZMQ_REP. See the
_messaging patterns_ section of linkzmq:zmq_socket[3] for more information.
*ETERM*::
The associated context was terminted.
The 0MQ 'context' associated with the specified 'socket' was terminated.
EXAMPLE
@ -63,10 +80,28 @@ rc = zmq_recv (socket, &msg, 0);
assert (rc == 0);
----
.Receiving a multi-part message
----
int64_t more;
do {
/* Create an empty 0MQ message to hold the message part */
zmq_msg_t part;
int rc = zmq_msg_init (&part);
assert (rc == 0);
/* Block until a message is available to be dequeued from socket */
rc = zmq_recv (socket, &part, 0);
assert (rc == 0);
/* Determine if more message parts are to follow */
rc = zmq_getsockopt (socket, ZMQ_RCVMORE, &more, sizeof more);
assert (rc == 0);
} while (more);
----
SEE ALSO
--------
linkzmq:zmq_send[3]
linkzmq:zmq_getsockopt[3]
linkzmq:zmq_socket[7]
linkzmq:zmq[7]

33
doc/zmq_send.txt
View File

@ -23,12 +23,34 @@ Specifies that the operation should be performed in non-blocking mode. If the
message cannot be queued on the underlying _message queue_ associated with
'socket', the _zmq_send()_ function shall fail with 'errno' set to EAGAIN.
*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.
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 _message queue_ associated with the socket and 0MQ has assumed
responsibility for the message.
Multi-part messages
~~~~~~~~~~~~~~~~~~~
A 0MQ message is composed of 1 to N message parts; each message part is an
independent 'zmq_msg_t' in its own right. Consequently, wherever this
documentation uses the term _message_ it may be substituted for _message part_.
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. The total number of mess
0MQ shall ensure the atomicity of a multi-part message; peers shall receive
either all _message parts_ of a multi-part message or none at all.
RETURN VALUE
------------
The _zmq_send()_ function shall return zero if successful. Otherwise it shall
@ -47,7 +69,7 @@ to the socket not being in the appropriate state. This error may occur with
socket types that switch between several states, such as ZMQ_REP. See the
_messaging patterns_ section of linkzmq:zmq_socket[3] for more information.
*ETERM*::
The associated context was terminted.
The 0MQ 'context' associated with the specified 'socket' was terminated.
EXAMPLE
@ -65,6 +87,15 @@ rc = zmq_send (socket, &msg, 0);
assert (rc == 0);
----
.Sending a multi-part message
----
/* Send a multi-part message consisting of three parts to socket */
rc = zmq_send (socket, &part1, ZMQ_SNDMORE);
rc = zmq_send (socket, &part2, ZMQ_SNDMORE);
/* Final part; no more parts to follow */
rc = zmq_send (socket, &part3, 0);
----
SEE ALSO
--------