From d95f8c5f5575dd88b475fda2ad94fa7fb783d923 Mon Sep 17 00:00:00 2001 From: Martin Hurton Date: Wed, 24 Oct 2012 22:05:45 +0200 Subject: [PATCH 1/3] Resolve LIBZMQ-417 Ref: https://zeromq.jira.com/browse/LIBZMQ-417 --- src/session_base.cpp | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/session_base.cpp b/src/session_base.cpp index 73a018e1..b2676570 100644 --- a/src/session_base.cpp +++ b/src/session_base.cpp @@ -223,7 +223,7 @@ void zmq::session_base_t::clean_pipes () msg_t msg; int rc = msg.init (); errno_assert (rc == 0); - if (!pull_msg (&msg)) { + if (pull_msg (&msg) != 0) { zmq_assert (!incomplete_in); break; } From d9d7d9be545635b929d6803b94e70a8caf564dd5 Mon Sep 17 00:00:00 2001 From: Martin Hurton Date: Wed, 24 Oct 2012 23:46:58 +0200 Subject: [PATCH 2/3] Resolve LIBZMQ-452 Ref: https://zeromq.jira.com/browse/LIBZMQ-452 --- tests/test_connect_delay.cpp | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/tests/test_connect_delay.cpp b/tests/test_connect_delay.cpp index 4742aa5a..752698d6 100644 --- a/tests/test_connect_delay.cpp +++ b/tests/test_connect_delay.cpp @@ -19,6 +19,7 @@ along with this program. If not, see . */ #include "../include/zmq.h" +#include "../include/zmq_utils.h" #include #include #include @@ -86,7 +87,7 @@ static void *server (void *) rc = zmq_term (context); assert (rc == 0); - pthread_exit(NULL); + return NULL; } static void *worker (void *) @@ -129,7 +130,7 @@ static void *worker (void *) rc = zmq_term (context); assert (rc == 0); - pthread_exit(NULL); + return NULL; } int main (void) @@ -170,7 +171,7 @@ int main (void) assert(rc >= 0); } - sleep(1); + zmq_sleep (1); seen = 0; for (int i = 0; i < 10; ++i) { @@ -229,7 +230,7 @@ int main (void) assert (rc >= 0); } - sleep(1); + zmq_sleep (1); seen = 0; for (int i = 0; i < 10; ++i) From 09c56c44932eaf309bcd74f2400bc2b204d9bcec Mon Sep 17 00:00:00 2001 From: Pieter Hintjens Date: Sat, 27 Oct 2012 09:45:01 +0900 Subject: [PATCH 3/3] Cleanups to man pages --- doc/zmq_bind.txt | 49 ++++++++++--------- doc/zmq_connect.txt | 57 ++++++++++++----------- doc/zmq_inproc.txt | 28 +++++------ doc/zmq_ipc.txt | 39 +++++++++------- doc/zmq_pgm.txt | 32 ++++++------- doc/zmq_socket.txt | 52 ++++++++++----------- doc/zmq_tcp.txt | 111 ++++++++++---------------------------------- 7 files changed, 158 insertions(+), 210 deletions(-) diff --git a/doc/zmq_bind.txt b/doc/zmq_bind.txt index 58bc4d80..d45ba8c3 100644 --- a/doc/zmq_bind.txt +++ b/doc/zmq_bind.txt @@ -4,7 +4,7 @@ zmq_bind(3) NAME ---- -zmq_bind - accept connections on a socket +zmq_bind - accept incoming connections on a socket SYNOPSIS @@ -14,34 +14,41 @@ SYNOPSIS DESCRIPTION ----------- -The _zmq_bind()_ function shall create an endpoint for accepting connections -and bind it to the socket referenced by the 'socket' argument. +The _zmq_bind()_ function binds the 'socket' to a local 'endpoint' and then +accepts incoming connections on that endpoint. -The 'endpoint' argument is a string consisting of two parts as follows: -'transport'`://`'address'. The 'transport' part specifies the underlying -transport protocol to use. The meaning of the 'address' part is specific to -the underlying transport protocol selected. +The 'endpoint' is a string consisting of a 'transport'`://` followed by an +'address'. The 'transport' specifies the underlying protocol to use. The +'address' specifies the transport-specific address to bind to. -The following transports are defined: +0MQ provides the the following transports: -'inproc':: local in-process (inter-thread) communication transport, see linkzmq:zmq_inproc[7] -'ipc':: local inter-process communication transport, see linkzmq:zmq_ipc[7] 'tcp':: unicast transport using TCP, see linkzmq:zmq_tcp[7] +'ipc':: local inter-process communication transport, see linkzmq:zmq_ipc[7] +'inproc':: local in-process (inter-thread) communication transport, see linkzmq:zmq_inproc[7] 'pgm', 'epgm':: reliable multicast transport using PGM, see linkzmq:zmq_pgm[7] -ZeroMQ sockets support one-to-many and many-to-one semantics. With the exception -of 'ZMQ_PAIR' sockets every ZeroMQ socket type supports being bound with -_zmq_bind()_ as a singular endpoint or connecting with _zmq_connect()_ as one -of many endpoints. This allows combinations such as 1 ZMQ_REP to 100 ZMQ_REP and -100 ZMQ_REQ to 1 ZMQ_REP socket connections. Refer to linkzmq:zmq_socket[3] for -a description of the exact semantics involved when connecting or binding a socket -to multiple endpoints. +Every 0MQ socket type except 'ZMQ_PAIR' supports one-to-many and many-to-one +semantics. The precise semantics depend on the socket type and are defined in +linkzmq:zmq_socket[3]. + +The 'ipc' and 'tcp' transports accept wildcard addresses: see linkzmq:zmq_ipc[7] +and linkzmq:zmq_tcp[7] for details. + +NOTE: the address syntax may be different for _zmq_bind()_ and _zmq_connect()_ +especially for the 'tcp', 'pgm' and 'epgm' transports. + +NOTE: following a _zmq_bind()_, the socket enters a 'mute' state unless or +until at least one incoming or outgoing connection is made, at which point +the socket enters a 'ready' state. In the mute state, the socket blocks or +drops messages according to the socket type, as defined in linkzmq:zmq_socket[3]. +By contrast, following a libzmq:zmq_connect[3], the socket enters the 'ready' state. RETURN VALUE ------------ -The _zmq_bind()_ function shall return zero if successful. Otherwise it shall -return `-1` and set 'errno' to one of the values defined below. +The _zmq_bind()_ function returns zero if successful. Otherwise it returns +`-1` and sets 'errno' to one of the values defined below. ERRORS @@ -91,5 +98,5 @@ linkzmq:zmq[7] AUTHORS ------- -This 0MQ manual page was written by Martin Sustrik and -Martin Lucina . +This 0MQ manual page was written by Pieter Hintjens , +Martin Sustrik and Martin Lucina . diff --git a/doc/zmq_connect.txt b/doc/zmq_connect.txt index d9c37cd4..8028e381 100644 --- a/doc/zmq_connect.txt +++ b/doc/zmq_connect.txt @@ -4,7 +4,7 @@ zmq_connect(3) NAME ---- -zmq_connect - connect a socket +zmq_connect - create outgoing connection from socket SYNOPSIS @@ -14,42 +14,43 @@ SYNOPSIS DESCRIPTION ----------- -The _zmq_connect()_ function shall connect the socket referenced by the -'socket' argument to the endpoint specified by the 'endpoint' argument. +The _zmq_connect()_ function connects the 'socket' to an 'endpoint' and then +accepts incoming connections on that endpoint. -The 'endpoint' argument is a string consisting of two parts as follows: -'transport'`://`'address'. The 'transport' part specifies the underlying -transport protocol to use. The meaning of the 'address' part is specific to -the underlying transport protocol selected. +The 'endpoint' is a string consisting of a 'transport'`://` followed by an +'address'. The 'transport' specifies the underlying protocol to use. The +'address' specifies the transport-specific address to connect to. -The following transports are defined: +0MQ provides the the following transports: -'inproc':: local in-process (inter-thread) communication transport, see linkzmq:zmq_inproc[7] -'ipc':: local inter-process communication transport, see linkzmq:zmq_ipc[7] 'tcp':: unicast transport using TCP, see linkzmq:zmq_tcp[7] +'ipc':: local inter-process communication transport, see linkzmq:zmq_ipc[7] +'inproc':: local in-process (inter-thread) communication transport, see linkzmq:zmq_inproc[7] 'pgm', 'epgm':: reliable multicast transport using PGM, see linkzmq:zmq_pgm[7] -ZeroMQ sockets support one-to-many and many-to-one semantics. With the exception -of 'ZMQ_PAIR' sockets every ZeroMQ socket type supports being bound with -_zmq_bind()_ as a singular endpoint or connecting with _zmq_connect()_ as one -of many endpoints. This allows combinations such as 1 ZMQ_REP to 100 ZMQ_REP and -100 ZMQ_REQ to 1 ZMQ_REP socket connections. Refer to linkzmq:zmq_socket[3] for -a description of the exact semantics involved when connecting or binding a socket -to multiple endpoints. +Every 0MQ socket type except 'ZMQ_PAIR' supports one-to-many and many-to-one +semantics. The precise semantics depend on the socket type and are defined in +linkzmq:zmq_socket[3]. -NOTE: The connection will not be performed immediately but as needed by 0MQ. -Thus a successful invocation of _zmq_connect()_ does not indicate that a -physical connection was or can actually be established. Because of this, for most -socket types the order in which a listening socket is bound and a connecting socket -is connected does not matter. However, for inproc:// scheme sockets, the zmq_bind() -must be executed before any sockets zmq_connect() to that endpoint. Refer to -linkzmq:zmq_inproc[7] for more details. +NOTE: for most transports and socket types the connection is not performed +immediately but as needed by 0MQ. Thus a successful call to _zmq_connect()_ +does not mean that the connection was or could actually be established. +Because of this, for most transports and socket types the order in which +a 'server' socket is bound and a 'client' socket is connected to it does not +matter. The first exception is when using the inproc:// transport: you must +call _zmq_bind()_ before calling _zmq_connect()_. The second exception are +_ZMQ_PAIR_ sockets, which do not automatically reconnect to endpoints. + +NOTE: following a _zmq_connect()_, the socket enters its normal 'ready' state. +By contrast, following a _zmq_bind()_ alone, the socket enters a 'mute' state +in which the socket blocks or drops messages according to the socket type, as +defined in linkzmq:zmq_socket[3]. RETURN VALUE ------------ -The _zmq_connect()_ function shall return zero if successful. Otherwise it -shall return `-1` and set 'errno' to one of the values defined below. +The _zmq_connect()_ function returns zero if successful. Otherwise it returns +`-1` and sets 'errno' to one of the values defined below. ERRORS @@ -93,5 +94,5 @@ linkzmq:zmq[7] AUTHORS ------- -This 0MQ manual page was written by Martin Sustrik and -Martin Lucina . +This 0MQ manual page was written by Pieter Hintjens , +Martin Sustrik and Martin Lucina . diff --git a/doc/zmq_inproc.txt b/doc/zmq_inproc.txt index e68e14b0..c6e3ea87 100644 --- a/doc/zmq_inproc.txt +++ b/doc/zmq_inproc.txt @@ -20,11 +20,12 @@ linkzmq:zmq_init[3] for details. ADDRESSING ---------- -A 0MQ address string consists of two parts as follows: -'transport'`://`'endpoint'. The 'transport' part specifies the underlying -transport protocol to use, and for the in-process transport shall be set to -`inproc`. The meaning of the 'endpoint' part for the in-process transport is -defined below. +A 0MQ endpoint is a string consisting of a 'transport'`://` followed by an +'address'. The 'transport' specifies the underlying protocol to use. The +'address' specifies the transport-specific address to connect to. + +For the in-process transport, the transport is `inproc`, and the meaning of +the 'address' part is defined below. Assigning a local address to a socket @@ -45,29 +46,24 @@ created by assigning it to at least one 'socket' within the same 0MQ 'context' as the 'socket' being connected. -WIRE FORMAT ------------ -Not applicable. - - EXAMPLES -------- .Assigning a local address to a socket ---- -/* Assign the in-process name "#1" */ +// Assign the in-process name "#1" rc = zmq_bind(socket, "inproc://#1"); assert (rc == 0); -/* Assign the in-process name "my-endpoint" */ +// Assign the in-process name "my-endpoint" rc = zmq_bind(socket, "inproc://my-endpoint"); assert (rc == 0); ---- .Connecting a socket ---- -/* Connect to the in-process name "#1" */ +// Connect to the in-process name "#1" rc = zmq_connect(socket, "inproc://#1"); assert (rc == 0); -/* Connect to the in-process name "my-endpoint" */ +// Connect to the in-process name "my-endpoint" rc = zmq_connect(socket, "inproc://my-endpoint"); assert (rc == 0); ---- @@ -85,5 +81,5 @@ linkzmq:zmq[7] AUTHORS ------- -This 0MQ manual page was written by Martin Sustrik and -Martin Lucina . +This 0MQ manual page was written by Pieter Hintjens , +Martin Sustrik and Martin Lucina . diff --git a/doc/zmq_ipc.txt b/doc/zmq_ipc.txt index 974ad244..4d9f6f1f 100644 --- a/doc/zmq_ipc.txt +++ b/doc/zmq_ipc.txt @@ -18,22 +18,31 @@ systems that provide UNIX domain sockets. ADDRESSING ---------- -A 0MQ address string consists of two parts as follows: -'transport'`://`'endpoint'. The 'transport' part specifies the underlying -transport protocol to use, and for the inter-process transport shall be set to -`ipc`. The meaning of the 'endpoint' part for the inter-process transport is -defined below. +A 0MQ endpoint is a string consisting of a 'transport'`://` followed by an +'address'. The 'transport' specifies the underlying protocol to use. The +'address' specifies the transport-specific address to connect to. + +For the inter-process transport, the transport is `ipc`, and the meaning of +the 'address' part is defined below. -Assigning a local address to a socket -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -When assigning a local address to a 'socket' using _zmq_bind()_ with the 'ipc' +Binding a socket +~~~~~~~~~~~~~~~~ +When binding a 'socket' to a local address using _zmq_bind()_ with the 'ipc' transport, the 'endpoint' shall be interpreted as an arbitrary string identifying the 'pathname' to create. The 'pathname' must be unique within the operating system namespace used by the 'ipc' implementation, and must fulfill any restrictions placed by the operating system on the format and length of a 'pathname'. +When the address is `*`, _zmq_bind()_ shall generate a unique temporary +pathname. The caller should retrieve this pathname using the ZMQ_LAST_ENDPOINT +socket option. See linkzmq:zmq_getsockopt[3] for details. + +NOTE: any existing binding to the same endpoint shall be overridden. In this +behavior, the 'ipc' transport is not consistent with the 'tcp' or 'inproc' +transports. + Connecting a socket ~~~~~~~~~~~~~~~~~~~ When connecting a 'socket' to a peer address using _zmq_connect()_ with the @@ -43,23 +52,18 @@ previously created within the operating system namespace by assigning it to a 'socket' with _zmq_bind()_. -WIRE FORMAT ------------ -Not applicable. - - EXAMPLES -------- .Assigning a local address to a socket ---- -/* Assign the pathname "/tmp/feeds/0" */ +// Assign the pathname "/tmp/feeds/0" rc = zmq_bind(socket, "ipc:///tmp/feeds/0"); assert (rc == 0); ---- .Connecting a socket ---- -/* Connect to the pathname "/tmp/feeds/0" */ +// Connect to the pathname "/tmp/feeds/0" rc = zmq_connect(socket, "ipc:///tmp/feeds/0"); assert (rc == 0); ---- @@ -71,10 +75,11 @@ linkzmq:zmq_connect[3] linkzmq:zmq_inproc[7] linkzmq:zmq_tcp[7] linkzmq:zmq_pgm[7] +linkzmq:zmq_getsockopt[3] linkzmq:zmq[7] AUTHORS ------- -This 0MQ manual page was written by Martin Sustrik and -Martin Lucina . +This 0MQ manual page was written by Pieter Hintjens , +Martin Sustrik and Martin Lucina . diff --git a/doc/zmq_pgm.txt b/doc/zmq_pgm.txt index c583f82e..7b6b9851 100644 --- a/doc/zmq_pgm.txt +++ b/doc/zmq_pgm.txt @@ -17,8 +17,8 @@ DESCRIPTION ----------- 0MQ implements two variants of PGM, the standard protocol where PGM datagrams are layered directly on top of IP datagrams as defined by RFC 3208 (the 'pgm' -transport) and "Encapsulated PGM" where PGM datagrams are encapsulated inside -UDP datagrams (the 'epgm' transport). +transport) and "Encapsulated PGM" or EPGM where PGM datagrams are encapsulated +inside UDP datagrams (the 'epgm' transport). The 'pgm' and 'epgm' transports can only be used with the 'ZMQ_PUB' and 'ZMQ_SUB' socket types. @@ -36,12 +36,12 @@ not require any special privileges. ADDRESSING ---------- -A 0MQ address string consists of two parts as follows: -'transport'`://`'endpoint'. The 'transport' part specifies the underlying -transport protocol to use. For the standard PGM protocol, 'transport' shall be -set to `pgm`. For the "Encapsulated PGM" protocol 'transport' shall be set to -`epgm`. The meaning of the 'endpoint' part for both the 'pgm' and 'epgm' -transport is defined below. +A 0MQ endpoint is a string consisting of a 'transport'`://` followed by an +'address'. The 'transport' specifies the underlying protocol to use. The +'address' specifies the transport-specific address to connect to. + +For the PGM transport, the transport is `pgm`, and for the EPGM protocol the +transport is `epgm`. The meaning of the 'address' part is defined below. Connecting a socket @@ -134,14 +134,14 @@ EXAMPLE ------- .Connecting a socket ---- -/* Connecting to the multicast address 239.192.1.1, port 5555, */ -/* using the first Ethernet network interface on Linux */ -/* and the Encapsulated PGM protocol */ +// Connecting to the multicast address 239.192.1.1, port 5555, +// 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); -/* Connecting to the multicast address 239.192.1.1, port 5555, */ -/* using the network interface with the address 192.168.1.1 */ -/* and the standard PGM protocol */ +// Connecting to the multicast address 239.192.1.1, port 5555, +// using the network interface with the address 192.168.1.1 +// and the standard PGM protocol rc = zmq_connect(socket, "pgm://192.168.1.1;239.192.1.1:5555"); assert (rc == 0); ---- @@ -158,5 +158,5 @@ linkzmq:zmq[7] AUTHORS ------- -This 0MQ manual page was written by Martin Sustrik and -Martin Lucina . +This 0MQ manual page was written by Pieter Hintjens , +Martin Sustrik and Martin Lucina . diff --git a/doc/zmq_socket.txt b/doc/zmq_socket.txt index 18edf8ee..ef2ac0fc 100644 --- a/doc/zmq_socket.txt +++ b/doc/zmq_socket.txt @@ -58,8 +58,8 @@ general _messaging pattern_ which is built from related socket types. Request-reply pattern ~~~~~~~~~~~~~~~~~~~~~ -The request-reply pattern is used for sending requests from a _client_ to one -or more instances of a _service_, and receiving subsequent replies to each +The request-reply pattern is used for sending requests from a ZMQ_REQ _client_ +to one or more ZMQ_REP _services_, and receiving subsequent replies to each request sent. @@ -71,10 +71,10 @@ sequence of _zmq_send(request)_ and subsequent _zmq_recv(reply)_ calls. Each request sent is round-robined among all _services_, and each reply received is matched with the last issued request. -When a 'ZMQ_REQ' socket enters an exceptional state due to having reached the +When a 'ZMQ_REQ' socket enters the 'mute' state due to having reached the high water mark for all _services_, or if there are no _services_ at all, then any linkzmq:zmq_send[3] operations on the socket shall block until the -exceptional state ends or at least one _service_ becomes available for sending; +'mute' state ends or at least one _service_ becomes available for sending; messages are not discarded. [horizontal] @@ -84,7 +84,7 @@ Direction:: Bidirectional Send/receive pattern:: Send, Receive, Send, Receive, ... Outgoing routing strategy:: Round-robin Incoming routing strategy:: Last peer -ZMQ_HWM option action:: Block +Action in mute state:: Block ZMQ_REP @@ -96,9 +96,9 @@ request received is fair-queued from among all _clients_, and each reply sent is routed to the _client_ that issued the last request. If the original requester doesn't exist any more the reply is silently discarded. -When a 'ZMQ_REP' socket enters an exceptional state due to having reached the +When a 'ZMQ_REP' socket enters the 'mute' state due to having reached the high water mark for a _client_, then any replies sent to the _client_ in -question shall be dropped until the exceptional state ends. +question shall be dropped until the mute state ends. [horizontal] .Summary of ZMQ_REP characteristics @@ -107,7 +107,7 @@ Direction:: Bidirectional Send/receive pattern:: Receive, Send, Receive, Send, ... Incoming routing strategy:: Fair-queued Outgoing routing strategy:: Last peer -ZMQ_HWM option action:: Drop +Action in mute state:: Drop ZMQ_DEALER @@ -116,9 +116,9 @@ A socket of type 'ZMQ_DEALER' is an advanced pattern used for extending request/reply sockets. Each message sent is round-robined among all connected peers, and each message received is fair-queued from all connected peers. -When a 'ZMQ_DEALER' socket enters an exceptional state due to having reached the +When a 'ZMQ_DEALER' socket enters the 'mute' state due to having reached the high water mark for all peers, or if there are no peers at all, then any -linkzmq:zmq_send[3] operations on the socket shall block until the exceptional +linkzmq:zmq_send[3] operations on the socket shall block until the mute state ends or at least one peer becomes available for sending; messages are not discarded. @@ -135,7 +135,7 @@ Direction:: Bidirectional Send/receive pattern:: Unrestricted Outgoing routing strategy:: Round-robin Incoming routing strategy:: Fair-queued -ZMQ_HWM option action:: Block +Action in mute state:: Block ZMQ_ROUTER @@ -150,9 +150,9 @@ the peer the message shall be routed to. If the peer does not exist anymore the message shall be silently discarded by default, unless 'ZMQ_ROUTER_BEHAVIOR' socket option is set to '1'. -When a 'ZMQ_ROUTER' socket enters an exceptional state due to having reached the +When a 'ZMQ_ROUTER' socket enters the 'mute' state due to having reached the high water mark for all peers, then any messages sent to the socket shall be dropped -until the exceptional state ends. Likewise, any messages routed to a peer for which +until the mute state ends. Likewise, any messages routed to a peer for which the individual high water mark has been reached shall also be dropped. When a 'ZMQ_REQ' socket is connected to a 'ZMQ_ROUTER' socket, in addition to the @@ -171,7 +171,7 @@ Direction:: Bidirectional Send/receive pattern:: Unrestricted Outgoing routing strategy:: See text Incoming routing strategy:: Fair-queued -ZMQ_HWM option action:: Drop +Action in mute state:: Drop Publish-subscribe pattern @@ -186,9 +186,9 @@ A socket of type 'ZMQ_PUB' is used by a _publisher_ to distribute data. 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 +When a 'ZMQ_PUB' socket enters the 'mute' state due to having reached the high water mark for a _subscriber_, then any messages that would be sent to the -_subscriber_ in question shall instead be dropped until the exceptional state +_subscriber_ in question shall instead be dropped until the mute state ends. The _zmq_send()_ function shall never block for this socket type. [horizontal] @@ -198,7 +198,7 @@ Direction:: Unidirectional Send/receive pattern:: Send only Incoming routing strategy:: N/A Outgoing routing strategy:: Fan out -ZMQ_HWM option action:: Drop +Action in mute state:: Drop ZMQ_SUB @@ -216,7 +216,7 @@ Direction:: Unidirectional Send/receive pattern:: Receive only Incoming routing strategy:: Fair-queued Outgoing routing strategy:: N/A -ZMQ_HWM option action:: Drop +Action in mute state:: Drop ZMQ_XPUB @@ -233,7 +233,7 @@ Direction:: Unidirectional Send/receive pattern:: Send messages, receive subscriptions Incoming routing strategy:: N/A Outgoing routing strategy:: Fan out -ZMQ_HWM option action:: Drop +Action in mute state:: Drop ZMQ_XSUB @@ -249,7 +249,7 @@ Direction:: Unidirectional Send/receive pattern:: Receive messages, send subscriptions Incoming routing strategy:: Fair-queued Outgoing routing strategy:: N/A -ZMQ_HWM option action:: Drop +Action in mute state:: Drop Pipeline pattern @@ -267,10 +267,10 @@ to downstream pipeline _nodes_. Messages are round-robined to all connected downstream _nodes_. The _zmq_recv()_ function is not implemented for this socket type. -When a 'ZMQ_PUSH' socket enters an exceptional state due to having reached the +When a 'ZMQ_PUSH' socket enters the 'mute' state due to having reached the high water mark for all downstream _nodes_, or if there are no downstream _nodes_ at all, then any linkzmq:zmq_send[3] operations on the socket shall -block until the exceptional state ends or at least one downstream _node_ +block until the mute state ends or at least one downstream _node_ becomes available for sending; messages are not discarded. [horizontal] @@ -280,7 +280,7 @@ Direction:: Unidirectional Send/receive pattern:: Send only Incoming routing strategy:: N/A Outgoing routing strategy:: Round-robin -ZMQ_HWM option action:: Block +Action in mute state:: Block ZMQ_PULL @@ -297,7 +297,7 @@ Direction:: Unidirectional Send/receive pattern:: Receive only Incoming routing strategy:: Fair-queued Outgoing routing strategy:: N/A -ZMQ_HWM option action:: Block +Action in mute state:: Block Exclusive pair pattern @@ -313,7 +313,7 @@ A socket of type 'ZMQ_PAIR' can only be connected to a single peer at any one time. No message routing or filtering is performed on messages sent over a 'ZMQ_PAIR' socket. -When a 'ZMQ_PAIR' socket enters an exceptional state due to having reached the +When a 'ZMQ_PAIR' socket enters the 'mute' state due to having reached the high water mark for the connected peer, or if no peer is connected, then any linkzmq:zmq_send[3] operations on the socket shall block until the peer becomes available for sending; messages are not discarded. @@ -330,7 +330,7 @@ Direction:: Bidirectional Send/receive pattern:: Unrestricted Incoming routing strategy:: N/A Outgoing routing strategy:: N/A -ZMQ_HWM option action:: Block +Action in mute state:: Block RETURN VALUE diff --git a/doc/zmq_tcp.txt b/doc/zmq_tcp.txt index 5f75052a..a87aaa0c 100644 --- a/doc/zmq_tcp.txt +++ b/doc/zmq_tcp.txt @@ -16,10 +16,12 @@ your first choice. ADDRESSING ---------- -A 0MQ address string consists of two parts as follows: -'transport'`://`'endpoint'. The 'transport' part specifies the underlying -transport protocol to use, and for the TCP transport shall be set to `tcp`. -The meaning of the 'endpoint' part for the TCP transport is defined below. +A 0MQ endpoint is a string consisting of a 'transport'`://` followed by an +'address'. The 'transport' specifies the underlying protocol to use. The +'address' specifies the transport-specific address to connect to. + +For the TCP transport, the transport is `tcp`, and the meaning of the +'address' part is defined below. Assigning a local address to a socket @@ -33,12 +35,17 @@ An 'interface' may be specified by either of the following: * The wild-card `*`, meaning all available interfaces. * The primary IPv4 or IPv6 address assigned to the interface, in its numeric representation. -* The interface name as defined by the operating system. +* The non-portable interface name as defined by the operating system. + +The TCP port number may be specified by: + +* A numeric value, usually above 1024 on POSIX systems. +* The wild-card `*`, meaning a system-assigned ephemeral port. + +When using ephemeral ports, the caller should retrieve the actual assigned +port using the ZMQ_LAST_ENDPOINT socket option. See linkzmq:zmq_getsockopt[3] +for details. -NOTE: Interface names are not standardised in any way and should be assumed to -be arbitrary and platform dependent. On Win32 platforms no short interface -names exist, thus only the primary IP address may be used to specify an -'interface'. Connecting a socket ~~~~~~~~~~~~~~~~~~~ @@ -49,98 +56,30 @@ a colon and the TCP port number to use. A 'peer address' may be specified by either of the following: * The DNS name of the peer. -* The IPv4 or IPv6 address of the peer, in it's numeric representation. - - -WIRE FORMAT ------------ -0MQ messages are transmitted over TCP in frames consisting of an encoded -'payload length', followed by a 'flags' field and the message body. The 'payload -length' is defined as the combined length in octets of the message body and the -'flags' field. - -For frames with a 'payload length' not exceeding 254 octets, the 'payload -length' shall be encoded as a single octet. The minimum valid 'payload length' -of a frame is 1 octet, thus a 'payload length' of 0 octets is invalid and such -frames SHOULD be ignored. - -For frames with a 'payload length' exceeding 254 octets, the 'payload length' -shall be encoded as a single octet with the value `255` followed by the -'payload length' represented as a 64-bit unsigned integer in network byte -order. - -The 'flags' field consists of a single octet containing various control flags: - -Bit 0 (MORE): _More message parts to follow_. A value of 0 indicates that there -are no more message parts to follow; or that the message being sent is not a -multi-part message. A value of 1 indicates that the message being sent is a -multi-part message and more message parts are to follow. - -Bits 1-7: _Reserved_. Bits 1-7 are reserved for future expansion and MUST be -set to zero. - -The following ABNF grammar represents a single 'frame': - -.... - frame = (length flags data) - length = OCTET / (escape 8OCTET) - flags = OCTET - escape = %xFF - data = *OCTET -.... - -The following diagram illustrates the layout of a frame with a 'payload length' -not exceeding 254 octets: - -.... -0 1 2 3 -0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Payload length| Flags | Message body ... | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Message body ... -+-+-+-+-+-+-+- ... -.... - -The following diagram illustrates the layout of a frame with a 'payload length' -exceeding 254 octets: - -.... -0 1 2 3 -0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| 0xff | Payload length ... | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Payload length ... | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Payload length| Flags | Message body ... | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Message body ... -+-+-+-+-+-+-+-+ ... -.... +* The IPv4 or IPv6 address of the peer, in its numeric representation. EXAMPLES -------- .Assigning a local address to a socket ---- -/* TCP port 5555 on all available interfaces */ -rc = zmq_bind(socket, "tcp://*:5555"); +// TCP port 5555 on all available interfaces +rc = zmq_bind(socket, "tcp:/// :5555"); assert (rc == 0); -/* TCP port 5555 on the local loop-back 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); ---- .Connecting a socket ---- -/* Connecting using an IP address */ +// Connecting using an IP address rc = zmq_connect(socket, "tcp://192.168.1.1:5555"); assert (rc == 0); -/* Connecting using a DNS name */ +// Connecting using a DNS name rc = zmq_connect(socket, "tcp://server1:5555"); assert (rc == 0); ---- @@ -158,5 +97,5 @@ linkzmq:zmq[7] AUTHORS ------- -This 0MQ manual page was written by Martin Sustrik and -Martin Lucina . +This 0MQ manual page was written by Pieter Hintjens , +Martin Sustrik and Martin Lucina .