mirror of
https://github.com/zeromq/libzmq.git
synced 2024-12-13 10:52:56 +01:00
Cleanups to man pages
This commit is contained in:
Pieter Hintjens
parent
0b13872ff4
commit
171897f4e8
@ -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 <sustrik@250bpm.com> and
|
||||
Martin Lucina <mato@kotelna.sk>.
|
||||
This 0MQ manual page was written by Pieter Hintjens <ph@imatix.com>,
|
||||
Martin Sustrik <sustrik@250bpm.com> and Martin Lucina <mato@kotelna.sk>.
|
||||
|
||||
@ -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 <sustrik@250bpm.com> and
|
||||
Martin Lucina <mato@kotelna.sk>.
|
||||
This 0MQ manual page was written by Pieter Hintjens <ph@imatix.com>,
|
||||
Martin Sustrik <sustrik@250bpm.com> and Martin Lucina <mato@kotelna.sk>.
|
||||
|
||||
@ -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 <sustrik@250bpm.com> and
|
||||
Martin Lucina <mato@kotelna.sk>.
|
||||
This 0MQ manual page was written by Pieter Hintjens <ph@imatix.com>,
|
||||
Martin Sustrik <sustrik@250bpm.com> and Martin Lucina <mato@kotelna.sk>.
|
||||
|
||||
@ -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 <sustrik@250bpm.com> and
|
||||
Martin Lucina <mato@kotelna.sk>.
|
||||
This 0MQ manual page was written by Pieter Hintjens <ph@imatix.com>,
|
||||
Martin Sustrik <sustrik@250bpm.com> and Martin Lucina <mato@kotelna.sk>.
|
||||
|
||||
@ -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 <sustrik@250bpm.com> and
|
||||
Martin Lucina <mato@kotelna.sk>.
|
||||
This 0MQ manual page was written by Pieter Hintjens <ph@imatix.com>,
|
||||
Martin Sustrik <sustrik@250bpm.com> and Martin Lucina <mato@kotelna.sk>.
|
||||
|
||||
@ -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
|
||||
|
||||
111
doc/zmq_tcp.txt
111
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 <sustrik@250bpm.com> and
|
||||
Martin Lucina <mato@kotelna.sk>.
|
||||
This 0MQ manual page was written by Pieter Hintjens <ph@imatix.com>,
|
||||
Martin Sustrik <sustrik@250bpm.com> and Martin Lucina <mato@kotelna.sk>.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user