From 4a7aad06d95701cf232198093ce396dcdbb53e5b Mon Sep 17 00:00:00 2001 From: Martin Sustrik Date: Thu, 16 Feb 2012 10:01:47 +0900 Subject: ZeroMQ renamed to Crossroads Signed-off-by: Martin Sustrik --- doc/zmq_socket.txt | 347 ----------------------------------------------------- 1 file changed, 347 deletions(-) delete mode 100644 doc/zmq_socket.txt (limited to 'doc/zmq_socket.txt') diff --git a/doc/zmq_socket.txt b/doc/zmq_socket.txt deleted file mode 100644 index 39ddebf..0000000 --- a/doc/zmq_socket.txt +++ /dev/null @@ -1,347 +0,0 @@ -zmq_socket(3) -============= - - -NAME ----- -zmq_socket - create 0MQ socket - - -SYNOPSIS --------- -*void *zmq_socket (void '*context', int 'type');* - - -DESCRIPTION ------------ -The 'zmq_socket()' function shall create a 0MQ socket within the specified -'context' and return an opaque handle to the newly created socket. The 'type' -argument specifies the socket type, which determines the semantics of -communication over the socket. - -The newly created socket is initially unbound, and not associated with any -endpoints. In order to establish a message flow a socket must first be -connected to at least one endpoint with linkzmq:zmq_connect[3], or at least one -endpoint must be created for accepting incoming connections with -linkzmq:zmq_bind[3]. - -.Key differences to conventional sockets -Generally speaking, conventional sockets present a _synchronous_ interface to -either connection-oriented reliable byte streams (SOCK_STREAM), or -connection-less unreliable datagrams (SOCK_DGRAM). In comparison, 0MQ sockets -present an abstraction of an asynchronous _message queue_, with the exact -queueing semantics depending on the socket type in use. Where conventional -sockets transfer streams of bytes or discrete datagrams, 0MQ sockets transfer -discrete _messages_. - -0MQ sockets being _asynchronous_ means that the timings of the physical -connection setup and tear down, reconnect and effective delivery are transparent -to the user and organized by 0MQ itself. Further, messages may be _queued_ in -the event that a peer is unavailable to receive them. - -Conventional sockets allow only strict one-to-one (two peers), many-to-one -(many clients, one server), or in some cases one-to-many (multicast) -relationships. With the exception of 'ZMQ_PAIR', 0MQ sockets may be connected -*to multiple endpoints* using _zmq_connect()_, while simultaneously accepting -incoming connections *from multiple endpoints* bound to the socket using -_zmq_bind()_, thus allowing many-to-many relationships. - -.Thread safety -0MQ 'sockets' are _not_ thread safe. Applications MUST NOT use a socket -from multiple threads except after migrating a socket from one thread to -another with a "full fence" memory barrier. - -.Socket types -0MQ defines several messaging patterns which encapsulate exact semantics of -a particular topology. For example, publush-subscribe pattern defines data -distribution trees while request-reply defines networks of shared stateless -services. Each pattern defines several socket types (roles in the pattern). - -The following sections present the socket types defined by 0MQ: - - -Request-reply pattern -~~~~~~~~~~~~~~~~~~~~~ -The request-reply pattern is used for sending requests from a _client_ to one -or more instances of a stateless _service_, and receiving subsequent replies -to each request sent. - - -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 load-balanced among all _services_, and each reply received is -matched with the last issued request. - -When a 'ZMQ_REQ' socket enters an exceptional state due to having reached the -high water mark for all _services_, or if there are no _services_ at all, then -any linkzmq:zmq_send[3] operations on the socket shall block until the -exceptional state ends or at least one _service_ becomes available for sending; -messages are not discarded. - -[horizontal] -.Summary of ZMQ_REQ characteristics -Compatible peer sockets:: 'ZMQ_REP' -Send/receive pattern:: Send, Receive, Send, Receive, ... -Outgoing routing strategy:: Load-balanced -Incoming routing strategy:: Last peer -ZMQ_HWM option action:: 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 doesn't exist any more the reply is silently discarded. - -When a 'ZMQ_REP' socket enters an exceptional state due to having reached the -high water mark for a _client_, then any replies sent to the _client_ in -question shall be dropped until the exceptional state ends. - -[horizontal] -.Summary of ZMQ_REP characteristics -Compatible peer sockets:: 'ZMQ_REQ' -Send/receive pattern:: Receive, Send, Receive, Send, ... -Incoming routing strategy:: Fair-queued -Outgoing routing strategy:: Last peer -ZMQ_HWM option action:: Drop - - -ZMQ_XREQ -^^^^^^^^ -A socket of type 'ZMQ_XREQ' is a socket type underlying 'ZMQ_REQ'. It doesn't -impose the strict order of sends and recvs as 'ZMQ_REQ' does and it is -intended for use in intermediate devices in request-reply topologies. - -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. - -[horizontal] -.Summary of ZMQ_XREQ characteristics -Compatible peer sockets:: 'ZMQ_XREP', 'ZMQ_REP' -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 a socket type underlying 'ZMQ_REP'. It doesn't -impose the strict order of sends and recvs as 'ZMQ_REQ' does and it is -intended for use in intermediate devices in request-reply topologies. - -Messages received are fair-queued from among all connected peers. The outbound -messages are routed to a specific peer, as explained below. - -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 to be routed to a non-existent peer or a peer for which -the individual high water mark has been reached shall also be dropped. - -[horizontal] -.Summary of ZMQ_XREP characteristics -Compatible peer sockets:: 'ZMQ_XREQ', 'ZMQ_REQ' -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 -a single _publisher_ to multiple _subscribers_ in a fan out fashion. - - -ZMQ_PUB -^^^^^^^ -A socket of type 'ZMQ_PUB' is used by a _publisher_ to distribute data. -Messages sent are distributed in a fan out fashion to all connected peers. -The linkzmq:zmq_recv[3] function is not implemented for this socket type. - -When a 'ZMQ_PUB' socket enters an exceptional state due to having reached the -high water mark for a _subscriber_, then any messages that would be sent to the -_subscriber_ in question shall instead be dropped until the exceptional state -ends. The _zmq_send()_ function shall never block for this socket type. - -[horizontal] -.Summary of ZMQ_PUB characteristics -Compatible peer sockets:: 'ZMQ_SUB', 'ZMQ_XSUB' -Send/receive pattern:: Send only -Incoming routing strategy:: N/A -Outgoing routing strategy:: Fan out -ZMQ_HWM option action:: Drop - - -ZMQ_SUB -^^^^^^^ -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 linkzmq:zmq_setsockopt[3] to -specify which messages to subscribe to. The _zmq_send()_ function is not -implemented for this socket type. - -[horizontal] -.Summary of ZMQ_SUB characteristics -Compatible peer sockets:: 'ZMQ_PUB', 'ZMQ_XPUB' -Send/receive pattern:: Receive only -Incoming routing strategy:: Fair-queued -Outgoing routing strategy:: N/A -ZMQ_HWM option action:: Drop - - -ZMQ_XPUB -^^^^^^^^ -Same as ZMQ_PUB except that you can receive subscriptions from the peers -in form of incoming messages. Subscription message is a byte 1 (for -subscriptions) or byte 0 (for unsubscriptions) followed by the subscription -body. - -[horizontal] -.Summary of ZMQ_XPUB characteristics -Compatible peer sockets:: 'ZMQ_SUB', 'ZMQ_XSUB' -Send/receive pattern:: Send messages, receive subscriptions -Incoming routing strategy:: N/A -Outgoing routing strategy:: Fan out -ZMQ_HWM option action:: Drop - - -ZMQ_XSUB -^^^^^^^^ -Same as ZMQ_SUB except that you subscribe by sending subscription messages to -the socket. Subscription message is a byte 1 (for subscriptions) or byte 0 -(for unsubscriptions) followed by the subscription body. - -[horizontal] -.Summary of ZMQ_XSUB characteristics -Compatible peer sockets:: 'ZMQ_PUB', 'ZMQ_XPUB' -Send/receive pattern:: Receive messages, send subscriptions -Incoming routing strategy:: Fair-queued -Outgoing routing strategy:: N/A -ZMQ_HWM option action:: Drop - - -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 load-balanced among all connected _nodes_. - - -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_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. - -[horizontal] -.Summary of ZMQ_PUSH characteristics -Compatible peer sockets:: 'ZMQ_PULL' -Direction:: Unidirectional -Send/receive pattern:: Send only -Incoming routing strategy:: N/A -Outgoing routing strategy:: Load-balanced -ZMQ_HWM option action:: Block - - -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. - -[horizontal] -.Summary of ZMQ_PULL characteristics -Compatible peer sockets:: 'ZMQ_PUSH' -Direction:: Unidirectional -Send/receive pattern:: Receive only -Incoming routing strategy:: Fair-queued -Outgoing routing strategy:: N/A -ZMQ_HWM option action:: N/A - - -Exclusive pair pattern -~~~~~~~~~~~~~~~~~~~~~~ -The exclusive pair is an advanced pattern used for communicating exclusively -between two peers. - - -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. - -When a 'ZMQ_PAIR' socket enters an exceptional state due to having reached the -high water mark for the connected peer, or if no peer is connected, then -any linkzmq:zmq_send[3] operations on the socket shall block until the peer -becomes available for sending; messages are not discarded. - -NOTE: 'ZMQ_PAIR' sockets are experimental, and are currently missing several -features such as auto-reconnection. - -[horizontal] -.Summary of ZMQ_PAIR characteristics -Compatible peer sockets:: 'ZMQ_PAIR' -Direction:: Bidirectional -Send/receive pattern:: Unrestricted -Incoming routing strategy:: N/A -Outgoing routing strategy:: N/A -ZMQ_HWM option action:: Block - - -RETURN VALUE ------------- -The _zmq_socket()_ function shall return an opaque handle to the newly created -socket if successful. Otherwise, it shall return NULL and set 'errno' to one of -the values defined below. - - -ERRORS ------- -*EINVAL*:: -The requested socket 'type' is invalid. -*EFAULT*:: -The provided 'context' is invalid. -*EMFILE*:: -The limit on the total number of open 0MQ sockets has been reached. -*ETERM*:: -The context specified was terminated. - -SEE ALSO --------- -linkzmq:zmq_init[3] -linkzmq:zmq_setsockopt[3] -linkzmq:zmq_bind[3] -linkzmq:zmq_connect[3] -linkzmq:zmq_send[3] -linkzmq:zmq_recv[3] -linkzmq:zmq[7] - - -AUTHORS -------- -The 0MQ documentation was written by Martin Sustrik and -Martin Lucina . -- cgit v1.2.3