From 4a7aad06d95701cf232198093ce396dcdbb53e5b Mon Sep 17 00:00:00 2001 From: Martin Sustrik Date: Thu, 16 Feb 2012 10:01:47 +0900 Subject: ZeroMQ renamed to Crossroads Signed-off-by: Martin Sustrik --- doc/xs_setsockopt.txt | 410 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 410 insertions(+) create mode 100644 doc/xs_setsockopt.txt (limited to 'doc/xs_setsockopt.txt') diff --git a/doc/xs_setsockopt.txt b/doc/xs_setsockopt.txt new file mode 100644 index 0000000..7cb91d2 --- /dev/null +++ b/doc/xs_setsockopt.txt @@ -0,0 +1,410 @@ +xs_setsockopt(3) +================ + + +NAME +---- + +xs_setsockopt - set Crossroads socket options + + +SYNOPSIS +-------- +*int xs_setsockopt (void '*socket', int 'option_name', const void '*option_value', size_t 'option_len');* + +Caution: All options, with the exception of XS_SUBSCRIBE, XS_UNSUBSCRIBE and +XS_LINGER, only take effect for subsequent socket bind/connects. + +DESCRIPTION +----------- +The _xs_setsockopt()_ function shall set the option specified by the +'option_name' argument to the value pointed to by the 'option_value' argument +for the Crossroads 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 _xs_setsockopt()_ function: + + +XS_SNDHWM: Set high water mark for outbound messages +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'XS_SNDHWM' option shall set the high water mark for outbound messages on +the specified 'socket'. The high water mark is a hard limit on the maximum +number of outstanding messages the library 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, the library shall take appropriate action such as +blocking or dropping sent messages. Refer to the individual socket descriptions +in linkxs:xs_socket[3] for details on the exact action taken for each socket +type. + +[horizontal] +Option value type:: int +Option value unit:: messages +Default value:: 1000 +Applicable socket types:: all + + +XS_RCVHWM: Set high water mark for inbound messages +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'XS_RCVHWM' option shall set the high water mark for inbound messages on +the specified 'socket'. The high water mark is a hard limit on the maximum +number of outstanding messages the libray 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, the library shall take appropriate action such as +blocking or dropping sent messages. Refer to the individual socket descriptions +in linkxs:xs_socket[3] for details on the exact action taken for each socket +type. + +[horizontal] +Option value type:: int +Option value unit:: messages +Default value:: 1000 +Applicable socket types:: all + + +XS_AFFINITY: Set I/O thread affinity +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'XS_AFFINITY' option shall set the I/O thread affinity for newly created +connections on the specified 'socket'. + +Affinity determines which threads from the Crossroads 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 Crossroads 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 linkxs:xs_init[3] for details on allocating the number of I/O +threads for a specific _context_. + +[horizontal] +Option value type:: uint64_t +Option value unit:: N/A (bitmap) +Default value:: 0 +Applicable socket types:: N/A + + +XS_SUBSCRIBE: Establish message filter +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'XS_SUBSCRIBE' option shall establish a new message filter on a 'XS_SUB' +socket. Newly created 'XS_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. Multiple filters may be attached to a single +'XS_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:: XS_SUB + + +XS_UNSUBSCRIBE: Remove message filter +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'XS_UNSUBSCRIBE' option shall remove an existing message filter on a +'XS_SUB' socket. The filter specified must match an existing filter previously +established with the 'XS_SUBSCRIBE' option. If the socket has several +instances of the same filter attached the 'XS_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:: XS_SUB + + +XS_IDENTITY: Set socket identity +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'XS_IDENTITY' option shall set the identity of the specified 'socket'. +Socket identity is used only by request/reply pattern. Namely, it can be used +in tandem with ROUTER socket to route messages to the peer with specific +identity. + +Identity should be at least one byte and at most 255 bytes long. Identities +starting with binary zero are reserved for use by Crossroads infrastructure. + +[horizontal] +Option value type:: binary data +Option value unit:: N/A +Default value:: NULL +Applicable socket types:: all + + +XS_RATE: Set multicast data rate +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'XS_RATE' option shall set the maximum send or receive data rate for +multicast transports such as linkxs:xs_pgm[7] using the specified 'socket'. + +[horizontal] +Option value type:: int +Option value unit:: kilobits per second +Default value:: 100 +Applicable socket types:: all, when using multicast transports + + +XS_RECOVERY_IVL: Set multicast recovery interval +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'XS_RECOVERY_IVL' option shall set the recovery interval 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. + +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:: int +Option value unit:: milliseconds +Default value:: 10000 +Applicable socket types:: all, when using multicast transports + +XS_SNDBUF: Set kernel transmit buffer size +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'XS_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:: int +Option value unit:: bytes +Default value:: 0 +Applicable socket types:: all + + +XS_RCVBUF: Set kernel receive buffer size +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'XS_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:: int +Option value unit:: bytes +Default value:: 0 +Applicable socket types:: all + + +XS_LINGER: Set linger period for socket shutdown +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'XS_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 +linkxs:xs_close[3], and further affects the termination of the socket's +context with linkxs:xs_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 _xs_close()_; attempting to + terminate the socket's context with _xs_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 _xs_close()_. + +* Positive values specify an upper bound for the linger period in milliseconds. + Pending messages shall not be discarded after a call to _xs_close()_; + attempting to terminate the socket's context with _xs_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 + + +XS_RECONNECT_IVL: Set reconnection interval +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'XS_RECONNECT_IVL' option shall set the initial reconnection interval for +the specified 'socket'. The reconnection interval is the period the library +shall wait between attempts to reconnect disconnected peers when using +connection-oriented transports. + +NOTE: The reconnection interval may be randomized by the library 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 + + +XS_RECONNECT_IVL_MAX: Set maximum reconnection interval +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'XS_RECONNECT_IVL_MAX' option shall set the maximum reconnection interval +for the specified 'socket'. This is the maximum period the library shall wait +between attempts to reconnect. On each reconnect attempt, the previous interval +shall be doubled untill XS_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 +XS_RECONNECT_IVL. + +NOTE: Values less than XS_RECONNECT_IVL will be ignored. + +[horizontal] +Option value type:: int +Option value unit:: milliseconds +Default value:: 0 (only use XS_RECONNECT_IVL) +Applicable socket types:: all, only for connection-oriented transports + + +XS_BACKLOG: Set maximum length of the queue of outstanding connections +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'XS_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. + + +XS_MAXMSGSIZE: Maximum acceptable inbound message size +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Limits the size of the inbound message. If a peer sends a message larger than +XS_MAXMSGSIZE it is disconnected. Value of -1 means 'no limit'. + +[horizontal] +Option value type:: int64_t +Option value unit:: bytes +Default value:: -1 +Applicable socket types:: all + + +XS_MULTICAST_HOPS: Maximum network hops for multicast packets +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Sets the time-to-live field in every multicast packet sent from this socket. +The default is 1 which means that the multicast packets don't leave the local +network. + +[horizontal] +Option value type:: int +Option value unit:: network hops +Default value:: 1 +Applicable socket types:: all, when using multicast transports + + +XS_RCVTIMEO: Maximum time before a recv operation returns with EAGAIN +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Sets the timeout for receive operation on the socket. If the value is `0`, +_xs_recv(3)_ will return immediately, with a EAGAIN error if there is no +message to receive. If the value is `-1`, it will block until a message is +available. For all other values, it will wait for a message for that amount +of time before returning with an EAGAIN error. + +[horizontal] +Option value type:: int +Option value unit:: milliseconds +Default value:: -1 (infinite) +Applicable socket types:: all + + +XS_SNDTIMEO: Maximum time before a send operation returns with EAGAIN +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Sets the timeout for send operation on the socket. If the value is `0`, +_xs_send(3)_ will return immediately, with a EAGAIN error if the message +cannot be sent. If the value is `-1`, it will block until the message is sent. +For all other values, it will try to send the message for that amount of time +before returning with an EAGAIN error. + +[horizontal] +Option value type:: int +Option value unit:: milliseconds +Default value:: -1 (infinite) +Applicable socket types:: all + + +XS_IPV4ONLY: Use IPv4-only sockets +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Sets the underlying native socket type. A value of `1` will use IPv4 sockets, +while the value of `0` will use IPv6 sockets. An IPv6 socket lets +applications connect to and accept connections from both IPv4 and IPv6 hosts. + +[horizontal] +Option value type:: int +Option value unit:: boolean +Default value:: 1 (true) +Applicable socket types:: all, when using TCP transports. + + +RETURN VALUE +------------ +The _xs_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 'context' associated with the specified 'socket' was terminated. +*ENOTSOCK*:: +The provided 'socket' was invalid. +*EINTR*:: +The operation was interrupted by delivery of a signal. + + +EXAMPLE +------- +.Subscribing to messages on a 'XS_SUB' socket +---- +/* Subscribe to all messages */ +rc = xs_setsockopt (socket, XS_SUBSCRIBE, "", 0); +assert (rc == 0); +/* Subscribe to messages prefixed with "ANIMALS.CATS" */ +rc = xs_setsockopt (socket, XS_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 = xs_setsockopt (socket, XS_AFFINITY, &affinity, sizeof affinity); +assert (rc); +rc = xs_bind (socket, "tcp://lo:5555"); +assert (rc); +/* Incoming connections on TCP port 5556 shall be handled by I/O thread 2 */ +affinity = 2; +rc = xs_setsockopt (socket, XS_AFFINITY, &affinity, sizeof affinity); +assert (rc); +rc = xs_bind (socket, "tcp://lo:5556"); +assert (rc); +---- + + +SEE ALSO +-------- +linkxs:xs_getsockopt[3] +linkxs:xs_socket[3] +linkxs:xs[7] + + +AUTHORS +------- +The Crossroads documentation was written by Martin Sustrik +and Martin Lucina . -- cgit v1.2.3