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

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_DOWNSTREAM

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

Summary of ZMQ_DOWNSTREAM characteristics

+ + + + + + + + + + + + + + + + + + + + + + + + +

+Compatible peer sockets + +	+ +ZMQ_UPSTREAM + +
+Direction + +	+ +Unidirectional + +
+Send/receive pattern + +	+ +Send only + +
+Incoming routing strategy + +	+ +N/A + +
+Outgoing routing strategy + +	+ +Load-balanced + +
+ZMQ_HWM option action + +	+ +Block + +

ZMQ_UPSTREAM

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

Summary of ZMQ_UPSTREAM characteristics

+ + + + + + + + + + + + + + + + + + + + + + + + +

+Compatible peer sockets + +	+ +ZMQ_DOWNSTREAM + +
+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. +
+

AUTHORS

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

Publish-subscribe pattern

ZMQ_PUB

ZMQ_SUB

Pipeline pattern

ZMQ_DOWNSTREAM

ZMQ_UPSTREAM

Exclusive pair pattern

ZMQ_PAIR

RETURN VALUE

ERRORS

SEE ALSO

AUTHORS