3party/libzmq
0
0
Fork 0
mirror of https://github.com/zeromq/libzmq.git synced 2024-12-26 23:01:04 +08:00
Code Issues Projects Releases Wiki Activity

Problem: client/server pattern is not documented

Browse Source 
Solution: add man pages/sections for:

 * ZMQ_SERVER
 * ZMQ_CLIENT
 * ZMQ_THREADSAFE
 * zmq_msg_routing_id
 * zmq_msg_set_routing_id
This commit is contained in:
Pieter Hintjens 2015-09-11 17:12:58 -04:00
parent 4db73fc18b
commit e7da0ea07b
5 changed files with 202 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
doc/Makefile.am
View File

@ -6,6 +6,7 @@ MAN3 = zmq_bind.3 zmq_unbind.3 zmq_connect.3 zmq_disconnect.3 zmq_close.3 \
zmq_msg_init.3 zmq_msg_init_data.3 zmq_msg_init_size.3 \
zmq_msg_move.3 zmq_msg_copy.3 zmq_msg_size.3 zmq_msg_data.3 zmq_msg_close.3 \
zmq_msg_send.3 zmq_msg_recv.3 \
zmq_msg_routing_id.3 zmq_msg_set_routing_id.3 \
zmq_send.3 zmq_recv.3 zmq_send_const.3 \
zmq_msg_get.3 zmq_msg_set.3 zmq_msg_more.3 zmq_msg_gets.3 \
zmq_getsockopt.3 zmq_setsockopt.3 \

11
doc/zmq_getsockopt.txt
View File

@ -688,6 +688,17 @@ Default value:: 0 (leave to OS default)
Applicable socket types:: all, when using TCP transports.
ZMQ_THREADSAFE: Retrieve socket thread safety
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_THREADSAFE' option shall retrieve a boolean value indicating whether
or not the socket is threadsafe. Currently only 'ZMQ_CLIENT' sockets are
threadsafe.
[horizontal]
Option value type:: boolean
Applicable socket types:: all
ZMQ_TOS: Retrieve the Type-of-Service socket override status
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Retrieve the IP_TOS option for the socket.

61
doc/zmq_msg_routing_id.txt Normal file
View File

@ -0,0 +1,61 @@
zmq_msg_routing_id(3)
=====================
NAME
----
zmq_msg_routing_id - return routing ID for message, if any
SYNOPSIS
--------
*uint32_t zmq_msg_routing_id (zmq_msg_t '*message');*
DESCRIPTION
-----------
The _zmq_msg_routing_id()_ function returns the routing ID for the message,
if any. The routing ID is set on all messages received from a 'ZMQ_SERVER'
socket. To send a message to a 'ZMQ_SERVER' socket you must set the routing
ID of a connected 'ZMQ_CLIENT' peer. Routing IDs are transient.
RETURN VALUE
------------
The _zmq_msg_routing_id()_ function shall return zero if there is no routing
ID, otherwise it shall return an unsigned 32-bit integer greater than zero.
EXAMPLE
-------
.Receiving a client message and routing ID
----
void *ctx = zmq_ctx_new ();
assert (ctx);
void *server = zmq_socket (ctx, ZMQ_SERVER);
assert (server);
int rc = zmq_bind (server, "tcp://127.0.0.1:8080");
assert (rc == 0);
zmq_msg_t message;
rc = zmq_msg_init (&message);
assert (rc == 0);
// Receive a message from socket
rc = zmq_msg_recv (server, &message, 0);
assert (rc != -1);
uint32_t routing_id = zmq_msg_routing_id (&message);
assert (routing_id);
----
SEE ALSO
--------
linkzmq:zmq_msg_set_routing_id[3]
AUTHORS
-------
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.

46
doc/zmq_msg_set_routing_id.txt Normal file
View File

@ -0,0 +1,46 @@
zmq_msg_set_routing_id(3)
=========================
NAME
----
zmq_msg_set_routing_id - set routing ID property on message
SYNOPSIS
--------
*int zmq_msg_set_routing_id (zmq_msg_t '*message', uint32_t 'routing_id');*
DESCRIPTION
-----------
The _zmq_msg_set_routing_id()_ function sets the 'routing_id' specified, on the
the message pointed to by the 'message' argument. The 'routing_id' must be
greater than zero. To get a valid routing ID, you must receive a message
from a 'ZMQ_SERVER' socket, and use the libzmq:zmq_msg_routing_id method.
Routing IDs are transient.
RETURN VALUE
------------
The _zmq_msg_set_routing_id()_ function shall return zero if successful. Otherwise it
shall return `-1` and set 'errno' to one of the values defined below.
ERRORS
------
*EINVAL*::
The provided 'routing_id' is zero.
SEE ALSO
--------
linkzmq:zmq_msg_routing_id[3]
linkzmq:zmq[7]
AUTHORS
-------
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.

94
doc/zmq_socket.txt
View File

@ -48,7 +48,7 @@ _zmq_bind()_, thus allowing many-to-many relationships.
.Thread safety
0MQ 'sockets' are _not_ thread safe. Applications MUST NOT use a socket
from multiple threads except after migrating a socket from one thread to
from multiple threads except after migrating a socket from one thread to
another with a "full fence" memory barrier.
.Socket types
@ -56,6 +56,78 @@ The following sections present the socket types defined by 0MQ, grouped by the
general _messaging pattern_ which is built from related socket types.
Client-server pattern
~~~~~~~~~~~~~~~~~~~~~
The client-server pattern is used to allow a single 'ZMQ_SERVER' _server_ talk
to one or more 'ZMQ_CLIENT' _clients_. The client always starts the conversation,
after which either peer can send messages asynchronously, to the other.
The client-server pattern is formally defined by http://rfc.zeromq.org/spec:41.
Note: this pattern deprecates the use of 'ZMQ_DEALER' and 'ZMQ_ROUTER' to build
client-server architectures.
ZMQ_CLIENT
^^^^^^^^^^
A 'ZMQ_CLIENT' socket talks to a 'ZMQ_SERVER' socket. Either peer can connect,
though the usual and recommended model is to bind the 'ZMQ_SERVER' and connect
the 'ZMQ_CLIENT'.
If the 'ZMQ_CLIENT' socket has established a connection, linkzmq:zmq_send[3]
will accept messages, queue them, and send them as rapidly as the network
allows. The outgoing buffer limit is defined by the high water mark for the
socket. If the outgoing buffer is full, or if there is no connected peer,
linkzmq:zmq_send[3] will block, by default. The 'ZMQ_CLIENT' socket will not
drop messages.
When a 'ZMQ_CLIENT' socket is connected to multiple 'ZMQ_SERVER' sockets,
outgoing messages are distributed between connected peers on a round-robin
basis. Likewise, the 'ZMQ_CLIENT' socket receives messages fairly from each
connected peer. This usage is sensible only for stateless protocols.
'ZMQ_CLIENT' sockets are threadsafe and can be used from multiple threads
at the same time. Note that replies from a 'ZMQ_SERVER' socket will go to
the first client thread that calls libzmq:zmq_msg_recv. If you need to get
replies back to the originating thread, use one 'ZMQ_CLIENT' socket per
thread.
[horizontal]
.Summary of ZMQ_CLIENT characteristics
Compatible peer sockets:: 'ZMQ_SERVER'
Direction:: Bidirectional
Send/receive pattern:: Unrestricted
Outgoing routing strategy:: Round-robin
Incoming routing strategy:: Fair-queued
Action in mute state:: Block
ZMQ_SERVER
^^^^^^^^^^
A 'ZMQ_SERVER' socket talks to a set of 'ZMQ_CLIENT' sockets. A 'ZMQ_SERVER'
socket can only reply to an incoming message: the 'ZMQ_CLIENT' peer must
always initiate a conversation.
Each received message has a 'routing_id' that is a 32-bit unsigned integer.
The application can fetch this with linkzmq:zmq_msg_routing_id[3]. To send
a message to a given 'ZMQ_CLIENT' peer the application must set the peer's
'routing_id' on the message, using linkzmq:zmq_msg_set_routing_id[3].
If the 'routing_id' is not specified, or does not refer to a connected client
peer, the send call will fail with EHOSTUNREACH. If the outgoing buffer for
the client peer is full, the send call will fail with EAGAIN. The 'ZMQ_SERVER'
socket shall not drop messages, nor shall it block.
[horizontal]
.Summary of ZMQ_SERVER characteristics
Compatible peer sockets:: 'ZMQ_CLIENT'
Direction:: Bidirectional
Send/receive pattern:: Unrestricted
Outgoing routing strategy:: See text
Incoming routing strategy:: Fair-queued
Action in mute state:: Return EAGAIN
Request-reply pattern
~~~~~~~~~~~~~~~~~~~~~
The request-reply pattern is used for sending requests from a ZMQ_REQ _client_
@ -72,7 +144,7 @@ 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.
If no services are available, then any send operation on the socket shall
If no services are available, then any send operation on the socket shall
block until at least one _service_ becomes available. The REQ socket shall
not discard messages.
@ -328,26 +400,26 @@ Action in mute state:: Block
Native Pattern
~~~~~~~~~~~~~~
The native pattern is used for communicating with TCP peers and allows
The native pattern is used for communicating with TCP peers and allows
asynchronous requests and replies in either direction.
ZMQ_STREAM
^^^^^^^^^^
A socket of type 'ZMQ_STREAM' is used to send and receive TCP data from a
non-0MQ peer, when using the tcp:// transport. A 'ZMQ_STREAM' socket can
A socket of type 'ZMQ_STREAM' is used to send and receive TCP data from a
non-0MQ peer, when using the tcp:// transport. A 'ZMQ_STREAM' socket can
act as client and/or server, sending and/or receiving TCP data asynchronously.
When receiving TCP data, a 'ZMQ_STREAM' socket shall prepend a message part
containing the _identity_ of the originating peer to the message before passing
it to the application. Messages received are fair-queued from among all
connected peers.
containing the _identity_ of the originating peer to the message before passing
it to the application. Messages received are fair-queued from among all
connected peers.
When sending TCP data, a 'ZMQ_STREAM' socket shall remove the first part of the
message and use it to determine the _identity_ of the peer the message shall be
When sending TCP data, a 'ZMQ_STREAM' socket shall remove the first part of the
message and use it to determine the _identity_ of the peer the message shall be
routed to, and unroutable messages shall cause an EHOSTUNREACH or EAGAIN error.
To open a connection to a server, use the zmq_connect call, and then fetch the
To open a connection to a server, use the zmq_connect call, and then fetch the
socket identity using the ZMQ_IDENTITY zmq_getsockopt call.
To close a specific connection, send the identity frame followed by a