From e645fc2693acc796304498909786b7b47005b429 Mon Sep 17 00:00:00 2001 From: Martin Lucina Date: Mon, 23 Jan 2012 08:53:35 +0100 Subject: Imported Upstream version 2.1.3 --- doc/zmq_socket.html | 1403 --------------------------------------------------- 1 file changed, 1403 deletions(-) delete mode 100644 doc/zmq_socket.html (limited to 'doc/zmq_socket.html') diff --git a/doc/zmq_socket.html b/doc/zmq_socket.html deleted file mode 100644 index 50f5844..0000000 --- a/doc/zmq_socket.html +++ /dev/null @@ -1,1403 +0,0 @@ - - - - - -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 teardown, 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.

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

-

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

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

-
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 -a single publisher to multiple subscribers in a fanout fashion.

-

ZMQ_PUB

-

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

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

-Fanout -

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

-N/A -

-
-

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

-
-
-EMTHREAD -
-
-

-The maximum number of sockets within this context has been exceeded. -

-
-
-EFAULT -
-
-

-The provided context was not valid (NULL). -

-
-
-
-

SEE ALSO

-
-

zmq_init(3) -zmq_setsockopt(3) -zmq_bind(3) -zmq_connect(3) -zmq_send(3) -zmq_recv(3) -zmq(7)

-
-

AUTHORS

-
-

The ØMQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and -Martin Lucina <mato@kotelna.sk>.

-
-
-
- - - -- cgit v1.2.3