diff options
Diffstat (limited to 'doc/zmq_socket.txt')
| -rw-r--r-- | doc/zmq_socket.txt | 102 |
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 |