generic-library/libzmq
1
0
Fork 0
mirror of https://github.com/zeromq/libzmq.git synced 2024-12-12 10:33:52 +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
(SOCK_DGRAM). In comparison, 0MQ sockets present an abstraction of a
asynchronous _message queue_, with the exact queueing semantics depending on
the socket type (_messaging pattern_) in use. See linkzmq:zmq_socket[3] for the
_messaging patterns_ provided.
the socket type in use. See linkzmq:zmq_socket[3] for the socket types
provided.
0MQ sockets being _asynchronous_ means that the timings of the physical
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
'socket'.
sockets. Affinity determines which threads from the 0MQ I/O thread pool
associated with the socket's _context_ shall handle newly created connections.
A value of zero specifies no affinity, meaning that work shall be distributed
fairly among all 0MQ I/O threads in the thread pool. For non-zero values, the
lowest bit corresponds to thread 1, second lowest bit to thread 2 and so on.
For example, a value of 3 specifies that subsequent connections on 'socket'
shall be handled exclusively by I/O threads 1 and 2.
Affinity determines which threads from the 0MQ I/O thread pool associated with
the socket's _context_ shall handle newly created connections. A value of zero
specifies no affinity, meaning that work shall be distributed fairly among all
0MQ I/O threads in the thread pool. For non-zero values, the lowest bit
corresponds to thread 1, second lowest bit to thread 2 and so on. For example,
a value of 3 specifies that subsequent connections on 'socket' shall be handled
exclusively by I/O threads 1 and 2.
See also linkzmq:zmq_init[3] for details on allocating the number of I/O
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
communication over the socket.
The following _messaging patterns_ are defined:
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.
The following sections present the socket types defined by 0MQ, grouped by the
general _messaging pattern_ built from related socket types.
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.
Parallelized pipeline pattern
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The parallelized pipeline pattern is used for distributing work between
_components_ of a pipeline. Work travels down the pipeline and at each stage
can be processed by any number of _components_ in parallel.
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_UPSTREAM'
Compatible peer sockets:: 'ZMQ_DOWNSTREAM'
Socket type:: 'ZMQ_PUB'
Compatible peer sockets:: 'ZMQ_SUB'
A socket of type 'ZMQ_UPSTREAM' is used by a _component_ of a pipeline to
receive messages from upstream stages of the pipeline. Messages are fair-queued
from among all connected upstream _components_. The _zmq_send()_ function is
not implemented for this socket type.
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.
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'
Compatible peer sockets:: 'ZMQ_UPSTREAM'
A socket of type 'ZMQ_DOWNSTREAM' is used by a _component_ of a pipeline to
send messages to downstream stages of the pipeline. Messages are load-balanced
to all connected downstream _components_. The _zmq_recv()_ function is not
implemented for this socket type.
A socket of type 'ZMQ_DOWNSTREAM' is used by a pipeline _node_ to send messages
to downstream pipeline _nodes_. Messages are load-balanced to all connected
downstream _nodes_. The _zmq_recv()_ function is not implemented for this
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