mirror of
https://github.com/zeromq/libzmq.git
synced 2024-12-13 10:52:56 +01:00
Documentation updates
Add zmq_getsockopt(3), clean up zmq_setsockopt(3).
This commit is contained in:
Martin Lucina
parent
be6019abd1
commit
8becacf82c
209
doc/zmq_getsockopt.txt
Normal file
209
doc/zmq_getsockopt.txt
Normal file
@ -0,0 +1,209 @@
|
||||
zmq_getsockopt(3)
|
||||
=================
|
||||
|
||||
|
||||
NAME
|
||||
----
|
||||
|
||||
zmq_getsockopt - get 0MQ socket options
|
||||
|
||||
|
||||
SYNOPSIS
|
||||
--------
|
||||
*int zmq_getsockopt (void '*socket', int 'option_name', void '*option_value', size_t 'option_len');*
|
||||
|
||||
|
||||
DESCRIPTION
|
||||
-----------
|
||||
The _zmq_getsockopt()_ function shall retrieve the value for the option
|
||||
specified by the 'option_name' argument for the 0MQ socket pointed to by the
|
||||
'socket' argument, and store it in the buffer pointed to by the 'option_value'
|
||||
argument. The 'option_len' argument is the size in bytes of the buffer pointed
|
||||
to by 'option_value'.
|
||||
|
||||
The following options can be retrieved with the _zmq_getsockopt()_ function:
|
||||
|
||||
|
||||
ZMQ_HWM: Retrieve high water mark
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
The 'ZMQ_HWM' option shall retrieve the high water mark for the _message queue_
|
||||
associated with the specified '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_SWAP: Retrieve disk offload size
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
The 'ZMQ_SWAP' option shall retrieve the disk offload (swap) size for the
|
||||
_message queue_ associated with 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.
|
||||
|
||||
Option value type:: int64_t
|
||||
Option value unit:: bytes
|
||||
Default value:: 0
|
||||
Applicable socket types:: all
|
||||
|
||||
|
||||
ZMQ_AFFINITY: Retrieve I/O thread affinity
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
The 'ZMQ_AFFINITY' option shall retrieve 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_.
|
||||
|
||||
Option value type:: int64_t
|
||||
Option value unit:: N/A (bitmap)
|
||||
Default value:: 0
|
||||
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
|
||||
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 can 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_RATE: Retrieve multicast data rate
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
The 'ZMQ_RATE' option shall retrieve the maximum send or receive data rate for
|
||||
multicast transports 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: Get multicast recovery interval
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
The 'ZMQ_RECOVERY_IVL' option shall retrieve 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.
|
||||
|
||||
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 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
|
||||
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: Retrieve kernel transmit buffer size
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
The 'ZMQ_SNDBUF' option shall retrieve the underlying kernel transmit buffer
|
||||
size for the specified 'socket'. A value of zero means that the OS default is
|
||||
in effect. For details 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: Retrieve kernel receive buffer size
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
The 'ZMQ_RCVBUF' option shall retrieve the underlying kernel receive buffer
|
||||
size for the specified 'socket'. A value of zero means that the OS default is
|
||||
in effect. 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_getsockopt()_ 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, or the size of the buffer pointed to by
|
||||
_option_value_, as specified by _option_len_, is insufficient for storing the
|
||||
option value.
|
||||
|
||||
*ETERM*::
|
||||
The 0MQ 'context' associated with the specified 'socket' was terminated.
|
||||
|
||||
|
||||
EXAMPLE
|
||||
-------
|
||||
.Retrieving the high water mark
|
||||
----
|
||||
/* Retrieve high water mark into hwm */
|
||||
int64_t hwm;
|
||||
rc = zmq_getsockopt (socket, ZMQ_HWM, &hwm, sizeof hwm);
|
||||
assert (rc == 0);
|
||||
----
|
||||
|
||||
|
||||
SEE ALSO
|
||||
--------
|
||||
linkzmq:zmq_setsockopt[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>.
|
||||
@ -20,17 +20,17 @@ The _zmq_setsockopt()_ function shall set the option specified by the
|
||||
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:
|
||||
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 _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.
|
||||
associated with the specified '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".
|
||||
|
||||
@ -43,9 +43,10 @@ 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.
|
||||
queue_ associated with 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.
|
||||
|
||||
@ -57,9 +58,8 @@ 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'.
|
||||
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
|
||||
@ -80,10 +80,10 @@ 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.
|
||||
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
|
||||
@ -146,9 +146,9 @@ 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.
|
||||
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
|
||||
@ -163,11 +163,12 @@ 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.
|
||||
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.
|
||||
|
||||
Option value type:: uint64_t
|
||||
Option value unit:: boolean
|
||||
@ -178,8 +179,8 @@ 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
|
||||
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
|
||||
@ -191,9 +192,9 @@ 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.
|
||||
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
|
||||
@ -214,7 +215,7 @@ The requested option _option_name_ is unknown, or the requested _option_len_ or
|
||||
_option_value_ is invalid.
|
||||
|
||||
*ETERM*::
|
||||
The associated context was terminted.
|
||||
The 0MQ 'context' associated with the specified 'socket' was terminated.
|
||||
|
||||
|
||||
EXAMPLE
|
||||
@ -248,6 +249,7 @@ assert (rc);
|
||||
|
||||
SEE ALSO
|
||||
--------
|
||||
linkzmq:zmq_getsockopt[3]
|
||||
linkzmq:zmq_socket[3]
|
||||
linkzmq:zmq[7]
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user