Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix documentation about sockets blocking on send operations #3686

Merged
merged 1 commit into from
Sep 23, 2019
+40 −33
Merged

Fix documentation about sockets blocking on send operations #3686

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 5 additions & 4 deletions doc/zmq_msg_send.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,10 +23,11 @@ argument to be sent to the socket referenced by the 'socket' argument. The
'flags' argument is a combination of the flags defined below:

*ZMQ_DONTWAIT*::
For socket types (DEALER, PUSH) that block when there are no available peers
(or all peers have full high-water mark), specifies that the operation should
be performed in non-blocking mode. If the message cannot be queued on the
'socket', the _zmq_msg_send()_ function shall fail with 'errno' set to EAGAIN.
For socket types (DEALER, PUSH) that block (either with ZMQ_IMMEDIATE option set
and no peer available, or all peers having full high-water mark), specifies that
the operation should be performed in non-blocking mode. If the message cannot be
queued on the 'socket', the _zmq_msg_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
Expand Down
9 changes: 5 additions & 4 deletions doc/zmq_send.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,10 +19,11 @@ referenced by the 'buf' and 'len' arguments. The 'flags' argument is
a combination of the flags defined below:

*ZMQ_DONTWAIT*::
For socket types (DEALER, PUSH) that block when there are no available peers
(or all peers have full high-water mark), 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.
For socket types (DEALER, PUSH) that block (either with ZMQ_IMMEDIATE option set
and no peer available, or all peers having full high-water mark), 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_SNDMORE*::
Specifies that the message being sent is a multi-part message, and that further
Expand Down
9 changes: 5 additions & 4 deletions doc/zmq_send_const.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,10 +20,11 @@ to be constant-memory and will therefore not be copied or deallocated
in any way. The 'flags' argument is a combination of the flags defined below:

*ZMQ_DONTWAIT*::
For socket types (DEALER, PUSH) that block when there are no available peers
(or all peers have full high-water mark), specifies that the operation should
be performed in non-blocking mode. If the message cannot be queued on the
'socket', the _zmq_send_const()_ function shall fail with 'errno' set to EAGAIN.
For socket types (DEALER, PUSH) that block (either with ZMQ_IMMEDIATE option set
and no peer available, or all peers having full high-water mark), specifies that
the operation should be performed in non-blocking mode. If the message cannot be
queued on the 'socket', the _zmq_send_const()_ function shall fail with 'errno' set
to EAGAIN.

*ZMQ_SNDMORE*::
Specifies that the message being sent is a multi-part message, and that further
Expand Down
9 changes: 5 additions & 4 deletions doc/zmq_sendmsg.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,10 +19,11 @@ argument to be sent to the socket referenced by the 'socket' argument. The
'flags' argument is a combination of the flags defined below:

*ZMQ_DONTWAIT*::
For socket types (DEALER, PUSH) that block when there are no available peers
(or all peers have full high-water mark), 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.
For socket types (DEALER, PUSH) that block (either with ZMQ_IMMEDIATE option set
and no peer available, or all peers having full high-water mark), 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_SNDMORE*::
Specifies that the message being sent is a multi-part message, and that further
Expand Down
37 changes: 20 additions & 17 deletions doc/zmq_socket.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -85,14 +85,15 @@ the 'ZMQ_CLIENT'.
If the 'ZMQ_CLIENT' socket has established a connection, linkzmq:zmq_send[3]
will accept messages, queue them, and send them as rapidly as the network
allows. The outgoing buffer limit is defined by the high water mark for the
socket. If the outgoing buffer is full, or if there is no connected peer,
linkzmq:zmq_send[3] will block, by default. The 'ZMQ_CLIENT' socket will not
drop messages.
socket. If the outgoing buffer is full, or, for connection-oriented transports,
if the ZMQ_IMMEDIATE option is set and there is no connected peer,
linkzmq:zmq_send[3] will block.
The 'ZMQ_CLIENT' socket will not drop messages.

When a 'ZMQ_CLIENT' socket is connected to multiple 'ZMQ_SERVER' sockets,
outgoing messages are distributed between connected peers on a round-robin
basis. Likewise, the 'ZMQ_CLIENT' socket receives messages fairly from each
connected peer. This usage is sensible only for stateless protocols.
connected peer. This usage is sensible only for stateless protocols.

'ZMQ_CLIENT' sockets are threadsafe and can be used from multiple threads
at the same time. Note that replies from a 'ZMQ_SERVER' socket will go to
Expand Down Expand Up @@ -128,7 +129,7 @@ a message to a given 'ZMQ_CLIENT' peer the application must set the peer's

If the 'routing_id' is not specified, or does not refer to a connected client
peer, the send call will fail with EHOSTUNREACH. If the outgoing buffer for
the client peer is full, the send call shall block, unless ZMQ_DONT_WAIT is
the client peer is full, the send call shall block, unless ZMQ_DONTWAIT is
used in the send, in which case it shall fail with EAGAIN. The 'ZMQ_SERVER'
socket shall not drop messages in any case.

Expand Down Expand Up @@ -307,10 +308,11 @@ downstream _nodes_. The _zmq_recv()_ function is not implemented for this
socket type.

When a 'ZMQ_PUSH' socket enters the 'mute' state due to having reached the
high water mark for all downstream _nodes_, or if there are no downstream
_nodes_ at all, then any linkzmq:zmq_send[3] operations on the socket shall
block until the mute state ends or at least one downstream _node_
becomes available for sending; messages are not discarded.
high water mark for all downstream _nodes_, or, for connection-oriented transports,
if the ZMQ_IMMEDIATE option is set and there are no downstream _nodes_ at all,
then any linkzmq:zmq_send[3] operations on the socket shall block until the mute
state ends or at least one downstream _node_ becomes available for sending;
messages are not discarded.

[horizontal]
.Summary of ZMQ_PUSH characteristics
Expand Down Expand Up @@ -354,7 +356,8 @@ time. No message routing or filtering is performed on messages sent over a
'ZMQ_PAIR' socket.

When a 'ZMQ_PAIR' socket enters the 'mute' state due to having reached the
high water mark for the connected peer, or if no peer is connected, then
high water mark for the connected peer, or, for connection-oriented transports,
if the ZMQ_IMMEDIATE option is set and there is no connected peer, then
any linkzmq:zmq_send[3] operations on the socket shall block until the peer
becomes available for sending; messages are not discarded.

Expand Down Expand Up @@ -437,9 +440,9 @@ 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.
For connection-oriented transports, If the ZMQ_IMMEDIATE option is set and there
is no service 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
Expand Down Expand Up @@ -476,10 +479,10 @@ 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.
high water mark for all peers, or, for connection-oriented transports, if the
ZMQ_IMMEDIATE option is set and 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
Expand Down