diff options
Diffstat (limited to 'doc/zmq_getsockopt.txt')
| -rw-r--r-- | doc/zmq_getsockopt.txt | 116 |
1 files changed, 78 insertions, 38 deletions
diff --git a/doc/zmq_getsockopt.txt b/doc/zmq_getsockopt.txt index 40a99b1..7f73e1c 100644 --- a/doc/zmq_getsockopt.txt +++ b/doc/zmq_getsockopt.txt @@ -26,8 +26,8 @@ value stored in the buffer. The following options can be retrieved with the _zmq_getsockopt()_ function: -ZMQ_TYPE: Retrieve socket type. -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +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. @@ -167,13 +167,13 @@ Default value:: 10 Applicable socket types:: all, when using multicast transports -ZMQ_MCAST_LOOP: Control multicast loopback -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +ZMQ_MCAST_LOOP: Control multicast loop-back +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The 'ZMQ_MCAST_LOOP' option controls whether data sent via multicast -transports can also be received by the sending host via loopback. A value of -zero indicates that the loopback functionality is disabled, while the default -value of 1 indicates that the loopback functionality is enabled. Leaving -multicast loopback enabled when it is not required can have a negative impact +transports can also be received by the sending host via loop-back. A value of +zero indicates that the loop-back functionality is disabled, while the default +value of 1 indicates that the loop-back functionality is enabled. Leaving +multicast loop-back enabled when it is not required can have a negative impact on performance. Where possible, disable 'ZMQ_MCAST_LOOP' in production environments. @@ -214,53 +214,80 @@ 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. +The 'ZMQ_LINGER' option shall retrieve the linger period for the specified +'socket'. The linger period determines how long pending messages which have +yet to be sent to a peer shall linger in memory after a socket is closed with +linkzmq:zmq_close[3], and further affects the termination of the socket's +context with linkzmq:zmq_term[3]. The following outlines the different +behaviours: + +* The default value of '-1' specifies an infinite linger period. Pending + messages shall not be discarded after a call to _zmq_close()_; attempting to + terminate the socket's context with _zmq_term()_ shall block until all + pending messages have been sent to a peer. + +* The value of '0' specifies no linger period. Pending messages shall be + discarded immediately when the socket is closed with _zmq_close()_. + +* Positive values specify an upper bound for the linger period in milliseconds. + Pending messages shall not be discarded after a call to _zmq_close()_; + attempting to terminate the socket's context with _zmq_term()_ shall block + until either all pending messages have been sent to a peer, or the linger + period expires, after which any pending messages shall be discarded. [horizontal] Option value type:: int Option value unit:: milliseconds -Default value:: -1 +Default value:: -1 (infinite) 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. +ZMQ_RECONNECT_IVL: Retrieve reconnection interval +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_RECONNECT_IVL' option shall retrieve the reconnection interval for the +specified 'socket'. The reconnection interval is the maximum period 0MQ shall +wait between attempts to reconnect disconnected peers when using +connection-oriented transports. + +NOTE: The reconnection interval may be randomized by 0MQ to prevent +reconnection storms in topologies with a large number of peers per socket. [horizontal] Option value type:: int Option value unit:: milliseconds Default value:: 100 -Applicable socket types:: all +Applicable socket types:: all, only for connection-oriented transports -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. +ZMQ_BACKLOG: Retrieve maximum length of the queue of outstanding connections +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_BACKLOG' option shall retrieve the maximum length of the queue of +outstanding peer connections for the specified 'socket'; this only applies to +connection-oriented 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 +Applicable socket types:: all, only for connection-oriented transports 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. +The 'ZMQ_FD' option shall retrieve the file descriptor associated with the +specified 'socket'. The returned file descriptor can be used to integrate the +socket into an existing event loop; the 0MQ library shall signal any pending +events on the socket in an _edge-triggered_ fashion by making the file +descriptor become ready for reading. + +NOTE: The ability to read from the returned file descriptor does not +necessarily indicate that messages are available to be read from, or can be +written to, the underlying socket; applications must retrieve the actual event +state with a subsequent retrieval of the 'ZMQ_EVENTS' option. + +CAUTION: The returned file descriptor is intended for use with a 'poll' or +similar system call only. Applications must never attempt to read or write data +to it directly. [horizontal] Option value type:: int on POSIX systems, SOCKET on Windows @@ -269,11 +296,24 @@ 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. +ZMQ_EVENTS: Retrieve socket event state +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_EVENTS' option shall retrieve the event state for the specified +'socket'. The returned value is a bit mask constructed by OR'ing a combination +of the following event flags: + +*ZMQ_POLLIN*:: +Indicates that at least one message may be received from the specified socket +without blocking. + +*ZMQ_POLLOUT*:: +Indicates that at least one message may be sent to the specified socket without +blocking. + +The combination of a file descriptor returned by the 'ZMQ_FD' option being +ready for reading but no actual events returned by a subsequent retrieval of +the 'ZMQ_EVENTS' option is valid; applications should simply ignore this case +and restart their polling operation/event loop. [horizontal] Option value type:: uint32_t |