diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/zmq.txt | 12 | ||||
| -rw-r--r-- | doc/zmq_close.txt | 12 | ||||
| -rw-r--r-- | doc/zmq_errno.txt | 2 | ||||
| -rw-r--r-- | doc/zmq_getsockopt.txt | 116 | ||||
| -rw-r--r-- | doc/zmq_pgm.txt | 6 | ||||
| -rw-r--r-- | doc/zmq_poll.txt | 11 | ||||
| -rw-r--r-- | doc/zmq_setsockopt.txt | 67 | ||||
| -rw-r--r-- | doc/zmq_socket.txt | 24 | ||||
| -rw-r--r-- | doc/zmq_tcp.txt | 6 | ||||
| -rw-r--r-- | doc/zmq_term.txt | 27 | ||||
| -rw-r--r-- | doc/zmq_version.txt | 2 |
11 files changed, 186 insertions, 99 deletions
diff --git a/doc/zmq.txt b/doc/zmq.txt index 06658c9..0c29a74 100644 --- a/doc/zmq.txt +++ b/doc/zmq.txt @@ -44,9 +44,15 @@ Terminate 0MQ context:: Thread safety ^^^^^^^^^^^^^ A 0MQ 'context' is thread safe and may be shared among as many application -threads as necessary, without any additional locking required on the part of the -caller. Each 0MQ socket belonging to a particular 'context' may only be used -by *the thread that created it* using _zmq_socket()_. +threads as necessary, without any additional locking required on the part of +the caller. + +Individual 0MQ 'sockets' are _not_ thread safe except in the case where full +memory barriers are issued when migrating a socket from one thread to another. +In practice this means applications can create a socket in one thread with +_zmq_socket()_ and then pass it to a _newly created_ thread as part of thread +initialization, for example via a structure passed as an argument to +_pthread_create()_. Multiple contexts diff --git a/doc/zmq_close.txt b/doc/zmq_close.txt index 1200fb7..fe3bde5 100644 --- a/doc/zmq_close.txt +++ b/doc/zmq_close.txt @@ -16,10 +16,14 @@ DESCRIPTION ----------- The _zmq_close()_ function shall destroy the socket referenced by the 'socket' argument. Any outstanding messages physically received from the network but not -yet received by the application with _zmq_recv()_ shall also be dropped. As for -the messages sent with _zmq_send()_ but not yet passed to the network, 0MQ -will try to send them in the background after _zmq_close()_ returns. Time spent -attempting can be set using _ZMQ_LINGER_ socket option. +yet received by the application with _zmq_recv()_ shall be discarded. The +behaviour for discarding messages sent by the application with _zmq_send()_ but +not yet physically transferred to the network depends on the value of the +_ZMQ_LINGER_ socket option for the specified 'socket'. + +NOTE: The default setting of _ZMQ_LINGER_ does not discard unsent messages; +this behaviour may cause the application to block when calling _zmq_term()_. +For details refer to linkzmq:zmq_setsockopt[3] and linkzmq:zmq_term[3]. RETURN VALUE diff --git a/doc/zmq_errno.txt b/doc/zmq_errno.txt index 61939a5..6bee0f1 100644 --- a/doc/zmq_errno.txt +++ b/doc/zmq_errno.txt @@ -20,7 +20,7 @@ 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 -runtime library from the C runtime library in use by 0MQ will need to use +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 diff --git a/doc/zmq_getsockopt.txt b/doc/zmq_getsockopt.txt index 40a99b1..7f73e1c 100644 --- a/doc/zmq_getsockopt.txt +++ b/doc/zmq_getsockopt.txt @@ -26,8 +26,8 @@ value stored in the buffer. The following options can be retrieved with the _zmq_getsockopt()_ function: -ZMQ_TYPE: Retrieve socket type. -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +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. @@ -167,13 +167,13 @@ Default value:: 10 Applicable socket types:: all, when using multicast transports -ZMQ_MCAST_LOOP: Control multicast loopback -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +ZMQ_MCAST_LOOP: Control multicast loop-back +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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 +transports can also be received by the sending host via loop-back. A value of +zero indicates that the loop-back functionality is disabled, while the default +value of 1 indicates that the loop-back functionality is enabled. Leaving +multicast loop-back enabled when it is not required can have a negative impact on performance. Where possible, disable 'ZMQ_MCAST_LOOP' in production environments. @@ -214,53 +214,80 @@ Applicable socket types:: all ZMQ_LINGER: Retrieve linger period for socket shutdown ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_LINGER' option shall retrieve the period for pending outbound -messages to linger in memory after closing the socket. Value of -1 means -infinite. Pending messages will be kept until they are fully transferred to -the peer. Value of 0 means that all the pending messages are dropped immediately -when socket is closed. Positive value means number of milliseconds to keep -trying to send the pending messages before discarding them. +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 +Default value:: -1 (infinite) Applicable socket types:: all -ZMQ_RECONNECT_IVL: Retrieve reconnect period for connection-based transports -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_RECONNECT_IVL' option shall retrieve the period indicating how long it -takes for a disconnected underlying connection to attempt to reconnect. +ZMQ_RECONNECT_IVL: Retrieve reconnection interval +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_RECONNECT_IVL' option shall retrieve the reconnection interval for the +specified 'socket'. The reconnection interval is the maximum period 0MQ shall +wait between attempts to reconnect disconnected peers when using +connection-oriented transports. + +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 +Applicable socket types:: all, only for connection-oriented transports -ZMQ_BACKLOG: Retrieve maximum length of the queue of pending connections -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_BACKLOG' option shall retrieve maximum size of the -pending connection backlog for connection-based transports. For details -refer to your operating system documentation for the 'listen' function. +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 +Applicable socket types:: all, only for connection-oriented transports ZMQ_FD: Retrieve file descriptor associated with the socket ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_FD' option shall retrieve file descriptor associated with the 0MQ -socket. The descriptor can be used to integrate 0MQ socket into an existing -event loop. It should never be used for anything else than polling -- such as -reading or writing. The descriptor signals edge-triggered IN event when -something has happened within the 0MQ socket. It does not necessarily mean that -the messages can be read or written. Check ZMQ_EVENTS option to find out whether -the 0MQ socket is readable or writeable. +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. + +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. [horizontal] Option value type:: int on POSIX systems, SOCKET on Windows @@ -269,11 +296,24 @@ Default value:: N/A Applicable socket types:: all -ZMQ_EVENTS: Check whether socket is readable and/or writeable -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_EVENTS' option shall retrieve event flags for the specified socket. -If a message can be read from the socket ZMQ_POLLIN flag is set. If message can -be written to the socket ZMQ_POLLOUT flag is set. +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:: uint32_t diff --git a/doc/zmq_pgm.txt b/doc/zmq_pgm.txt index 4017db2..d9bce5a 100644 --- a/doc/zmq_pgm.txt +++ b/doc/zmq_pgm.txt @@ -24,7 +24,7 @@ The 'pgm' and 'epgm' transports can only be used with the 'ZMQ_PUB' and 'ZMQ_SUB' socket types. Further, PGM sockets are rate limited by default and incur a performance -penalty when used over a loopback interface. For details, refer to the +penalty when used over a loop-back interface. For details, refer to the 'ZMQ_RATE', 'ZMQ_RECOVERY_IVL' and 'ZMQ_MCAST_LOOP' options documented in linkzmq:zmq_setsockopt[3]. @@ -69,7 +69,7 @@ representation. WIRE FORMAT ----------- -Consecutive PGM datagrams are interpreted by 0MQ as a single continous stream +Consecutive PGM datagrams are interpreted by 0MQ as a single continuous stream of data where 0MQ messages are not necessarily aligned with PGM datagram boundaries and a single 0MQ message may span several PGM datagrams. This stream of data consists of 0MQ messages encapsulated in 'frames' as described in @@ -130,7 +130,7 @@ EXAMPLE .Connecting a socket ---- /* Connecting to the multicast address 239.192.1.1, port 5555, */ -/* using the first ethernet network interface on Linux */ +/* using the first Ethernet network interface on Linux */ /* and the Encapsulated PGM protocol */ rc = zmq_connect(socket, "epgm://eth0;239.192.1.1:5555"); assert (rc == 0); diff --git a/doc/zmq_poll.txt b/doc/zmq_poll.txt index f709c07..e8e001c 100644 --- a/doc/zmq_poll.txt +++ b/doc/zmq_poll.txt @@ -40,17 +40,17 @@ NOTE: All 0MQ sockets passed to the _zmq_poll()_ function must share the same 0MQ 'context' and must belong to the thread calling _zmq_poll()_. For each *zmq_pollitem_t* item, _zmq_poll()_ shall first clear the 'revents' -member, and then indicate any requested events that have occured by setting the +member, and then indicate any requested events that have occurred by setting the bit corresponding to the event condition in the 'revents' member. -If none of the requested events have occured on any *zmq_pollitem_t* item, +If none of the requested events have occurred on any *zmq_pollitem_t* item, _zmq_poll()_ shall wait 'timeout' microseconds for an event to occur on any of the requested items. If the value of 'timeout' is `0`, _zmq_poll()_ shall return immediately. If the value of 'timeout' is `-1`, _zmq_poll()_ shall -block indefinitely until a requested event has occured on at least one +block indefinitely until a requested event has occurred on at least one *zmq_pollitem_t*. -The 'events' and 'revents' members of *zmq_pollitem_t* are bitmasks constructed +The 'events' and 'revents' members of *zmq_pollitem_t* are bit masks constructed by OR'ing a combination of the following event flags: *ZMQ_POLLIN*:: @@ -93,7 +93,8 @@ associated 0MQ 'context' was terminated. *EFAULT*:: The provided 'items' was not valid (NULL). *EINTR*:: -The poll was interrupted by delivery of a signal before any event was available. +The operation was interrupted by delivery of a signal before any events were +available. EXAMPLE diff --git a/doc/zmq_setsockopt.txt b/doc/zmq_setsockopt.txt index af92929..86b01e4 100644 --- a/doc/zmq_setsockopt.txt +++ b/doc/zmq_setsockopt.txt @@ -171,13 +171,13 @@ Default value:: 10 Applicable socket types:: all, when using multicast transports -ZMQ_MCAST_LOOP: Control multicast loopback -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +ZMQ_MCAST_LOOP: Control multicast loop-back +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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 +host via loop-back. A value of zero disables the loop-back functionality, while +the default value of 1 enables the loop-back functionality. Leaving multicast +loop-back enabled when it is not required can have a negative impact on performance. Where possible, disable 'ZMQ_MCAST_LOOP' in production environments. @@ -218,44 +218,63 @@ Applicable socket types:: all ZMQ_LINGER: Set linger period for socket shutdown ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_LINGER' option shall be set to specify period for pending outbound -messages to linger in memory after closing the socket. Value of -1 means -infinite. Pending messages will be kept until they are fully transferred to -the peer. Value of 0 means that all the pending messages are dropped immediately -when socket is closed. Positive value means number of milliseconds to keep -trying to send the pending messages before discarding them. +The 'ZMQ_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 +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 +Default value:: -1 (infinite) Applicable socket types:: all -ZMQ_RECONNECT_IVL: Set reconnect period for connection-based transports -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_RECONNECT_IVL' option shall be set to specify how long it takes for a -disconnected underlying connection to attempt to reconnect. The interval -can be randomized to some extent by 0MQ to prevent reconnection storms. +ZMQ_RECONNECT_IVL: Set reconnection interval +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_RECONNECT_IVL' option shall set the reconnection interval for the +specified 'socket'. The reconnection interval is the maximum period 0MQ shall +wait between attempts to reconnect disconnected peers when using +connection-oriented transports. + +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 +Applicable socket types:: all, only for connection-oriented transports -ZMQ_BACKLOG: Set maximum length of the queue of pending connections -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_BACKLOG' option shall be set to specify maximum size of the -pending connection backlog for connection-based transports. For details -refer to your operating system documentation for the 'listen' function. +ZMQ_BACKLOG: Set maximum length of the queue of outstanding connections +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_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 +Applicable socket types:: all, only for connection-oriented transports. RETURN VALUE diff --git a/doc/zmq_socket.txt b/doc/zmq_socket.txt index 2156af2..6bcb133 100644 --- a/doc/zmq_socket.txt +++ b/doc/zmq_socket.txt @@ -35,7 +35,7 @@ sockets transfer streams of bytes or discrete datagrams, 0MQ sockets transfer discrete _messages_. 0MQ sockets being _asynchronous_ means that the timings of the physical -connection setup and teardown, reconnect and effective delivery are transparent +connection setup and tear down, reconnect and effective delivery are transparent to the user and organized by 0MQ itself. Further, messages may be _queued_ in the event that a peer is unavailable to receive them. @@ -46,6 +46,18 @@ relationships. With the exception of 'ZMQ_PAIR', 0MQ sockets may be connected incoming connections *from multiple endpoints* bound to the socket using _zmq_bind()_, thus allowing many-to-many relationships. +.Thread safety +A 0MQ 'context' is thread safe and may be shared among as many application +threads as necessary, without any additional locking required on the part of +the caller. + +Individual 0MQ 'sockets' are _not_ thread safe except in the case where full +memory barriers are issued when migrating a socket from one thread to another. +In practice this means applications can create a socket in one thread with +_zmq_socket()_ and then pass it to a _newly created_ thread as part of thread +initialization, for example via a structure passed as an argument to +_pthread_create()_. + .Socket types The following sections present the socket types defined by 0MQ, grouped by the general _messaging pattern_ which is built from related socket types. @@ -100,7 +112,7 @@ Compatible peer sockets:: 'ZMQ_REQ' Direction:: Bidirectional Send/receive pattern:: Receive, Send, Receive, Send, ... Incoming routing strategy:: Fair-queued -Outgoing routing stratagy:: Last peer +Outgoing routing strategy:: Last peer ZMQ_HWM option action:: Drop @@ -166,13 +178,13 @@ ZMQ_HWM option action:: Drop Publish-subscribe pattern ~~~~~~~~~~~~~~~~~~~~~~~~~ The publish-subscribe pattern is used for one-to-many distribution of data from -a single _publisher_ to multiple _subscribers_ in a fanout fashion. +a single _publisher_ to multiple _subscribers_ in a fan out fashion. ZMQ_PUB ^^^^^^^ A socket of type 'ZMQ_PUB' is used by a _publisher_ to distribute data. -Messages sent are distributed in a fanout fashion to all connected peers. +Messages sent are distributed in a fan out fashion to all connected peers. The linkzmq:zmq_recv[3] function is not implemented for this socket type. When a 'ZMQ_PUB' socket enters an exceptional state due to having reached the @@ -186,7 +198,7 @@ Compatible peer sockets:: 'ZMQ_SUB' Direction:: Unidirectional Send/receive pattern:: Send only Incoming routing strategy:: N/A -Outgoing routing strategy:: Fanout +Outgoing routing strategy:: Fan out ZMQ_HWM option action:: Drop @@ -301,8 +313,6 @@ ERRORS ------ *EINVAL*:: The requested socket 'type' is invalid. -*EMTHREAD*:: -The maximum number of sockets within this 'context' has been exceeded. *EFAULT*:: The provided 'context' was not valid (NULL). diff --git a/doc/zmq_tcp.txt b/doc/zmq_tcp.txt index 29fa181..84ec6c8 100644 --- a/doc/zmq_tcp.txt +++ b/doc/zmq_tcp.txt @@ -30,7 +30,7 @@ colon and the TCP port number to use. An 'interface' may be specified by either of the following: -* The wildcard `*`, meaning all available interfaces. +* The wild-card `*`, meaning all available interfaces. * The primary IPv4 address assigned to the interface, in its numeric representation. * The interface name as defined by the operating system. @@ -127,10 +127,10 @@ EXAMPLES /* TCP port 5555 on all available interfaces */ rc = zmq_bind(socket, "tcp://*:5555"); assert (rc == 0); -/* TCP port 5555 on the local loopback interface on all platforms */ +/* TCP port 5555 on the local loop-back interface on all platforms */ rc = zmq_bind(socket, "tcp://127.0.0.1:5555"); assert (rc == 0); -/* TCP port 5555 on the first ethernet network interface on Linux */ +/* TCP port 5555 on the first Ethernet network interface on Linux */ rc = zmq_bind(socket, "tcp://eth0:5555"); assert (rc == 0); ---- diff --git a/doc/zmq_term.txt b/doc/zmq_term.txt index 6c69b82..2edc765 100644 --- a/doc/zmq_term.txt +++ b/doc/zmq_term.txt @@ -14,20 +14,27 @@ SYNOPSIS DESCRIPTION ----------- -The _zmq_term()_ function terminates the 0MQ context 'context'. +The _zmq_term()_ function shall terminate the 0MQ context 'context'. -It does so in following steps: +Context termination is performed in the following steps: -* It causes any blocking operations currently in progress on sockets open within - 'context' to exit immediately with an error code of ETERM. +1. Any blocking operations currently in progress on sockets open within + 'context' shall return immediately with an error code of ETERM. With the + exception of _zmq_close()_, any further operations on sockets open within + 'context' shall fail with an error code of ETERM. -* With the exception of _zmq_close()_, any further operations on sockets open - within 'context' shall fail with an error code of ETERM. +2. After interrupting all blocking calls, _zmq_term()_ shall _block_ until the + following conditions are satisfied: ++ + * All sockets open within 'context' have been closed with _zmq_close()_. -* After iterrupting all blocking calls, _zmq_term()_ blocks until all sockets - open within the context are closed using _zmq_close()_ and either all the - pending outbound messages are pushed to the network or ZMQ_LINGER period - expires for individual sockets. + * For each socket within 'context', all messages sent by the application + with _zmq_send()_ have either been physically transferred to a network + peer, or the socket's linger period set with the _ZMQ_LINGER_ socket + option has expired. + +For further details regarding socket linger behaviour refer to the _ZMQ_LINGER_ +option in linkzmq:zmq_setsockopt[3]. RETURN VALUE diff --git a/doc/zmq_version.txt b/doc/zmq_version.txt index 0ad3a55..58b7977 100644 --- a/doc/zmq_version.txt +++ b/doc/zmq_version.txt @@ -15,7 +15,7 @@ SYNOPSIS DESCRIPTION ----------- The _zmq_version()_ function shall fill in the integer variables pointed to by -the 'major', 'minor' and 'patch' arguments with the major, minor and patchlevel +the 'major', 'minor' and 'patch' arguments with the major, minor and patch level components of the 0MQ library version. This functionality is intended for applications or language bindings |