mirror of
https://github.com/zeromq/libzmq.git
synced 2024-12-13 10:52:56 +01:00
271 lines
9.3 KiB
Plaintext
271 lines
9.3 KiB
Plaintext
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 options are defined:
|
|
|
|
|
|
ZMQ_HWM: Set high water mark
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
The 'ZMQ_HWM' option shall set the high water mark for the _message queue_
|
|
associated with the socket. The high water mark is a hard limit on the number
|
|
of outstanding messages in the queue; if this limit has been reached the socket
|
|
shall enter an "emergency" state and depending on the socket type, 0MQ shall
|
|
take appropriate action such as blocking or dropping new messages entering the
|
|
queue.
|
|
|
|
The default 'ZMQ_HWM' value of zero means "no limit".
|
|
|
|
Option value type:: int64_t
|
|
Option value unit:: messages
|
|
Default value:: 0
|
|
Applicable socket types:: all
|
|
|
|
|
|
ZMQ_LWM: Set low water mark
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
The 'ZMQ_LWM' option shall set the low water mark for the _message queue_
|
|
associated with the socket. This option only makes sense when used in
|
|
conjunction with the 'ZMQ_HWM' option. A socket which has reached it's high
|
|
water mark remains in the "emergency" state until the number of outstanding
|
|
messages in it's associated message queue falls below the low water mark, at
|
|
which point normal message processing is resumed.
|
|
|
|
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 _message
|
|
queue_ associated with the 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.
|
|
|
|
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 connections
|
|
created by subsequent _zmq_connect()_ or _zmq_bind()_ calls on the specified
|
|
'socket'.
|
|
|
|
sockets. 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_.
|
|
|
|
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 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.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
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'.
|
|
|
|
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 such as linkzmq:zmq_pgm[7] 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.
|
|
|
|
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 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.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
|
|
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:5555");
|
|
assert (rc);
|
|
----
|
|
|
|
|
|
SEE ALSO
|
|
--------
|
|
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>.
|