diff options
Diffstat (limited to 'doc/zmq_socket.txt')
-rw-r--r-- | doc/zmq_socket.txt | 184 |
1 files changed, 96 insertions, 88 deletions
diff --git a/doc/zmq_socket.txt b/doc/zmq_socket.txt index b6cdc35..c53779c 100644 --- a/doc/zmq_socket.txt +++ b/doc/zmq_socket.txt @@ -4,110 +4,117 @@ zmq_socket(3) NAME ---- -zmq_socket - creates 0MQ socket +zmq_socket - create 0MQ socket SYNOPSIS -------- -'void *zmq_socket (void *context, int type);' +*void *zmq_socket (void '*context', int 'type');* DESCRIPTION ----------- -Open a socket within the specified 'context'. To create a context, use -'zmq_init' function. 'type' argument can be one of the values defined below. -Note that each socket is owned by exactly one thread (the one that it was -created from) and should not be used from any other thread. - -*ZMQ_P2P*:: -Socket to communicate with a single peer. Allows for only a single connect -or a single bind. There's no message routing or message filtering involved. -+ -Compatible peer sockets: ZMQ_P2P. - -*ZMQ_PUB*:: -Socket to distribute data. Recv function is not implemented for this socket -type. Messages are distributed in fanout fashion to all the peers. -+ -Compatible peer sockets: ZMQ_SUB. - -*ZMQ_SUB*:: -Socket to subscribe for data. Send function is not implemented for this socket -type. Initially, socket is subscribed for no messages. Use ZMQ_SUBSCRIBE option -to specify which messages to subscribe for. -+ -Compatible peer sockets: ZMQ_PUB. - -*ZMQ_REQ*:: -Socket to send requests and receive replies. Requests are load-balanced among -all the peers. This socket type allows only an alternated sequence of send's -and recv's. -+ -Compatible peer sockets: ZMQ_REP, ZMQ_XREP. - -*ZMQ_REP*:: -Socket to receive requests and send replies. This socket type allows only an -alternated sequence of recv's and send's. Each send is routed to the peer that -issued the last received request. -+ -Compatible peer sockets: ZMQ_REQ, ZMQ_XREQ. - -*ZMQ_XREQ*:: -Special socket type to be used in request/reply middleboxes such as -linkzmq:zmq_queue[7]. Requests forwarded using this socket type should be -tagged by a proper prefix identifying the original requester. Replies received -by this socket are tagged with a proper prefix that can be use to route the -reply back to the original requester. -+ -Compatible peer sockets: ZMQ_REP, ZMQ_XREP. - -*ZMQ_XREP*:: -Special socket type to be used in request/reply middleboxes such as -linkzmq:zmq_queue[7]. Requests received using this socket are already properly -tagged with prefix identifying the original requester. When sending a reply via -XREP socket the message should be tagged with a prefix from a corresponding -request. -+ -Compatible peer sockets: ZMQ_REQ, ZMQ_XREQ. - -*ZMQ_UPSTREAM*:: -Socket to receive messages from up the stream. Messages are fair-queued from -among all the connected peers. Send function is not implemented for this socket -type. -+ -Compatible peer sockets: ZMQ_DOWNSTREAM. - -*ZMQ_DOWNSTREAM*:: -Socket to send messages down stream. Messages are load-balanced among all the -connected peers. Recv function is not implemented for this socket type. -+ -Compatible peer sockets: ZMQ_UPSTREAM. +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 _messaging pattern_, which determines the semantics of +communication over the socket. + +The following _messaging patterns_ are defined: + + +Peer to peer pattern +~~~~~~~~~~~~~~~~~~~~ +The simplest messaging pattern, used for communicating between two peers. + +Socket type:: 'ZMQ_P2P' +Compatible peer sockets:: 'ZMQ_P2P' + +A socket of type 'ZMQ_P2P' 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_P2P' socket. + + +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 fanout fashion. + +Socket type:: 'ZMQ_PUB' +Compatible peer sockets:: 'ZMQ_SUB' + +A socket of type 'ZMQ_PUB' is used by a _publisher_ to distribute data. +Messages sent are distributed in a fanout fashion to all connected peers. +The _zmq_recv()_ function is not implemented for this socket type. + +Socket type:: 'ZMQ_SUB' +Compatible peer sockets:: 'ZMQ_PUB' + +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 _zmq_setsockopt()_ to specify +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' + +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. + + +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' + +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_DOWNSTREAM' +Compatible peer sockets:: 'ZMQ_UPSTREAM' + +A socket of type 'ZMQ_DOWNSTREAM' is used by a _component_ of a pipeline to +send messages to downstream stages of the pipeline. The _zmq_recv()_ function +is not implemented for this socket type. RETURN VALUE ------------ -Function returns socket handle is successful. Otherwise it returns NULL and -sets errno to one of the values below. +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*:: - invalid socket type. +The requested socket 'type' is invalid. *EMTHREAD*:: - the number of application threads allowed to own 0MQ sockets was exceeded. - See 'app_threads' parameter to 'zmq_init' function. - - -EXAMPLE -------- ----- -void *s = zmq_socket (context, ZMQ_PUB); -assert (s); -int rc = zmq_bind (s, "tcp://192.168.0.1:5555"); -assert (rc == 0); ----- +The number of application threads using sockets within this 'context' has been +exceeded. See the 'app_threads' parameter of the _zmq_init()_ function. SEE ALSO @@ -121,6 +128,7 @@ linkzmq:zmq_flush[3] linkzmq:zmq_recv[3] -AUTHOR ------- -Martin Sustrik <sustrik at 250bpm dot com> +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and +Martin Lucina <mato@kotelna.sk>. |