diff options
Diffstat (limited to 'doc/zmq_getsockopt.txt')
| -rw-r--r-- | doc/zmq_getsockopt.txt | 180 |
1 files changed, 172 insertions, 8 deletions
diff --git a/doc/zmq_getsockopt.txt b/doc/zmq_getsockopt.txt index 1e36a2a..1279fbc 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. @@ -154,13 +167,33 @@ Default value:: 10 Applicable socket types:: all, when using multicast transports -ZMQ_MCAST_LOOP: Control multicast loopback -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +ZMQ_RECOVERY_IVL_MSEC: Get multicast recovery interval in milliseconds +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_RECOVERY_IVL'_MSEC option shall retrieve the recovery interval, in +milliseconds, for multicast 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. + +For backward compatibility, the default value of 'ZMQ_RECOVERY_IVL_MSEC' is +-1 indicating that the recovery interval should be obtained from the +'ZMQ_RECOVERY_IVL' option. However, if the 'ZMQ_RECOVERY_IVL_MSEC' value is +not zero, then it will take precedence, and be used. + +[horizontal] +Option value type:: int64_t +Option value unit:: milliseconds +Default value:: -1 +Applicable socket types:: all, when using multicast transports + + +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. @@ -199,6 +232,135 @@ Default value:: 0 Applicable socket types:: all +ZMQ_LINGER: Retrieve linger period for socket shutdown +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +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 (infinite) +Applicable socket types:: all + + +ZMQ_RECONNECT_IVL: Retrieve reconnection interval +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_RECONNECT_IVL' option shall retrieve the initial reconnection interval +for the specified 'socket'. The reconnection interval is the 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, only for connection-oriented transports + + +ZMQ_RECONNECT_IVL_MAX: Retrieve maximum reconnection interval +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_RECONNECT_IVL_MAX' option shall retrieve the maximum reconnection +interval for the specified 'socket'. This is the maximum period 0MQ shall wait +between attempts to reconnect. On each reconnect attempt, the previous interval +shall be doubled untill ZMQ_RECONNECT_IVL_MAX is reached. This allows for +exponential backoff strategy. Default value means no exponential backoff is +performed and reconnect interval calculations are only based on ZMQ_RECONNECT_IVL. + +NOTE: Values less than ZMQ_RECONNECT_IVL will be ignored. + +[horizontal] +Option value type:: int +Option value unit:: milliseconds +Default value:: 0 (only use ZMQ_RECONNECT_IVL) +Applicable socket types:: all, only for connection-oriented transport + + +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, only for connection-oriented transports + + +ZMQ_FD: Retrieve file descriptor associated with the socket +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +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, neither should they try to close it. + +[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: 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 +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 +378,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 @@ -239,5 +403,5 @@ linkzmq:zmq[7] AUTHORS ------- -The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and +This 0MQ manual page was written by Martin Sustrik <sustrik@250bpm.com> and Martin Lucina <mato@kotelna.sk>. |