diff options
Diffstat (limited to 'doc/zmq_setsockopt.txt')
| -rw-r--r-- | doc/zmq_setsockopt.txt | 273 |
1 files changed, 273 insertions, 0 deletions
diff --git a/doc/zmq_setsockopt.txt b/doc/zmq_setsockopt.txt new file mode 100644 index 0000000..a5a2601 --- /dev/null +++ b/doc/zmq_setsockopt.txt @@ -0,0 +1,273 @@ +zmq_setsockopt(3) +================= + + +NAME +---- + +zmq_setsockopt - set 0MQ socket options + + +SYNOPSIS +-------- +*int zmq_setsockopt (void '*socket', int 'option_name', const void '*option_value', size_t 'option_len');* + + +DESCRIPTION +----------- +The _zmq_setsockopt()_ function shall set the option specified by the +'option_name' argument to the value pointed to by the 'option_value' argument +for the 0MQ socket pointed to by the 'socket' argument. The 'option_len' +argument is the size of the option value in bytes. + +The following socket options can be set with the _zmq_setsockopt()_ function: + + +ZMQ_HWM: Set high water mark +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_HWM' option shall set the high water mark for the specified 'socket'. +The high water mark is a hard limit on the maximum number of outstanding +messages 0MQ shall queue in memory for any single peer that the specified +'socket' is communicating with. + +If this limit has been reached the socket shall enter an exceptional state and +depending on the socket type, 0MQ shall take appropriate action such as +blocking or dropping sent messages. Refer to the individual socket descriptions +in linkzmq:zmq_socket[3] for details on the exact action taken for each socket +type. + +The default 'ZMQ_HWM' value of zero means "no limit". + +[horizontal] +Option value type:: int64_t +Option value unit:: messages +Default value:: 0 +Applicable socket types:: all + + +ZMQ_SWAP: Set disk offload size +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_SWAP' option shall set the disk offload (swap) size for the specified +'socket'. A socket which has 'ZMQ_SWAP' set to a non-zero value may exceed it's +high water mark; in this case outstanding messages shall be offloaded to +storage on disk rather than held in memory. + +The value of 'ZMQ_SWAP' defines the maximum size of the swap space in bytes. + +[horizontal] +Option value type:: int64_t +Option value unit:: bytes +Default value:: 0 +Applicable socket types:: all + + +ZMQ_AFFINITY: Set I/O thread affinity +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_AFFINITY' option shall set the I/O thread affinity for newly created +connections on the specified 'socket'. + +Affinity determines which threads from the 0MQ I/O thread pool associated with +the socket's _context_ shall handle newly created connections. A value of zero +specifies no affinity, meaning that work shall be distributed fairly among all +0MQ I/O threads in the thread pool. For non-zero values, the lowest bit +corresponds to thread 1, second lowest bit to thread 2 and so on. For example, +a value of 3 specifies that subsequent connections on 'socket' shall be handled +exclusively by I/O threads 1 and 2. + +See also linkzmq:zmq_init[3] for details on allocating the number of I/O +threads for a specific _context_. + +[horizontal] +Option value type:: int64_t +Option value unit:: N/A (bitmap) +Default value:: 0 +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_, +_forwarding devices_) shall be identified with a specific application and +persist across multiple runs of the application. + +If the socket has no identity, each run of an application is completely +separate from other runs. However, with identity set the socket shall re-use +any existing 0MQ infrastructure configured by the previous run(s). Thus the +application may receive messages that were sent in the meantime, _message +queue_ limits shall be shared with previous run(s) and so on. + +Identity should be at least one byte and at most 255 bytes long. Identities +starting with binary zero are reserved for use by 0MQ infrastructure. + +[horizontal] +Option value type:: binary data +Option value unit:: N/A +Default value:: NULL +Applicable socket types:: all + + +ZMQ_SUBSCRIBE: Establish message filter +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_SUBSCRIBE' option shall establish a new message filter on a 'ZMQ_SUB' +socket. Newly created 'ZMQ_SUB' sockets shall filter out all incoming messages, +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 +'ZMQ_SUB' socket, in which case a message shall be accepted if it matches at +least one filter. + +[horizontal] +Option value type:: binary data +Option value unit:: N/A +Default value:: N/A +Applicable socket types:: ZMQ_SUB + + +ZMQ_UNSUBSCRIBE: Remove message filter +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_UNSUBSCRIBE' option shall remove an existing message filter on a +'ZMQ_SUB' socket. The filter specified must match an existing filter previously +established with the 'ZMQ_SUBSCRIBE' option. If the socket has several +instances of the same filter attached the 'ZMQ_UNSUBSCRIBE' option shall remove +only one instance, leaving the rest in place and functional. + +[horizontal] +Option value type:: binary data +Option value unit:: N/A +Default value:: N/A +Applicable socket types:: ZMQ_SUB + + +ZMQ_RATE: Set multicast data rate +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_RATE' option shall set the maximum send or receive data rate for +multicast transports such as linkzmq:zmq_pgm[7] using the specified 'socket'. + +[horizontal] +Option value type:: uint64_t +Option value unit:: kilobits per second +Default value:: 100 +Applicable socket types:: all, when using multicast transports + + +ZMQ_RECOVERY_IVL: Set multicast recovery interval +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_RECOVERY_IVL' option shall set the recovery interval 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. + +CAUTION: Excersize 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:: uint64_t +Option value unit:: seconds +Default value:: 10 +Applicable socket types:: all, when using multicast transports + + +ZMQ_MCAST_LOOP: Control multicast loopback +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +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 +performance. Where possible, disable 'ZMQ_MCAST_LOOP' in production +environments. + +[horizontal] +Option value type:: uint64_t +Option value unit:: boolean +Default value:: 1 +Applicable socket types:: all, when using multicast transports + + +ZMQ_SNDBUF: Set kernel transmit buffer size +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_SNDBUF' option shall set the underlying kernel transmit buffer size +for the 'socket' to the specified size in bytes. A value of zero means leave +the OS default unchanged. For details please refer to your operating system +documentation for the 'SO_SNDBUF' socket option. + +[horizontal] +Option value type:: uint64_t +Option value unit:: bytes +Default value:: 0 +Applicable socket types:: all + + +ZMQ_RCVBUF: Set kernel receive buffer size +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_RCVBUF' option shall set the underlying kernel receive buffer size for +the 'socket' to the specified size in bytes. A value of zero means leave the +OS default unchanged. For details refer to your operating system documentation +for the 'SO_RCVBUF' socket option. + +[horizontal] +Option value type:: uint64_t +Option value unit:: bytes +Default value:: 0 +Applicable socket types:: all + + +RETURN VALUE +------------ +The _zmq_setsockopt()_ function shall return zero if successful. Otherwise it +shall return `-1` and set 'errno' to one of the values defined below. + + +ERRORS +------ +*EINVAL*:: +The requested option _option_name_ is unknown, or the requested _option_len_ or +_option_value_ is invalid. +*ETERM*:: +The 0MQ 'context' associated with the specified 'socket' was terminated. + + +EXAMPLE +------- +.Subscribing to messages on a 'ZMQ_SUB' socket +---- +/* Subscribe to all messages */ +rc = zmq_setsockopt (socket, ZMQ_SUBSCRIBE, "", 0); +assert (rc == 0); +/* Subscribe to messages prefixed with "ANIMALS.CATS" */ +rc = zmq_setsockopt (socket, ZMQ_SUBSCRIBE, "ANIMALS.CATS", 12); +---- + +.Setting I/O thread affinity +---- +int64_t affinity; +/* Incoming connections on TCP port 5555 shall be handled by I/O thread 1 */ +affinity = 1; +rc = zmq_setsockopt (socket, ZMQ_AFFINITY, &affinity, sizeof affinity); +assert (rc); +rc = zmq_bind (socket, "tcp://lo:5555"); +assert (rc); +/* Incoming connections on TCP port 5556 shall be handled by I/O thread 2 */ +affinity = 2; +rc = zmq_setsockopt (socket, ZMQ_AFFINITY, &affinity, sizeof affinity); +assert (rc); +rc = zmq_bind (socket, "tcp://lo:5556"); +assert (rc); +---- + + +SEE ALSO +-------- +linkzmq:zmq_getsockopt[3] +linkzmq:zmq_socket[3] +linkzmq:zmq[7] + + +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and +Martin Lucina <mato@kotelna.sk>. |