mirror of
https://github.com/zeromq/libzmq.git
synced 2025-03-04 07:27:26 +01:00
Documentation updates for 2.1
- Clarify ZMQ_LINGER, zmq_close (), zmq_term () relationship - New socket options - Clarify thread safety of sockets and migration between threads - Other minor and spelling fixes Signed-off-by: Martin Lucina <mato@kotelna.sk>
This commit is contained in:
Martin Lucina
Martin Sustrik
parent
5bb0a339be
commit
b70d628fad
12
doc/zmq.txt
12
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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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);
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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).
|
||||
|
||||
|
||||
@ -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);
|
||||
----
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user