summaryrefslogtreecommitdiff
path: root/doc/zmq_socket.txt
diff options
context:
space:
mode:
authorMartin Lucina <martin@lucina.net>2012-01-23 08:53:25 +0100
committerMartin Lucina <martin@lucina.net>2012-01-23 08:53:25 +0100
commit5ba1cb20fe6f6699cef1cc726718e760cd4c9af1 (patch)
treedf7b144c5325fd8b3c88c49b456fafc24249abe6 /doc/zmq_socket.txt
parenta15854bd92db69fcd0b4444fe1b8fe3610a7acf6 (diff)
Imported Upstream version 2.0.9.dfsgupstream/2.0.9.dfsg
Diffstat (limited to 'doc/zmq_socket.txt')
-rw-r--r--doc/zmq_socket.txt102
1 files changed, 83 insertions, 19 deletions
diff --git a/doc/zmq_socket.txt b/doc/zmq_socket.txt
index 23cc317..2156af2 100644
--- a/doc/zmq_socket.txt
+++ b/doc/zmq_socket.txt
@@ -104,6 +104,65 @@ Outgoing routing stratagy:: Last peer
ZMQ_HWM option action:: Drop
+ZMQ_XREQ
+^^^^^^^^
+A socket of type 'ZMQ_XREQ' is an advanced pattern used for extending
+request/reply sockets. Each message sent is load-balanced among all connected
+peers, and each message received is fair-queued from all connected peers.
+
+When a 'ZMQ_XREQ' socket enters an exceptional 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
+state ends or at least one peer becomes available for sending; messages are not
+discarded.
+
+When a 'ZMQ_XREQ' socket is connected to a 'ZMQ_REP' socket each message sent
+must consist of an empty message part, the _delimiter_, followed by one or more
+_body parts_.
+
+[horizontal]
+.Summary of ZMQ_XREQ characteristics
+Compatible peer sockets:: 'ZMQ_XREP', 'ZMQ_REP'
+Direction:: Bidirectional
+Send/receive pattern:: Unrestricted
+Outgoing routing strategy:: Load-balanced
+Incoming routing strategy:: Fair-queued
+ZMQ_HWM option action:: Block
+
+
+ZMQ_XREP
+^^^^^^^^
+A socket of type 'ZMQ_XREP' is an advanced pattern used for extending
+request/reply sockets. When receiving messages a 'ZMQ_XREP' 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. When sending messages a 'ZMQ_XREP' 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.
+
+When a 'ZMQ_XREP' socket enters an exceptional state due to having reached the
+high water mark for all peers, or if there are no peers at all, then any
+messages sent to the socket shall be dropped until the exceptional state ends.
+Likewise, any messages routed to a non-existent peer or 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_XREP' socket, in addition to the
+_identity_ of the originating peer each message received shall contain an empty
+_delimiter_ message part. Hence, the entire structure of each received message
+as seen by the application becomes: one or more _identity_ parts, _delimiter_
+part, one or more _body parts_. When sending replies to a 'ZMQ_REQ' socket the
+application must include the _delimiter_ part.
+
+[horizontal]
+.Summary of ZMQ_XREP characteristics
+Compatible peer sockets:: 'ZMQ_XREQ', 'ZMQ_REQ'
+Direction:: Bidirectional
+Send/receive pattern:: Unrestricted
+Outgoing routing strategy:: See text
+Incoming routing strategy:: Fair-queued
+ZMQ_HWM option action:: Drop
+
+
Publish-subscribe pattern
~~~~~~~~~~~~~~~~~~~~~~~~~
The publish-subscribe pattern is used for one-to-many distribution of data from
@@ -157,22 +216,24 @@ is connected to at least one _node_. When a pipeline stage is connected to
multiple _nodes_ data is load-balanced among all connected _nodes_.
-ZMQ_DOWNSTREAM
-^^^^^^^^^^^^^^
-A socket of type 'ZMQ_DOWNSTREAM' is used by a pipeline _node_ to send messages
+ZMQ_PUSH
+^^^^^^^^
+A socket of type 'ZMQ_PUSH' 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.
-When a 'ZMQ_DOWNSTREAM' socket enters an exceptional 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_ becomes available for sending; messages are not discarded.
+When a 'ZMQ_PUSH' socket enters an exceptional 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_
+becomes available for sending; messages are not discarded.
+
+Deprecated alias: 'ZMQ_DOWNSTREAM'.
[horizontal]
-.Summary of ZMQ_DOWNSTREAM characteristics
-Compatible peer sockets:: 'ZMQ_UPSTREAM'
+.Summary of ZMQ_PUSH characteristics
+Compatible peer sockets:: 'ZMQ_PULL'
Direction:: Unidirectional
Send/receive pattern:: Send only
Incoming routing strategy:: N/A
@@ -180,16 +241,18 @@ Outgoing routing strategy:: Load-balanced
ZMQ_HWM option action:: Block
-ZMQ_UPSTREAM
-^^^^^^^^^^^^
-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.
+ZMQ_PULL
+^^^^^^^^
+A socket of type 'ZMQ_PULL' 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.
+
+Deprecated alias: 'ZMQ_UPSTREAM'.
[horizontal]
-.Summary of ZMQ_UPSTREAM characteristics
-Compatible peer sockets:: 'ZMQ_DOWNSTREAM'
+.Summary of ZMQ_PULL characteristics
+Compatible peer sockets:: 'ZMQ_PUSH'
Direction:: Unidirectional
Send/receive pattern:: Receive only
Incoming routing strategy:: Fair-queued
@@ -238,9 +301,10 @@ ERRORS
------
*EINVAL*::
The requested socket 'type' is invalid.
-
*EMTHREAD*::
The maximum number of sockets within this 'context' has been exceeded.
+*EFAULT*::
+The provided 'context' was not valid (NULL).
SEE ALSO