From 5219e4ce8f9aa082c5f91e248a9f66639c69727d Mon Sep 17 00:00:00 2001 From: Martin Lucina Date: Fri, 28 May 2010 00:49:13 +0200 Subject: Clarify socket types in documentation, reinstate ZMQ_PAIR --- doc/zmq_socket.txt | 91 +++++++++++++++++++++++++++++++++--------------------- 1 file changed, 56 insertions(+), 35 deletions(-) (limited to 'doc/zmq_socket.txt') diff --git a/doc/zmq_socket.txt b/doc/zmq_socket.txt index e01921c..ebae5e1 100644 --- a/doc/zmq_socket.txt +++ b/doc/zmq_socket.txt @@ -19,7 +19,31 @@ 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: +The following sections present the socket types defined by 0MQ, grouped by the +general _messaging pattern_ built from related socket types. + + +Request-reply pattern +~~~~~~~~~~~~~~~~~~~~~ +The request-reply pattern is used for sending requests from a _client_ to a +_service_, and receiving subsequent replies to each request sent. + +Socket type:: 'ZMQ_REQ' +Compatible peer sockets:: 'ZMQ_REP' + +A socket of type 'ZMQ_REQ' is used by a _client_ to send requests to and +receive replies from a _service_. This socket type allows only an alternating +sequence of _zmq_send(request)_ and subsequent _zmq_recv(reply)_ calls. Each +request sent is load-balanced among all connected _services_. + +Socket type:: 'ZMQ_REP' +Compatible peer sockets:: 'ZMQ_REQ' + +A socket of type 'ZMQ_REP' is used by a _service_ to receive requests from and +send replies to a _client_. This socket type allows only an alternating +sequence of _zmq_recv(request)_ and subsequent _zmq_send(reply)_ calls. Each +reply is routed to the _client_ that issued the last received request. + Publish-subscribe pattern ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -43,49 +67,46 @@ which messages to subscribe to. The _zmq_send()_ function is not implemented for this socket type. -Request-reply pattern -~~~~~~~~~~~~~~~~~~~~~ -The request-reply pattern is used for sending requests from a _client_ to a -_service_, and receiving subsequent replies to each request sent. - -Socket type:: 'ZMQ_REQ' -Compatible peer sockets:: 'ZMQ_REP' +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. -A socket of type 'ZMQ_REQ' is used by a _client_ to send requests to and -receive replies from a _service_. This socket type allows only an alternating -sequence of _zmq_send(request)_ and subsequent _zmq_recv(reply)_ calls. Each -request sent is load-balanced among all connected _services_. +Socket type:: 'ZMQ_DOWNSTREAM' +Compatible peer sockets:: 'ZMQ_UPSTREAM' -Socket type:: 'ZMQ_REP' -Compatible peer sockets:: 'ZMQ_REQ' +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. -A socket of type 'ZMQ_REP' is used by a _service_ to receive requests from and -send replies to a _client_. This socket type allows only an alternating -sequence of _zmq_recv(request)_ and subsequent _zmq_send(reply)_ calls. Each -reply is routed to the _client_ that issued the last received request. +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. -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. -Socket type:: 'ZMQ_UPSTREAM' -Compatible peer sockets:: 'ZMQ_DOWNSTREAM' +Exclusive pair pattern +~~~~~~~~~~~~~~~~~~~~~~ +The exclusive pair pattern is used for communicating exclusively between two +peers. -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. +Socket type:: 'ZMQ_PAIR' +Compatible peer sockets:: 'ZMQ_PAIR' -Socket type:: 'ZMQ_DOWNSTREAM' -Compatible peer sockets:: 'ZMQ_UPSTREAM' +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. -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. +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 -- cgit v1.2.3