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

AUTHORS

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

+zmq_socket(3) Manual Page +

NAME

SYNOPSIS

DESCRIPTION

Request-reply pattern

ZMQ_REQ

ZMQ_REP

ZMQ_DEALER

ZMQ_ROUTER

Publish-subscribe pattern

ZMQ_PUB

ZMQ_SUB

Pipeline pattern

ZMQ_PUSH

ZMQ_PULL

Exclusive pair pattern

ZMQ_PAIR

RETURN VALUE

ERRORS

SEE ALSO

AUTHORS