rbczmq 1.6.2 → 1.6.4

data/ext/zeromq/doc/zmq_errno.txt

@@ -0,0 +1,50 @@
+zmq_errno(3)
+============
+
+
+NAME
+----
+zmq_errno - retrieve value of errno for the calling thread
+
+
+SYNOPSIS
+--------
+*int zmq_errno (void);*
+
+
+DESCRIPTION
+-----------
+The _zmq_errno()_ function shall retrieve the value of the 'errno' variable for
+the calling thread.
+
+The _zmq_errno()_ function is provided to assist users on non-POSIX systems who
+are experiencing issues with retrieving the correct value of 'errno' directly.
+Specifically, users on Win32 systems whose application is using a different C
+run-time library from the C run-time library in use by 0MQ will need to use
+_zmq_errno()_ for correct operation.
+
+IMPORTANT: Users not experiencing issues with retrieving the correct value of
+'errno' should not use this function and should instead access the 'errno'
+variable directly.
+
+
+RETURN VALUE
+------------
+The _zmq_errno()_ function shall return the value of the 'errno' variable for
+the calling thread.
+
+
+ERRORS
+------
+No errors are defined.
+
+
+SEE ALSO
+--------
+linkzmq:zmq[7]
+
+
+AUTHORS
+-------
+This 0MQ manual page was written by Martin Sustrik <sustrik@250bpm.com> and
+Martin Lucina <mato@kotelna.sk>.

data/ext/zeromq/doc/zmq_getsockopt.txt

@@ -0,0 +1,516 @@
+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'; upon successful completion _zmq_getsockopt()_ shall
+modify the 'option_len' argument to indicate the actual size of the option
+value stored in the buffer.
+
+The following options can be retrieved with the _zmq_getsockopt()_ function:
+
+
+ZMQ_TYPE: Retrieve socket type
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The 'ZMQ_TYPE' option shall retrieve the socket type for the specified
+'socket'.  The socket type is specified at socket creation time and
+cannot be modified afterwards.
+
+[horizontal]
+Option value type:: int
+Option value unit:: N/A
+Default value:: N/A
+Applicable socket types:: all
+
+
+ZMQ_RCVMORE: More message data parts to follow
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The 'ZMQ_RCVMORE' option shall return True (1) if the message part last
+received from the 'socket' was a data part with more parts to follow. If there
+are no data parts to follow, this option shall return False (0).
+
+Refer to linkzmq:zmq_send[3] and linkzmq:zmq_recv[3] for a detailed description
+of multi-part messages.
+
+[horizontal]
+Option value type:: int
+Option value unit:: boolean
+Default value:: N/A
+Applicable socket types:: all
+
+
+ZMQ_SNDHWM: Retrieves high water mark for outbound messages
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The 'ZMQ_SNDHWM' option shall return 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 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.
+
+[horizontal]
+Option value type:: int
+Option value unit:: messages
+Default value:: 1000
+Applicable socket types:: all
+
+
+ZMQ_RCVHWM: Retrieve high water mark for inbound messages
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The 'ZMQ_RCVHWM' option shall return 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 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.
+
+[horizontal]
+Option value type:: int
+Option value unit:: messages
+Default value:: 1000
+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_.
+
+[horizontal]
+Option value type:: uint64_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 retrieve 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 0MQ infrastructure.
+
+[horizontal]
+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'.
+
+[horizontal]
+Option value type:: int
+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 milliseconds that a receiver can be absent from a
+multicast group before unrecoverable data loss will occur.
+
+[horizontal]
+Option value type:: int
+Option value unit:: milliseconds
+Default value:: 10000
+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.
+
+[horizontal]
+Option value type:: int
+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.
+
+[horizontal]
+Option value type:: int
+Option value unit:: bytes
+Default value:: 0
+Applicable socket types:: all
+
+
+ZMQ_LINGER: Retrieve linger period for socket shutdown
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The 'ZMQ_LINGER' option shall retrieve 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: Retrieve reconnection interval
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The 'ZMQ_RECONNECT_IVL' option shall retrieve 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. The value -1 means no reconnection.
+
+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: Retrieve maximum reconnection interval
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The 'ZMQ_RECONNECT_IVL_MAX' option shall retrieve 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 transport
+
+
+ZMQ_BACKLOG: Retrieve maximum length of the queue of outstanding connections
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The 'ZMQ_BACKLOG' option shall retrieve 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
+
+
+ZMQ_MAXMSGSIZE: Maximum acceptable inbound message size
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The option shall retrieve limit for the inbound messages. If a peer sends
+a message larger than ZMQ_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
+
+
+ZMQ_MULTICAST_HOPS: Maximum network hops for multicast packets
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The option shall retrieve time-to-live used for outbound multicast packets.
+The default of 1 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
+
+
+ZMQ_RCVTIMEO: Maximum time before a socket operation returns with EAGAIN
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Retrieve the timeout for recv operation on the socket.  If the value is `0`,
+_zmq_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
+
+
+ZMQ_SNDTIMEO: Maximum time before a socket operation returns with EAGAIN
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Retrieve the timeout for send operation on the socket. If the value is `0`,
+_zmq_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
+
+
+ZMQ_IPV4ONLY: Retrieve IPv4-only socket override status
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Retrieve 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.
+
+
+ZMQ_DELAY_ATTACH_ON_CONNECT: Retrieve attach-on-connect value
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Retrieve the state of the attach on connect value. If set to `1`, will delay the
+attachment of a pipe on connect until the underlying connection has completed.
+This will cause the socket to block if there are no other connections, but will
+prevent queues from filling on pipes awaiting connection.
+
+[horizontal]
+Option value type:: int
+Option value unit:: boolean
+Default value:: 0 (false)
+Applicable socket types:: all, primarily when using TCP/IPC transports.
+
+
+ZMQ_FD: Retrieve file descriptor associated with the socket
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The 'ZMQ_FD' option shall retrieve the file descriptor associated with the
+specified 'socket'. The returned file descriptor can be used to integrate the
+socket into an existing event loop; the 0MQ library shall signal any pending
+events on the socket in an _edge-triggered_ fashion by making the file
+descriptor become ready for reading.
+
+NOTE: The ability to read from the returned file descriptor does not
+necessarily indicate that messages are available to be read from, or can be
+written to, the underlying socket; applications must retrieve the actual event
+state with a subsequent retrieval of the 'ZMQ_EVENTS' option.
+
+NOTE: The returned file descriptor is also used internally by the 'zmq_send' 
+and 'zmq_recv' functions. As the descriptor is edge triggered, applications 
+must update the state of 'ZMQ_EVENTS' after each invocation of 'zmq_send' 
+or 'zmq_recv'.To be more explicit: after calling 'zmq_send' the socket may 
+become readable (and vice versa) without triggering a read event on the 
+file descriptor.
+
+CAUTION: The returned file descriptor is intended for use with a 'poll' or
+similar system call only. Applications must never attempt to read or write data
+to it directly, neither should they try to close it.
+
+[horizontal]
+Option value type:: int on POSIX systems, SOCKET on Windows
+Option value unit:: N/A
+Default value:: N/A
+Applicable socket types:: all
+
+
+ZMQ_EVENTS: Retrieve socket event state
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The 'ZMQ_EVENTS' option shall retrieve the event state for the specified
+'socket'.  The returned value is a bit mask constructed by OR'ing a combination
+of the following event flags:
+
+*ZMQ_POLLIN*::
+Indicates that at least one message may be received from the specified socket
+without blocking.
+
+*ZMQ_POLLOUT*::
+Indicates that at least one message may be sent to the specified socket without
+blocking.
+
+The combination of a file descriptor returned by the 'ZMQ_FD' option being
+ready for reading but no actual events returned by a subsequent retrieval of
+the 'ZMQ_EVENTS' option is valid; applications should simply ignore this case
+and restart their polling operation/event loop.
+
+[horizontal]
+Option value type:: int
+Option value unit:: N/A (flags)
+Default value:: N/A
+Applicable socket types:: all
+
+
+ZMQ_LAST_ENDPOINT: Retrieve the last endpoint set
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The 'ZMQ_LAST_ENDPOINT' option shall retrieve the last endpoint bound for 
+TCP and IPC transports. The returned value will be a string in the form of
+a ZMQ DSN. Note that if the TCP host is INADDR_ANY, indicated by a *, then
+the returned address will be 0.0.0.0 (for IPv4).
+
+[horizontal]
+Option value type:: character string
+Option value unit:: N/A
+Default value:: NULL
+Applicable socket types:: all, when binding TCP or IPC transports
+
+
+ZMQ_TCP_KEEPALIVE: Override SO_KEEPALIVE socket option
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Override 'SO_KEEPALIVE' socket option(where supported by OS).
+The default value of `-1` means to skip any overrides and leave it to OS default.
+
+[horizontal]
+Option value type:: int
+Option value unit:: -1,0,1
+Default value:: -1 (leave to OS default)
+Applicable socket types:: all, when using TCP transports.
+
+
+ZMQ_TCP_KEEPALIVE_IDLE: Override TCP_KEEPCNT(or TCP_KEEPALIVE on some OS)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Override 'TCP_KEEPCNT'(or 'TCP_KEEPALIVE' on some OS) socket option(where supported by OS).
+The default value of `-1` means to skip any overrides and leave it to OS default.
+
+[horizontal]
+Option value type:: int
+Option value unit:: -1,>0
+Default value:: -1 (leave to OS default)
+Applicable socket types:: all, when using TCP transports.
+
+
+ZMQ_TCP_KEEPALIVE_CNT: Override TCP_KEEPCNT socket option
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Override 'TCP_KEEPCNT' socket option(where supported by OS).
+The default value of `-1` means to skip any overrides and leave it to OS default.
+
+[horizontal]
+Option value type:: int
+Option value unit:: -1,>0
+Default value:: -1 (leave to OS default)
+Applicable socket types:: all, when using TCP transports.
+
+
+ZMQ_TCP_KEEPALIVE_INTVL: Override TCP_KEEPINTVL socket option
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Override 'TCP_KEEPINTVL' socket option(where supported by OS).
+The default value of `-1` means to skip any overrides and leave it to OS default.
+
+[horizontal]
+Option value type:: int
+Option value unit:: -1,>0
+Default value:: -1 (leave to OS default)
+Applicable socket types:: all, when using TCP transports.
+
+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.
+*ENOTSOCK*::
+The provided 'socket' was invalid.
+*EINTR*::
+The operation was interrupted by delivery of a signal.
+
+
+EXAMPLE
+-------
+.Retrieving the high water mark for outgoing messages
+----
+/* Retrieve high water mark into sndhwm */
+int sndhwm;
+size_t sndhwm_size = sizeof (sndhwm);
+rc = zmq_getsockopt (socket, ZMQ_SNDHWM, &sndhwm, &sndhwm_size);
+assert (rc == 0);
+----
+
+
+SEE ALSO
+--------
+linkzmq:zmq_setsockopt[3]
+linkzmq:zmq_socket[3]
+linkzmq:zmq[7]
+
+
+AUTHORS
+-------
+This 0MQ manual page was written by Martin Sustrik <sustrik@250bpm.com> and
+Martin Lucina <mato@kotelna.sk>.