diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/zmq_bind.txt | 2 | ||||
| -rw-r--r-- | doc/zmq_close.txt | 12 | ||||
| -rw-r--r-- | doc/zmq_connect.txt | 2 | ||||
| -rw-r--r-- | doc/zmq_cpp.txt | 2 | ||||
| -rw-r--r-- | doc/zmq_getsockopt.txt | 87 | ||||
| -rw-r--r-- | doc/zmq_poll.txt | 10 | ||||
| -rw-r--r-- | doc/zmq_recv.txt | 3 | ||||
| -rw-r--r-- | doc/zmq_send.txt | 3 | ||||
| -rw-r--r-- | doc/zmq_setsockopt.txt | 50 | ||||
| -rw-r--r-- | doc/zmq_term.txt | 21 |
10 files changed, 163 insertions, 29 deletions
diff --git a/doc/zmq_bind.txt b/doc/zmq_bind.txt index 7aa5a0b..23c3134 100644 --- a/doc/zmq_bind.txt +++ b/doc/zmq_bind.txt @@ -58,6 +58,8 @@ The requested 'address' specifies a nonexistent interface. The 0MQ 'context' associated with the specified 'socket' was terminated. *EFAULT*:: The provided 'socket' was not valid (NULL). +*EMTHREAD*:: +No I/O thread is available to accomplish the task. EXAMPLE diff --git a/doc/zmq_close.txt b/doc/zmq_close.txt index e903437..1200fb7 100644 --- a/doc/zmq_close.txt +++ b/doc/zmq_close.txt @@ -15,12 +15,11 @@ SYNOPSIS DESCRIPTION ----------- The _zmq_close()_ function shall destroy the socket referenced by the 'socket' -argument. All active connections on the socket shall be terminated and -resources associated with the socket shall be released. Any outstanding -messages sent with _zmq_send()_ but not yet physically sent to the network -shall be dropped. Likewise, any outstanding messages physically received from -the network but not yet received by the application with _zmq_recv()_ shall -also be dropped. +argument. Any outstanding messages physically received from the network but not +yet received by the application with _zmq_recv()_ shall also be dropped. As for +the messages sent with _zmq_send()_ but not yet passed to the network, 0MQ +will try to send them in the background after _zmq_close()_ returns. Time spent +attempting can be set using _ZMQ_LINGER_ socket option. RETURN VALUE @@ -39,6 +38,7 @@ SEE ALSO -------- linkzmq:zmq_socket[3] linkzmq:zmq_term[3] +linkzmq:zmq_setsockopt[3] linkzmq:zmq[7] diff --git a/doc/zmq_connect.txt b/doc/zmq_connect.txt index ffcf3b4..a95f716 100644 --- a/doc/zmq_connect.txt +++ b/doc/zmq_connect.txt @@ -56,6 +56,8 @@ The requested 'transport' protocol is not compatible with the socket type. The 0MQ 'context' associated with the specified 'socket' was terminated. *EFAULT*:: The provided 'socket' was not valid (NULL). +*EMTHREAD*:: +No I/O thread is available to accomplish the task. EXAMPLE diff --git a/doc/zmq_cpp.txt b/doc/zmq_cpp.txt index d43ff62..2ecbb55 100644 --- a/doc/zmq_cpp.txt +++ b/doc/zmq_cpp.txt @@ -102,11 +102,13 @@ Maps to the _zmq_connect()_ function, as described in linkzmq:zmq_connect[3]. *bool socket_t::send(message_t '&msg', int 'flags' = 0)* Maps to the _zmq_send()_ function, as described in linkzmq:zmq_send[3]. +Returns true if message is successfully sent, false if it is not. [verse] *bool socket_t::recv(message_t '*msg', int 'flags' = 0)* Maps to the _zmq_recv()_ function, as described in linkzmq:zmq_recv[3]. +Returns true if message is successfully received, false if it is not. Message diff --git a/doc/zmq_getsockopt.txt b/doc/zmq_getsockopt.txt index 1e36a2a..40a99b1 100644 --- a/doc/zmq_getsockopt.txt +++ b/doc/zmq_getsockopt.txt @@ -26,6 +26,19 @@ value stored in the buffer. The following options can be retrieved with the _zmq_getsockopt()_ function: +ZMQ_TYPE: Retrieve socket type. +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_TYPE' option shall retrieve the socket type for the specified +'socket'. The socket type is specified at socket creation time and +cannot be modified afterwards. + +[horizontal] +Option value type:: int +Option value unit:: N/A +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 @@ -108,7 +121,7 @@ Applicable socket types:: N/A ZMQ_IDENTITY: Retrieve socket identity ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The 'ZMQ_IDENTITY' option shall retrieve the identity of the specified -'socket'. Socket identity determines if existing 0MQ infastructure (_message +'socket'. Socket identity determines if existing 0MQ infrastructure (_message queues_, _forwarding devices_) shall be identified with a specific application and persist across multiple runs of the application. @@ -199,6 +212,76 @@ Default value:: 0 Applicable socket types:: all +ZMQ_LINGER: Retrieve linger period for socket shutdown +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_LINGER' option shall retrieve the period for pending outbound +messages to linger in memory after closing the socket. Value of -1 means +infinite. Pending messages will be kept until they are fully transferred to +the peer. Value of 0 means that all the pending messages are dropped immediately +when socket is closed. Positive value means number of milliseconds to keep +trying to send the pending messages before discarding them. + +[horizontal] +Option value type:: int +Option value unit:: milliseconds +Default value:: -1 +Applicable socket types:: all + +ZMQ_RECONNECT_IVL: Retrieve reconnect period for connection-based transports +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_RECONNECT_IVL' option shall retrieve the period indicating how long it +takes for a disconnected underlying connection to attempt to reconnect. + +[horizontal] +Option value type:: int +Option value unit:: milliseconds +Default value:: 100 +Applicable socket types:: all + + +ZMQ_BACKLOG: Retrieve maximum length of the queue of pending connections +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_BACKLOG' option shall retrieve maximum size of the +pending connection backlog for connection-based transports. For details +refer to your operating system documentation for the 'listen' function. + +[horizontal] +Option value type:: int +Option value unit:: connections +Default value:: 100 +Applicable socket types:: all + + +ZMQ_FD: Retrieve file descriptor associated with the socket +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_FD' option shall retrieve file descriptor associated with the 0MQ +socket. The descriptor can be used to integrate 0MQ socket into an existing +event loop. It should never be used for anything else than polling -- such as +reading or writing. The descriptor signals edge-triggered IN event when +something has happened within the 0MQ socket. It does not necessarily mean that +the messages can be read or written. Check ZMQ_EVENTS option to find out whether +the 0MQ socket is readable or writeable. + +[horizontal] +Option value type:: int on POSIX systems, SOCKET on Windows +Option value unit:: N/A +Default value:: N/A +Applicable socket types:: all + + +ZMQ_EVENTS: Check whether socket is readable and/or writeable +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_EVENTS' option shall retrieve event flags for the specified socket. +If a message can be read from the socket ZMQ_POLLIN flag is set. If message can +be written to the socket ZMQ_POLLOUT flag is set. + +[horizontal] +Option value type:: uint32_t +Option value unit:: N/A (flags) +Default value:: N/A +Applicable socket types:: all + + RETURN VALUE ------------ The _zmq_getsockopt()_ function shall return zero if successful. Otherwise it @@ -216,6 +299,8 @@ option value. The 0MQ 'context' associated with the specified 'socket' was terminated. *EFAULT*:: The provided 'socket' was not valid (NULL). +*EINTR*:: +The operation was interrupted by delivery of a signal. EXAMPLE diff --git a/doc/zmq_poll.txt b/doc/zmq_poll.txt index fe2a209..f709c07 100644 --- a/doc/zmq_poll.txt +++ b/doc/zmq_poll.txt @@ -44,7 +44,7 @@ member, and then indicate any requested events that have occured by setting the bit corresponding to the event condition in the 'revents' member. If none of the requested events have occured on any *zmq_pollitem_t* item, -_zmq_poll()_ shall wait up to 'timeout' microseconds for an event to occur on +_zmq_poll()_ shall wait 'timeout' microseconds for an event to occur on any of the requested items. If the value of 'timeout' is `0`, _zmq_poll()_ shall return immediately. If the value of 'timeout' is `-1`, _zmq_poll()_ shall block indefinitely until a requested event has occured on at least one @@ -84,20 +84,16 @@ of *zmq_pollitem_t* structures with events signaled in 'revents' or `0` if no events have been signaled. Upon failure, _zmq_poll()_ shall return `-1` and set 'errno' to one of the values defined below. -IMPORTANT: The _zmq_poll()_ function may return *before* the 'timeout' period -has expired even if no events have been signaled. - ERRORS ------ -*EFAULT*:: -At least one of the members of the 'items' array refers to a 'socket' belonging -to a different application thread. *ETERM*:: At least one of the members of the 'items' array refers to a 'socket' whose associated 0MQ 'context' was terminated. *EFAULT*:: The provided 'items' was not valid (NULL). +*EINTR*:: +The poll was interrupted by delivery of a signal before any event was available. EXAMPLE diff --git a/doc/zmq_recv.txt b/doc/zmq_recv.txt index dc60af6..dbbbd75 100644 --- a/doc/zmq_recv.txt +++ b/doc/zmq_recv.txt @@ -65,6 +65,9 @@ _messaging patterns_ section of linkzmq:zmq_socket[3] for more information. The 0MQ 'context' associated with the specified 'socket' was terminated. *EFAULT*:: The provided 'socket' was not valid (NULL). +*EINTR*:: +The operation was interrupted by delivery of a signal before a message was +available. EXAMPLE diff --git a/doc/zmq_send.txt b/doc/zmq_send.txt index 793d1a8..231dfcc 100644 --- a/doc/zmq_send.txt +++ b/doc/zmq_send.txt @@ -71,6 +71,9 @@ _messaging patterns_ section of linkzmq:zmq_socket[3] for more information. The 0MQ 'context' associated with the specified 'socket' was terminated. *EFAULT*:: The provided 'context' was not valid (NULL). +*EINTR*:: +The operation was interrupted by delivery of a signal before the message was +sent. EXAMPLE diff --git a/doc/zmq_setsockopt.txt b/doc/zmq_setsockopt.txt index 1b551c6..af92929 100644 --- a/doc/zmq_setsockopt.txt +++ b/doc/zmq_setsockopt.txt @@ -87,7 +87,7 @@ Applicable socket types:: N/A ZMQ_IDENTITY: Set socket identity ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The 'ZMQ_IDENTITY' option shall set the identity of the specified 'socket'. -Socket identity determines if existing 0MQ infastructure (_message queues_, +Socket identity determines if existing 0MQ infrastructure (_message queues_, _forwarding devices_) shall be identified with a specific application and persist across multiple runs of the application. @@ -115,7 +115,7 @@ therefore you should call this option to establish an initial message filter. An empty 'option_value' of length zero shall subscribe to all incoming messages. A non-empty 'option_value' shall subscribe to all messages beginning -with the specified prefix. Mutiple filters may be attached to a single +with the specified prefix. Multiple filters may be attached to a single 'ZMQ_SUB' socket, in which case a message shall be accepted if it matches at least one filter. @@ -160,7 +160,7 @@ transports using the specified 'socket'. The recovery interval determines the maximum time in seconds that a receiver can be absent from a multicast group before unrecoverable data loss will occur. -CAUTION: Excersize care when setting large recovery intervals as the data +CAUTION: Exercise care when setting large recovery intervals as the data needed for recovery will be held in memory. For example, a 1 minute recovery interval at a data rate of 1Gbps requires a 7GB in-memory buffer. @@ -216,6 +216,48 @@ Default value:: 0 Applicable socket types:: all +ZMQ_LINGER: Set linger period for socket shutdown +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_LINGER' option shall be set to specify period for pending outbound +messages to linger in memory after closing the socket. Value of -1 means +infinite. Pending messages will be kept until they are fully transferred to +the peer. Value of 0 means that all the pending messages are dropped immediately +when socket is closed. Positive value means number of milliseconds to keep +trying to send the pending messages before discarding them. + +[horizontal] +Option value type:: int +Option value unit:: milliseconds +Default value:: -1 +Applicable socket types:: all + + +ZMQ_RECONNECT_IVL: Set reconnect period for connection-based transports +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_RECONNECT_IVL' option shall be set to specify how long it takes for a +disconnected underlying connection to attempt to reconnect. The interval +can be randomized to some extent by 0MQ to prevent reconnection storms. + +[horizontal] +Option value type:: int +Option value unit:: milliseconds +Default value:: 100 +Applicable socket types:: all + + +ZMQ_BACKLOG: Set maximum length of the queue of pending connections +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_BACKLOG' option shall be set to specify maximum size of the +pending connection backlog for connection-based transports. For details +refer to your operating system documentation for the 'listen' function. + +[horizontal] +Option value type:: int +Option value unit:: connections +Default value:: 100 +Applicable socket types:: all + + RETURN VALUE ------------ The _zmq_setsockopt()_ function shall return zero if successful. Otherwise it @@ -231,6 +273,8 @@ _option_value_ is invalid. The 0MQ 'context' associated with the specified 'socket' was terminated. *EFAULT*:: The provided 'socket' was not valid (NULL). +*EINTR*:: +The operation was interrupted by delivery of a signal. EXAMPLE diff --git a/doc/zmq_term.txt b/doc/zmq_term.txt index f3ffa01..6c69b82 100644 --- a/doc/zmq_term.txt +++ b/doc/zmq_term.txt @@ -16,23 +16,18 @@ DESCRIPTION ----------- The _zmq_term()_ function terminates the 0MQ context 'context'. -If there are no longer any sockets open within 'context' at the time -_zmq_term()_ is called then 'context' shall be shut down and all associated -resources shall be released immediately. +It does so in following steps: -Otherwise, the following applies: - -* The _zmq_term()_ function shall return immediately. - -* Any blocking operations currently in progress on sockets open within - 'context' shall return immediately with an error code of ETERM. +* It causes any blocking operations currently in progress on sockets open within + 'context' to exit immediately with an error code of ETERM. * With the exception of _zmq_close()_, any further operations on sockets open within 'context' shall fail with an error code of ETERM. -* The actual shutdown of 'context', and release of any associated resources, - *shall be delayed* until the last socket within it is closed with - _zmq_close()_. +* After iterrupting all blocking calls, _zmq_term()_ blocks until all sockets + open within the context are closed using _zmq_close()_ and either all the + pending outbound messages are pushed to the network or ZMQ_LINGER period + expires for individual sockets. RETURN VALUE @@ -51,6 +46,8 @@ SEE ALSO -------- linkzmq:zmq[7] linkzmq:zmq_init[3] +linkzmq:zmq_close[3] +linkzmq:zmq_setsockopt[3] AUTHORS |