generic-library/libzmq
1
0
Fork 0
mirror of https://github.com/zeromq/libzmq.git synced 2025-01-19 00:46:05 +01:00
Code Issues Projects Releases Wiki Activity

Clarify socket types in documentation, reinstate ZMQ_PAIR

Browse Source
This commit is contained in:
Martin Lucina 2010-05-28 00:49:13 +02:00
parent 8408ae066d
commit 5219e4ce8f
3 changed files with 67 additions and 46 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
doc/zmq.txt
View File

@ -90,8 +90,8 @@ Standard sockets present a _synchronous_ interface to either connection-mode
reliable byte streams (SOCK_STREAM), or connection-less unreliable datagrams reliable byte streams (SOCK_STREAM), or connection-less unreliable datagrams
(SOCK_DGRAM). In comparison, 0MQ sockets present an abstraction of a (SOCK_DGRAM). In comparison, 0MQ sockets present an abstraction of a
asynchronous _message queue_, with the exact queueing semantics depending on asynchronous _message queue_, with the exact queueing semantics depending on
the socket type (_messaging pattern_) in use. See linkzmq:zmq_socket[3] for the the socket type in use. See linkzmq:zmq_socket[3] for the socket types
_messaging patterns_ provided. provided.
0MQ sockets being _asynchronous_ means that the timings of the physical 0MQ sockets being _asynchronous_ means that the timings of the physical
connection setup and teardown, reconnect and effective delivery are organized connection setup and teardown, reconnect and effective delivery are organized

14
doc/zmq_setsockopt.txt
View File

@ -61,13 +61,13 @@ The 'ZMQ_AFFINITY' option shall set the I/O thread affinity for connections
created by subsequent _zmq_connect()_ or _zmq_bind()_ calls on the specified created by subsequent _zmq_connect()_ or _zmq_bind()_ calls on the specified
'socket'. 'socket'.
sockets. Affinity determines which threads from the 0MQ I/O thread pool Affinity determines which threads from the 0MQ I/O thread pool associated with
associated with the socket's _context_ shall handle newly created connections. the socket's _context_ shall handle newly created connections. A value of zero
A value of zero specifies no affinity, meaning that work shall be distributed specifies no affinity, meaning that work shall be distributed fairly among all
fairly among all 0MQ I/O threads in the thread pool. For non-zero values, the 0MQ I/O threads in the thread pool. For non-zero values, the lowest bit
lowest bit corresponds to thread 1, second lowest bit to thread 2 and so on. corresponds to thread 1, second lowest bit to thread 2 and so on. For example,
For example, a value of 3 specifies that subsequent connections on 'socket' a value of 3 specifies that subsequent connections on 'socket' shall be handled
shall be handled exclusively by I/O threads 1 and 2. exclusively by I/O threads 1 and 2.
See also linkzmq:zmq_init[3] for details on allocating the number of I/O See also linkzmq:zmq_init[3] for details on allocating the number of I/O
threads for a specific _context_. threads for a specific _context_.

95
doc/zmq_socket.txt
View File

@ -19,28 +19,8 @@ The 'zmq_socket()' function shall create a 0MQ socket within the specified
argument specifies the socket type, which determines the semantics of argument specifies the socket type, which determines the semantics of
communication over the socket. communication over the socket.
The following _messaging patterns_ are defined: The following sections present the socket types defined by 0MQ, grouped by the
general _messaging pattern_ built from related socket types.
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.
Socket type:: 'ZMQ_PUB'
Compatible peer sockets:: 'ZMQ_SUB'
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.
The _zmq_recv()_ function is not implemented for this socket type.
Socket type:: 'ZMQ_SUB'
Compatible peer sockets:: 'ZMQ_PUB'
A socket of type 'ZMQ_SUB' is used by a _subscriber_ to subscribe to data
distributed by a _publisher_. Initially a 'ZMQ_SUB' socket is not subscribed to
any messages, use the 'ZMQ_SUBSCRIBE' option of _zmq_setsockopt()_ to specify
which messages to subscribe to. The _zmq_send()_ function is not implemented
for this socket type.
Request-reply pattern Request-reply pattern
@ -65,27 +45,68 @@ sequence of _zmq_recv(request)_ and subsequent _zmq_send(reply)_ calls. Each
reply is routed to the _client_ that issued the last received request. reply is routed to the _client_ that issued the last received request.
Parallelized pipeline pattern Publish-subscribe pattern
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~
The parallelized pipeline pattern is used for distributing work between The publish-subscribe pattern is used for one-to-many distribution of data from
_components_ of a pipeline. Work travels down the pipeline and at each stage a single _publisher_ to multiple _subscribers_ in a fanout fashion.
can be processed by any number of _components_ in parallel.
Socket type:: 'ZMQ_UPSTREAM' Socket type:: 'ZMQ_PUB'
Compatible peer sockets:: 'ZMQ_DOWNSTREAM' Compatible peer sockets:: 'ZMQ_SUB'
A socket of type 'ZMQ_UPSTREAM' is used by a _component_ of a pipeline to A socket of type 'ZMQ_PUB' is used by a _publisher_ to distribute data.
receive messages from upstream stages of the pipeline. Messages are fair-queued Messages sent are distributed in a fanout fashion to all connected peers.
from among all connected upstream _components_. The _zmq_send()_ function is The _zmq_recv()_ function is not implemented for this socket type.
not implemented for this socket type.
Socket type:: 'ZMQ_SUB'
Compatible peer sockets:: 'ZMQ_PUB'
A socket of type 'ZMQ_SUB' is used by a _subscriber_ to subscribe to data
distributed by a _publisher_. Initially a 'ZMQ_SUB' socket is not subscribed to
any messages, use the 'ZMQ_SUBSCRIBE' option of _zmq_setsockopt()_ to specify
which messages to subscribe to. The _zmq_send()_ function is not implemented
for this socket type.
Pipeline pattern
~~~~~~~~~~~~~~~~
The pipeline pattern is used for distributing data to _nodes_ arranged in
a pipeline. Data always flows *down* the pipeline, and each stage of the
pipeline is connected to at least one _node_. When a pipeline stage is
connected to multiple _nodes_ data is processed by all connected _nodes_ in
parallel.
Socket type:: 'ZMQ_DOWNSTREAM' Socket type:: 'ZMQ_DOWNSTREAM'
Compatible peer sockets:: 'ZMQ_UPSTREAM' Compatible peer sockets:: 'ZMQ_UPSTREAM'
A socket of type 'ZMQ_DOWNSTREAM' is used by a _component_ of a pipeline to A socket of type 'ZMQ_DOWNSTREAM' is used by a pipeline _node_ to send messages
send messages to downstream stages of the pipeline. Messages are load-balanced to downstream pipeline _nodes_. Messages are load-balanced to all connected
to all connected downstream _components_. The _zmq_recv()_ function is not downstream _nodes_. The _zmq_recv()_ function is not implemented for this
implemented for this socket type. socket type.
Socket type:: 'ZMQ_UPSTREAM'
Compatible peer sockets:: 'ZMQ_DOWNSTREAM'
A socket of type 'ZMQ_UPSTREAM' is used by a pipeline _node_ to receive
messages from upstream pipeline _nodes_. Messages are fair-queued from among
all connected upstream _nodes_. The _zmq_send()_ function is not implemented
for this socket type.
Exclusive pair pattern
~~~~~~~~~~~~~~~~~~~~~~
The exclusive pair pattern is used for communicating exclusively between two
peers.
Socket type:: 'ZMQ_PAIR'
Compatible peer sockets:: 'ZMQ_PAIR'
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.
NOTE: 'ZMQ_PAIR' sockets are experimental, and are currently missing several
features such as auto-reconnection. Developers should consider other patterns
in preference to the exclusive pair pattern.
RETURN VALUE RETURN VALUE