diff --git a/doc/zmq_socket.txt b/doc/zmq_socket.txt index 4eb3c6ed..8c7fa8da 100644 --- a/doc/zmq_socket.txt +++ b/doc/zmq_socket.txt @@ -128,114 +128,6 @@ Incoming routing strategy:: Fair-queued Action in mute state:: Return EAGAIN -Request-reply pattern -~~~~~~~~~~~~~~~~~~~~~ -The request-reply pattern is used for sending requests from a ZMQ_REQ _client_ -to one or more ZMQ_REP _services_, and receiving subsequent replies to each -request sent. - -The request-reply pattern is formally defined by http://rfc.zeromq.org/spec:28. - -ZMQ_REQ -^^^^^^^ -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 round-robined among all _services_, and each reply received is -matched with the last issued request. - -If no services are available, then any send operation on the socket shall -block until at least one _service_ becomes available. The REQ socket shall -not discard messages. - -[horizontal] -.Summary of ZMQ_REQ characteristics -Compatible peer sockets:: 'ZMQ_REP', 'ZMQ_ROUTER' -Direction:: Bidirectional -Send/receive pattern:: Send, Receive, Send, Receive, ... -Outgoing routing strategy:: Round-robin -Incoming routing strategy:: Last peer -Action in mute state:: Block - - -ZMQ_REP -^^^^^^^ -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 -request received is fair-queued from among all _clients_, and each reply sent -is routed to the _client_ that issued the last request. If the original -requester does not exist any more the reply is silently discarded. - -[horizontal] -.Summary of ZMQ_REP characteristics -Compatible peer sockets:: 'ZMQ_REQ', 'ZMQ_DEALER' -Direction:: Bidirectional -Send/receive pattern:: Receive, Send, Receive, Send, ... -Incoming routing strategy:: Fair-queued -Outgoing routing strategy:: Last peer - - -ZMQ_DEALER -^^^^^^^^^^ -A socket of type 'ZMQ_DEALER' is an advanced pattern used for extending -request/reply sockets. Each message sent is round-robined among all connected -peers, and each message received is fair-queued from all connected peers. - -When a 'ZMQ_DEALER' socket enters the 'mute' 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 mute -state ends or at least one peer becomes available for sending; messages are not -discarded. - -When a 'ZMQ_DEALER' 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_DEALER characteristics -Compatible peer sockets:: 'ZMQ_ROUTER', 'ZMQ_REP', 'ZMQ_DEALER' -Direction:: Bidirectional -Send/receive pattern:: Unrestricted -Outgoing routing strategy:: Round-robin -Incoming routing strategy:: Fair-queued -Action in mute state:: Block - - -ZMQ_ROUTER -^^^^^^^^^^ -A socket of type 'ZMQ_ROUTER' is an advanced socket type used for extending -request/reply sockets. When receiving messages a 'ZMQ_ROUTER' 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_ROUTER' 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. If the peer does not exist anymore -the message shall be silently discarded by default, unless 'ZMQ_ROUTER_MANDATORY' -socket option is set to '1'. - -When a 'ZMQ_ROUTER' socket enters the 'mute' state due to having reached the -high water mark for all peers, then any messages sent to the socket shall be dropped -until the mute state ends. Likewise, any messages routed to 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_ROUTER' 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_ROUTER characteristics -Compatible peer sockets:: 'ZMQ_DEALER', 'ZMQ_REQ', 'ZMQ_ROUTER' -Direction:: Bidirectional -Send/receive pattern:: Unrestricted -Outgoing routing strategy:: See text -Incoming routing strategy:: Fair-queued -Action in mute state:: Drop - - Publish-subscribe pattern ~~~~~~~~~~~~~~~~~~~~~~~~~ The publish-subscribe pattern is used for one-to-many distribution of data from @@ -445,6 +337,116 @@ Incoming routing strategy:: Fair-queued Action in mute state:: EAGAIN +Request-reply pattern +~~~~~~~~~~~~~~~~~~~~~ +The request-reply pattern is used for sending requests from a ZMQ_REQ _client_ +to one or more ZMQ_REP _services_, and receiving subsequent replies to each +request sent. + +The request-reply pattern is formally defined by http://rfc.zeromq.org/spec:28. + +Note: this pattern will be deprecated in favor of the client-server pattern. + +ZMQ_REQ +^^^^^^^ +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 round-robined among all _services_, and each reply received is +matched with the last issued request. + +If no services are available, then any send operation on the socket shall +block until at least one _service_ becomes available. The REQ socket shall +not discard messages. + +[horizontal] +.Summary of ZMQ_REQ characteristics +Compatible peer sockets:: 'ZMQ_REP', 'ZMQ_ROUTER' +Direction:: Bidirectional +Send/receive pattern:: Send, Receive, Send, Receive, ... +Outgoing routing strategy:: Round-robin +Incoming routing strategy:: Last peer +Action in mute state:: Block + + +ZMQ_REP +^^^^^^^ +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 +request received is fair-queued from among all _clients_, and each reply sent +is routed to the _client_ that issued the last request. If the original +requester does not exist any more the reply is silently discarded. + +[horizontal] +.Summary of ZMQ_REP characteristics +Compatible peer sockets:: 'ZMQ_REQ', 'ZMQ_DEALER' +Direction:: Bidirectional +Send/receive pattern:: Receive, Send, Receive, Send, ... +Incoming routing strategy:: Fair-queued +Outgoing routing strategy:: Last peer + + +ZMQ_DEALER +^^^^^^^^^^ +A socket of type 'ZMQ_DEALER' is an advanced pattern used for extending +request/reply sockets. Each message sent is round-robined among all connected +peers, and each message received is fair-queued from all connected peers. + +When a 'ZMQ_DEALER' socket enters the 'mute' 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 mute +state ends or at least one peer becomes available for sending; messages are not +discarded. + +When a 'ZMQ_DEALER' 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_DEALER characteristics +Compatible peer sockets:: 'ZMQ_ROUTER', 'ZMQ_REP', 'ZMQ_DEALER' +Direction:: Bidirectional +Send/receive pattern:: Unrestricted +Outgoing routing strategy:: Round-robin +Incoming routing strategy:: Fair-queued +Action in mute state:: Block + + +ZMQ_ROUTER +^^^^^^^^^^ +A socket of type 'ZMQ_ROUTER' is an advanced socket type used for extending +request/reply sockets. When receiving messages a 'ZMQ_ROUTER' 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_ROUTER' 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. If the peer does not exist anymore +the message shall be silently discarded by default, unless 'ZMQ_ROUTER_MANDATORY' +socket option is set to '1'. + +When a 'ZMQ_ROUTER' socket enters the 'mute' state due to having reached the +high water mark for all peers, then any messages sent to the socket shall be dropped +until the mute state ends. Likewise, any messages routed to 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_ROUTER' 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_ROUTER characteristics +Compatible peer sockets:: 'ZMQ_DEALER', 'ZMQ_REQ', 'ZMQ_ROUTER' +Direction:: Bidirectional +Send/receive pattern:: Unrestricted +Outgoing routing strategy:: See text +Incoming routing strategy:: Fair-queued +Action in mute state:: Drop + + RETURN VALUE ------------ The _zmq_socket()_ function shall return an opaque handle to the newly created