diff options
Diffstat (limited to 'doc/zmq_setsockopt.txt')
| -rw-r--r-- | doc/zmq_setsockopt.txt | 125 |
1 files changed, 116 insertions, 9 deletions
diff --git a/doc/zmq_setsockopt.txt b/doc/zmq_setsockopt.txt index 1b551c6..8022568 100644 --- a/doc/zmq_setsockopt.txt +++ b/doc/zmq_setsockopt.txt @@ -12,6 +12,8 @@ SYNOPSIS -------- *int zmq_setsockopt (void '*socket', int 'option_name', const void '*option_value', size_t 'option_len');* +Caution: All options, with the exception of ZMQ_SUBSCRIBE, ZMQ_UNSUBSCRIBE and +ZMQ_LINGER, only take effect for subsequent socket bind/connects. DESCRIPTION ----------- @@ -87,7 +89,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 +117,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 +162,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. @@ -171,13 +173,37 @@ Default value:: 10 Applicable socket types:: all, when using multicast transports -ZMQ_MCAST_LOOP: Control multicast loopback -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +ZMQ_RECOVERY_IVL_MSEC: Set multicast recovery interval in milliseconds +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_RECOVERY_IVL_MSEC' option shall set the recovery interval, specified +in milliseconds (ms) for multicast transports using the specified 'socket'. +The recovery interval determines the maximum time in milliseconds that a +receiver can be absent from a multicast group before unrecoverable data loss +will occur. + +A non-zero value of the 'ZMQ_RECOVERY_IVL_MSEC' option will take precedence +over the 'ZMQ_RECOVERY_IVL' option, but since the default for the +'ZMQ_RECOVERY_IVL_MSEC' is -1, the default is to use the 'ZMQ_RECOVERY_IVL' +option value. + +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. + +[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 shall control whether data sent via multicast transports using the specified 'socket' can also be received by the sending -host via loopback. A value of zero disables the loopback functionality, while -the default value of 1 enables the loopback functionality. Leaving multicast -loopback enabled when it is not required can have a negative impact on +host via loop-back. A value of zero disables the loop-back functionality, while +the default value of 1 enables the loop-back functionality. 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. @@ -216,6 +242,85 @@ Default value:: 0 Applicable socket types:: all +ZMQ_LINGER: Set linger period for socket shutdown +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_LINGER' option shall set 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: Set reconnection interval +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_RECONNECT_IVL' option shall set 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: Set maximum reconnection interval +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_RECONNECT_IVL_MAX' option shall set 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 transports + + +ZMQ_BACKLOG: Set maximum length of the queue of outstanding connections +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_BACKLOG' option shall set 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. + + RETURN VALUE ------------ The _zmq_setsockopt()_ function shall return zero if successful. Otherwise it @@ -231,6 +336,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 @@ -271,5 +378,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>. |