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 ZMQ_REQ client +to one or more ZMQ_REP services, and receiving subsequent replies to each +request sent.

The request-reply pattern is formally defined by http://rfc.zeromq.org/spec:28.

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 round-robined among all services, and each reply received is +matched with the last issued request.

If no services are available, then any send operation on the socket shall +block until at least one service becomes available. The REQ socket shall +not discard messages.

Summary of ZMQ_REQ characteristics

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

+Compatible peer sockets + +	+ +ZMQ_REP, ZMQ_ROUTER + +
+Direction + +	+ +Bidirectional + +
+Send/receive pattern + +	+ +Send, Receive, Send, Receive, … + +
+Outgoing routing strategy + +	+ +Round-robin + +
+Incoming routing strategy + +	+ +Last peer + +
+Action in mute state + +	+ +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 does not exist any more the reply is silently discarded.

Summary of ZMQ_REP characteristics

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

+Compatible peer sockets + +	+ +ZMQ_REQ, ZMQ_DEALER + +
+Direction + +	+ +Bidirectional + +
+Send/receive pattern + +	+ +Receive, Send, Receive, Send, … + +
+Incoming routing strategy + +	+ +Fair-queued + +
+Outgoing routing strategy + +	+ +Last peer + +

ZMQ_DEALER

A socket of type ZMQ_DEALER is an advanced pattern used for extending +request/reply sockets. Each message sent is round-robined among all connected +peers, and each message received is fair-queued from all connected peers.

When a ZMQ_DEALER socket enters the mute 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 mute +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, ZMQ_DEALER + +
+Direction + +	+ +Bidirectional + +
+Send/receive pattern + +	+ +Unrestricted + +
+Outgoing routing strategy + +	+ +Round-robin + +
+Incoming routing strategy + +	+ +Fair-queued + +
+Action in mute state + +	+ +Block + +

ZMQ_ROUTER

A socket of type ZMQ_ROUTER is an advanced socket type 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 by default, unless ZMQ_ROUTER_MANDATORY +socket option is set to 1.

When a ZMQ_ROUTER socket enters the mute state due to having reached the +high water mark for all peers, then any messages sent to the socket shall be dropped +until the mute state ends. Likewise, any messages routed to 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, ZMQ_ROUTER + +
+Direction + +	+ +Bidirectional + +
+Send/receive pattern + +	+ +Unrestricted + +
+Outgoing routing strategy + +	+ +See text + +
+Incoming routing strategy + +	+ +Fair-queued + +
+Action in mute state + +	+ +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.

The publish-subscribe pattern is formally defined by http://rfc.zeromq.org/spec:29.

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 the mute 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 mute state +ends. The zmq_send() function shall never block for this socket type.

Summary of ZMQ_PUB characteristics

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

+Compatible peer sockets + +	+ +ZMQ_SUB, ZMQ_XSUB + +
+Direction + +	+ +Unidirectional + +
+Send/receive pattern + +	+ +Send only + +
+Incoming routing strategy + +	+ +N/A + +
+Outgoing routing strategy + +	+ +Fan out + +
+Action in mute state + +	+ +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, ZMQ_XPUB + +
+Direction + +	+ +Unidirectional + +
+Send/receive pattern + +	+ +Receive only + +
+Incoming routing strategy + +	+ +Fair-queued + +
+Outgoing routing strategy + +	+ +N/A + +

ZMQ_XPUB

Same as ZMQ_PUB except that you can receive subscriptions from the peers +in form of incoming messages. Subscription message is a byte 1 (for +subscriptions) or byte 0 (for unsubscriptions) followed by the subscription +body. Messages without a sub/unsub prefix are also received, but have no +effect on subscription status.

Summary of ZMQ_XPUB characteristics

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

+Compatible peer sockets + +	+ +ZMQ_SUB, ZMQ_XSUB + +
+Direction + +	+ +Unidirectional + +
+Send/receive pattern + +	+ +Send messages, receive subscriptions + +
+Incoming routing strategy + +	+ +N/A + +
+Outgoing routing strategy + +	+ +Fan out + +
+Action in mute state + +	+ +Drop + +

ZMQ_XSUB

Same as ZMQ_SUB except that you subscribe by sending subscription messages to +the socket. Subscription message is a byte 1 (for subscriptions) or byte 0 +(for unsubscriptions) followed by the subscription body. Messages without a +sub/unsub prefix may also be sent, but have no effect on subscription status.

Summary of ZMQ_XSUB characteristics

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

+Compatible peer sockets + +	+ +ZMQ_PUB, ZMQ_XPUB + +
+Direction + +	+ +Unidirectional + +
+Send/receive pattern + +	+ +Receive messages, send subscriptions + +
+Incoming routing strategy + +	+ +Fair-queued + +
+Outgoing routing strategy + +	+ +N/A + +
+Action in mute state + +	+ +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 round-robined among all connected nodes.

The pipeline pattern is formally defined by http://rfc.zeromq.org/spec:30.

ZMQ_PUSH

A socket of type ZMQ_PUSH is used by a pipeline node to send messages +to downstream pipeline nodes. Messages are round-robined to all connected +downstream nodes. The zmq_recv() function is not implemented for this +socket type.

When a ZMQ_PUSH socket enters the mute 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 mute state ends or at least one downstream node +becomes available for sending; messages are not discarded.

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 + +	+ +Round-robin + +
+Action in mute state + +	+ +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.

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 + +
+Action in mute state + +	+ +Block + +

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.

The exclusive pair pattern is formally defined by http://rfc.zeromq.org/spec:31.

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 the mute 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 + +
+Action in mute state + +	+ +Block + +

Native Pattern

The native pattern is used for communicating with TCP peers and allows +asynchronous requests and replies in either direction.

ZMQ_STREAM

A socket of type ZMQ_STREAM is used to send and receive TCP data from a +non-ØMQ peer, when using the tcp:// transport. A ZMQ_STREAM socket can +act as client and/or server, sending and/or receiving TCP data asynchronously.

When receiving TCP data, a ZMQ_STREAM 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 TCP data, a ZMQ_STREAM 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, and unroutable messages shall cause an EHOSTUNREACH or EAGAIN error.

To open a connection to a server, use the zmq_connect call, and then fetch the +socket identity using the ZMQ_IDENTITY zmq_getsockopt call.

To close a specific client connection, as a server, send the identity frame +followed by a zero-length message (see EXAMPLE section).

The ZMQ_MSGMORE flag is ignored on data frames. You must send one identity frame +followed by one data frame.

Also, please note that omitting the ZMQ_MSGMORE flag will prevent sending further +data (from any client) on the same socket.

Summary of ZMQ_STREAM characteristics

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

+Compatible peer sockets + +	+ +none. + +
+Direction + +	+ +Bidirectional + +
+Send/receive pattern + +	+ +Unrestricted + +
+Outgoing routing strategy + +	+ +See text + +
+Incoming routing strategy + +	+ +Fair-queued + +
+Action in mute state + +	+ +EAGAIN + +

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 is invalid. +
+
+EMFILE +: +
+The limit on the total number of open ØMQ sockets has been reached. +
+
+ETERM +: +
+The context specified was terminated. +
+

EXAMPLE

Creating a simple HTTP server using ZMQ_STREAM

void *ctx = zmq_ctx_new ();
+assert (ctx);
+/* Create ZMQ_STREAM socket */
+void *socket = zmq_socket (ctx, ZMQ_STREAM);
+assert (socket);
+int rc = zmq_bind (socket, "tcp://*:8080");
+assert (rc == 0);
+/* Data structure to hold the ZMQ_STREAM ID */
+uint8_t id [256];
+size_t id_size = 256;
+while (1) {
+        /*  Get HTTP request; ID frame and then request */
+        id_size = zmq_recv (socket, id, 256, 0);
+        assert (id_size > 0);
+        /* Prepares the response */
+        char http_response [] =
+                "HTTP/1.0 200 OK\r\n"
+                "Content-Type: text/plain\r\n"
+                "\r\n"
+                "Hello, World!";
+        /* Sends the ID frame followed by the response */
+        zmq_send (socket, id, id_size, ZMQ_SNDMORE);
+        zmq_send (socket, http_response, strlen (http_response), ZMQ_SNDMORE);
+        /* Closes the connection by sending the ID frame followed by a zero response */
+        zmq_send (socket, id, id_size, ZMQ_SNDMORE);
+        zmq_send (socket, 0, 0, ZMQ_SNDMORE);
+        /* NOTE: If we don't use ZMQ_SNDMORE, then we won't be able to send more */
+        /* message to any client */
+}
+zmq_close (socket);
+zmq_ctx_destroy (ctx);

AUTHORS

This page was written by the ØMQ community. To make a change please +read the ØMQ Contribution Policy at http://www.zeromq.org/docs:contributing.

+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

ZMQ_XPUB

ZMQ_XSUB

Pipeline pattern

ZMQ_PUSH

ZMQ_PULL

Exclusive pair pattern

ZMQ_PAIR

Native Pattern

ZMQ_STREAM

RETURN VALUE

ERRORS

EXAMPLE

SEE ALSO

AUTHORS