From 8e61b98c5e2943b149c825310b24e714a6127072 Mon Sep 17 00:00:00 2001 From: Martin Lucina Date: Mon, 23 Jan 2012 08:53:41 +0100 Subject: Imported Upstream version 2.1.4 --- doc/zmq_socket.html | 1416 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1416 insertions(+) create mode 100644 doc/zmq_socket.html (limited to 'doc/zmq_socket.html') diff --git a/doc/zmq_socket.html b/doc/zmq_socket.html new file mode 100644 index 0000000..3815b04 --- /dev/null +++ b/doc/zmq_socket.html @@ -0,0 +1,1416 @@ + + + + + +zmq_socket(3) + + + + + +
+

SYNOPSIS

+
+

void *zmq_socket (void *context, int type);

+
+

DESCRIPTION

+
+

The zmq_socket() function shall create a ØMQ 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 zmq_connect(3), or at least one +endpoint must be created for accepting incoming connections with +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, ØMQ 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, ØMQ sockets transfer +discrete messages.

+

ØMQ 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 ØMQ 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, ØMQ 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

ØMQ 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

The following sections present the socket types defined by ØMQ, grouped by the +general messaging pattern which is built from related socket types.

+

Request-reply pattern

+

The request-reply pattern is used for sending requests from a client to one +or more instances of a 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 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.

+
Summary of ZMQ_REQ characteristics
+ + + + + + + + + + + + + + + + + + + + + + + + +
+Compatible peer sockets +
+
+

+ZMQ_REP +

+
+Direction +
+
+

+Bidirectional +

+
+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.

+
Summary of ZMQ_REP characteristics
+ + + + + + + + + + + + + + + + + + + + + + + + +
+Compatible peer sockets +
+
+

+ZMQ_REQ +

+
+Direction +
+
+

+Bidirectional +

+
+Send/receive pattern +
+
+

+Receive, Send, Receive, Send, … +

+
+Incoming routing strategy +
+
+

+Fair-queued +

+
+Outgoing routing strategy +
+
+

+Last peer +

+
+ZMQ_HWM option action +
+
+

+Drop +

+
+

ZMQ_DEALER

+

A socket of type ZMQ_DEALER 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.

+

Previously this socket was called ZMQ_XREQ and that name remains available +for backwards compatibility.

+

When a ZMQ_DEALER 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 +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_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.

+
Summary of ZMQ_DEALER characteristics
+ + + + + + + + + + + + + + + + + + + + + + + + +
+Compatible peer sockets +
+
+

+ZMQ_ROUTER, ZMQ_REP +

+
+Direction +
+
+

+Bidirectional +

+
+Send/receive pattern +
+
+

+Unrestricted +

+
+Outgoing routing strategy +
+
+

+Load-balanced +

+
+Incoming routing strategy +
+
+

+Fair-queued +

+
+ZMQ_HWM option action +
+
+

+Block +

+
+

ZMQ_ROUTER

+

A socket of type ZMQ_ROUTER is an advanced pattern 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.

+

Previously this socket was called ZMQ_XREP and that name remains available +for backwards compatibility.

+

When a ZMQ_ROUTER 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_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.

+
Summary of ZMQ_ROUTER characteristics
+ + + + + + + + + + + + + + + + + + + + + + + + +
+Compatible peer sockets +
+
+

+ZMQ_DEALER, 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 +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 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.

+
Summary of ZMQ_PUB characteristics
+ + + + + + + + + + + + + + + + + + + + + + + + +
+Compatible peer sockets +
+
+

+ZMQ_SUB +

+
+Direction +
+
+

+Unidirectional +

+
+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 zmq_setsockopt(3) to +specify which messages to subscribe to. The zmq_send() function is not +implemented for this socket type.

+
Summary of ZMQ_SUB characteristics
+ + + + + + + + + + + + + + + + + + + + + + + + +
+Compatible peer sockets +
+
+

+ZMQ_PUB +

+
+Direction +
+
+

+Unidirectional +

+
+Send/receive pattern +
+
+

+Receive only +

+
+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 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.

+
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.

+

Deprecated alias: ZMQ_UPSTREAM.

+
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 pattern is used to connect a peer to precisely one other +peer. This pattern is used for inter-thread communication across the inproc +transport.

+

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 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 designed for inter-thread communication across +the zmq_inproc(7) transport and do not implement functionality such +as auto-reconnection. ZMQ_PAIR sockets are considered experimental and may +have other missing or broken aspects.
+
+
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 was not valid (NULL). +

+
+
+ETERM +
+
+

+The context specified was terminated. +

+
+
+
+

SEE ALSO

+ +

AUTHORS

+
+

This ØMQ manual page was written by Martin Sustrik <sustrik@250bpm.com> and +Martin Lucina <mato@kotelna.sk>.

+
+
+

+ + + -- cgit v1.2.3