1ZMQ_SOCKET(3) 0MQ Manual ZMQ_SOCKET(3)
2
6 zmq_socket - create 0MQ socket
7
9 void *zmq_socket (void *context, int type);
10
12 The zmq_socket() function shall create a 0MQ socket within the
13 specified context and return an opaque handle to the newly created
14 socket. The type argument specifies the socket type, which determines
15 the semantics of communication over the socket.
16 The newly created socket is initially unbound, and not associated with
18 any endpoints. In order to establish a message flow a socket must first
19 be connected to at least one endpoint with zmq_connect(3), or at least
20 one endpoint must be created for accepting incoming connections with
21 zmq_bind(3).
22 Key differences to conventional sockets. Generally speaking,
24 conventional sockets present a synchronous interface to either
25 connection-oriented reliable byte streams (SOCK_STREAM), or
26 connection-less unreliable datagrams (SOCK_DGRAM). In comparison, 0MQ
27 sockets present an abstraction of an asynchronous message queue, with
28 the exact queueing semantics depending on the socket type in use. Where
29 conventional sockets transfer streams of bytes or discrete datagrams,
30 0MQ sockets transfer discrete messages.
31 0MQ sockets being asynchronous means that the timings of the physical
33 connection setup and tear down, reconnect and effective delivery are
34 transparent to the user and organized by 0MQ itself. Further, messages
35 may be queued in the event that a peer is unavailable to receive them.
36 Conventional sockets allow only strict one-to-one (two peers),
38 many-to-one (many clients, one server), or in some cases one-to-many
39 (multicast) relationships. With the exception of ZMQ_PAIR and
40 ZMQ_CHANNEL, 0MQ sockets may be connected to multiple endpoints using
41 zmq_connect(), while simultaneously accepting incoming connections from
42 multiple endpoints bound to the socket using zmq_bind(), thus allowing
43 many-to-many relationships.
44 Thread safety. 0MQ has both thread safe socket type and not thread safe
46 socket types. Applications MUST NOT use a not thread safe socket from
47 multiple threads under any circumstances. Doing so results in undefined
48 behaviour.
49 Following are the thread safe sockets: * ZMQ_CLIENT * ZMQ_SERVER *
51 ZMQ_DISH * ZMQ_RADIO * ZMQ_SCATTER * ZMQ_GATHER * ZMQ_PEER *
52 ZMQ_CHANNEL
53 Socket types. The following sections present the socket types defined
55 by 0MQ, grouped by the general messaging pattern which is built from
56 related socket types.
57 Client-server pattern
59 The client-server pattern is used to allow a single ZMQ_SERVER server
60 talk to one or more ZMQ_CLIENT clients. The client always starts the
61 conversation, after which either peer can send messages asynchronously,
62 to the other.
63 The client-server pattern is formally defined by
65 http://rfc.zeromq.org/spec:41.
66 Note
68 Server-client is still in draft phase.
69 ZMQ_CLIENT
71 A ZMQ_CLIENT socket talks to a ZMQ_SERVER socket. Either peer can
72 connect, though the usual and recommended model is to bind the
73 ZMQ_SERVER and connect the ZMQ_CLIENT.
74 If the ZMQ_CLIENT socket has established a connection, zmq_send(3)
76 will accept messages, queue them, and send them as rapidly as the
77 network allows. The outgoing buffer limit is defined by the high
78 water mark for the socket. If the outgoing buffer is full, or, for
79 connection-oriented transports, if the ZMQ_IMMEDIATE option is set
80 and there is no connected peer, zmq_send(3) will block. The
81 ZMQ_CLIENT socket will not drop messages.
82 When a ZMQ_CLIENT socket is connected to multiple ZMQ_SERVER
84 sockets, outgoing messages are distributed between connected peers
85 on a round-robin basis. Likewise, the ZMQ_CLIENT socket receives
86 messages fairly from each connected peer. This usage is sensible
87 only for stateless protocols.
88 ZMQ_CLIENT sockets are threadsafe and can be used from multiple
90 threads at the same time. Note that replies from a ZMQ_SERVER
91 socket will go to the first client thread that calls
92 zmq_msg_recv(3). If you need to get replies back to the originating
93 thread, use one ZMQ_CLIENT socket per thread.
94 Note
96 ZMQ_CLIENT sockets are threadsafe. They do not accept the
97 ZMQ_SNDMORE option on sends not ZMQ_RCVMORE on receives. This
98 limits them to single part data. The intention is to extend the
99 API to allow scatter/gather of multi-part data.
100 Table 1. Summary of ZMQ_CLIENT characteristics
102 Compatible peer sockets ZMQ_SERVER
103 Direction Bidirectional
105 Send/receive pattern Unrestricted
107 Outgoing routing strategy Round-robin
109 Incoming routing strategy Fair-queued
111 Action in mute state Block
113 ZMQ_SERVER
116 A ZMQ_SERVER socket talks to a set of ZMQ_CLIENT sockets. A
117 ZMQ_SERVER socket can only reply to an incoming message: the
118 ZMQ_CLIENT peer must always initiate a conversation.
119 Each received message has a routing_id that is a 32-bit unsigned
121 integer. The application can fetch this with zmq_msg_routing_id(3).
122 To send a message to a given ZMQ_CLIENT peer the application must
123 set the peer’s routing_id on the message, using
124 zmq_msg_set_routing_id(3).
125 If the routing_id is not specified, or does not refer to a
127 connected client peer, the send call will fail with EHOSTUNREACH.
128 If the outgoing buffer for the client peer is full, the send call
129 shall block, unless ZMQ_DONTWAIT is used in the send, in which case
130 it shall fail with EAGAIN. The ZMQ_SERVER socket shall not drop
131 messages in any case.
132 Note
134 ZMQ_SERVER sockets are threadsafe. They do not accept the
135 ZMQ_SNDMORE option on sends not ZMQ_RCVMORE on receives. This
136 limits them to single part data. The intention is to extend the
137 API to allow scatter/gather of multi-part data.
138 Table 2. Summary of ZMQ_SERVER characteristics
140 Compatible peer sockets ZMQ_CLIENT
141 Direction Bidirectional
143 Send/receive pattern Unrestricted
145 Outgoing routing strategy See text
147 Incoming routing strategy Fair-queued
149 Action in mute state Return EAGAIN
151 Radio-dish pattern
154 The radio-dish pattern is used for one-to-many distribution of data
155 from a single publisher to multiple subscribers in a fan out fashion.
156 Radio-dish is using groups (vs Pub-sub topics), Dish sockets can join a
158 group and each message sent by Radio sockets belong to a group.
159 Groups are null terminated strings limited to 16 chars length
161 (including null). The intention is to increase the length to 40 chars
162 (including null). The encoding of groups shall be UTF8.
163 Groups are matched using exact matching (vs prefix matching of PubSub).
165 Note
167 Radio-dish is still in draft phase.
168 ZMQ_RADIO
170 A socket of type ZMQ_RADIO is used by a publisher to distribute
171 data. Each message belong to a group, a group is specified with
172 zmq_msg_set_group(3). Messages are distributed to all members of a
173 group. The zmq_recv(3) function is not implemented for this socket
174 type.
175 When a ZMQ_RADIO socket enters the mute state due to having reached
177 the high water mark for a subscriber, then any messages that would
178 be sent to the subscriber in question shall instead be dropped
179 until the mute state ends. The zmq_send() function shall never
180 block for this socket type.
181 Note
183 ZMQ_RADIO sockets are threadsafe. They do not accept the
184 ZMQ_SNDMORE option on sends. This limits them to single part
185 data.
186 Table 3. Summary of ZMQ_RADIO characteristics
188 Compatible peer sockets ZMQ_DISH
189 Direction Unidirectional
191 Send/receive pattern Send only
193 Incoming routing strategy N/A
195 Outgoing routing strategy Fan out
197 Action in mute state Drop
201 ZMQ_DISH
204 A socket of type ZMQ_DISH is used by a subscriber to subscribe to
205 groups distributed by a radio. Initially a ZMQ_DISH socket is not
206 subscribed to any groups, use zmq_join(3) to join a group. To get
207 the group the message belong to call zmq_msg_group(3). The
208 zmq_send() function is not implemented for this socket type.
209 Note
211 ZMQ_DISH sockets are threadsafe. They do not accept ZMQ_RCVMORE
212 on receives. This limits them to single part data.
213 Table 4. Summary of ZMQ_DISH characteristics
215 Compatible peer sockets ZMQ_RADIO
216 Direction Unidirectional
218 Send/receive pattern Receive only
220 Incoming routing strategy Fair-queued
222 Outgoing routing strategy N/A
224 Publish-subscribe pattern
227 The publish-subscribe pattern is used for one-to-many distribution of
228 data from a single publisher to multiple subscribers in a fan out
229 fashion.
230 The publish-subscribe pattern is formally defined by
232 http://rfc.zeromq.org/spec:29.
233 ZMQ_PUB
235 A socket of type ZMQ_PUB is used by a publisher to distribute data.
236 Messages sent are distributed in a fan out fashion to all connected
237 peers. The zmq_recv(3) function is not implemented for this socket
238 type.
239 When a ZMQ_PUB socket enters the mute state due to having reached
241 the high water mark for a subscriber, then any messages that would
242 be sent to the subscriber in question shall instead be dropped
243 until the mute state ends. The zmq_send() function shall never
244 block for this socket type.
245 Table 5. Summary of ZMQ_PUB characteristics
247 Compatible peer sockets ZMQ_SUB, ZMQ_XSUB
248 Direction Unidirectional
250 Send/receive pattern Send only
252 Incoming routing strategy N/A
254 Outgoing routing strategy Fan out
256 Action in mute state Drop
258 ZMQ_SUB
261 A socket of type ZMQ_SUB is used by a subscriber to subscribe to
262 data distributed by a publisher. Initially a ZMQ_SUB socket is not
263 subscribed to any messages, use the ZMQ_SUBSCRIBE option of
264 zmq_setsockopt(3) to specify which messages to subscribe to. The
265 zmq_send() function is not implemented for this socket type.
266 Table 6. Summary of ZMQ_SUB characteristics
268 Compatible peer sockets ZMQ_PUB, ZMQ_XPUB
269 Direction Unidirectional
271 Send/receive pattern Receive only
273 Incoming routing strategy Fair-queued
275 Outgoing routing strategy N/A
277 ZMQ_XPUB
280 Same as ZMQ_PUB except that you can receive subscriptions from the
281 peers in form of incoming messages. Subscription message is a byte
282 1 (for subscriptions) or byte 0 (for unsubscriptions) followed by
283 the subscription body. Messages without a sub/unsub prefix are also
284 received, but have no effect on subscription status.
285 Table 7. Summary of ZMQ_XPUB characteristics
287 Compatible peer sockets ZMQ_SUB, ZMQ_XSUB
288 Direction Unidirectional
290 Send/receive pattern Send messages, receive
292 subscriptions
293 Incoming routing strategy N/A
295 Outgoing routing strategy Fan out
297 Action in mute state Drop
299 ZMQ_XSUB
302 Same as ZMQ_SUB except that you subscribe by sending subscription
303 messages to the socket. Subscription message is a byte 1 (for
304 subscriptions) or byte 0 (for unsubscriptions) followed by the
305 subscription body. Messages without a sub/unsub prefix may also be
306 sent, but have no effect on subscription status.
307 Table 8. Summary of ZMQ_XSUB characteristics
309 Compatible peer sockets ZMQ_PUB, ZMQ_XPUB
310 Direction Unidirectional
312 Send/receive pattern Receive messages, send
314 subscriptions
315 Incoming routing strategy Fair-queued
317 Outgoing routing strategy N/A
319 Action in mute state Drop
321 Pipeline pattern
324 The pipeline pattern is used for distributing data to nodes arranged in
325 a pipeline. Data always flows down the pipeline, and each stage of the
326 pipeline is connected to at least one node. When a pipeline stage is
327 connected to multiple nodes data is round-robined among all connected
328 nodes.
329 The pipeline pattern is formally defined by
331 http://rfc.zeromq.org/spec:30.
332 ZMQ_PUSH
334 A socket of type ZMQ_PUSH is used by a pipeline node to send
335 messages to downstream pipeline nodes. Messages are round-robined
336 to all connected downstream nodes. The zmq_recv() function is not
337 implemented for this socket type.
338 When a ZMQ_PUSH socket enters the mute state due to having reached
340 the high water mark for all downstream nodes, or, for
341 connection-oriented transports, if the ZMQ_IMMEDIATE option is set
342 and there are no downstream nodes at all, then any zmq_send(3)
343 operations on the socket shall block until the mute state ends or
344 at least one downstream node becomes available for sending;
345 messages are not discarded.
346 Table 9. Summary of ZMQ_PUSH characteristics
348 Compatible peer sockets ZMQ_PULL
349 Direction Unidirectional
351 Send/receive pattern Send only
353 Incoming routing strategy N/A
355 Outgoing routing strategy Round-robin
357 Action in mute state Block
359 ZMQ_PULL
362 A socket of type ZMQ_PULL is used by a pipeline node to receive
363 messages from upstream pipeline nodes. Messages are fair-queued
364 from among all connected upstream nodes. The zmq_send() function is
365 not implemented for this socket type.
366 Table 10. Summary of ZMQ_PULL characteristics
368 Compatible peer sockets ZMQ_PUSH
369 Direction Unidirectional
371 Send/receive pattern Receive only
373 Incoming routing strategy Fair-queued
375 Outgoing routing strategy N/A
377 Action in mute state Block
379 Scatter-gather pattern
382 The scatter-gather pattern is the thread-safe version of the pipeline pattern.
384 The scatter-gather pattern is used for distributing data to _nodes_ arranged in
385 a pipeline. Data always flows down the pipeline, and each stage of the pipeline
386 is connected to at least one _node_. When a pipeline stage is connected to
387 multiple _nodes_ data is round-robined among all connected _nodes_.
388 ZMQ_SCATTER
390 ^^^^^^^^
391 A socket of type 'ZMQ_SCATTER' is used by a scatter-gather _node_ to send messages
392 to downstream scatter-gather _nodes_. Messages are round-robined to all connected
393 downstream _nodes_. The _zmq_recv()_ function is not implemented for this
394 socket type.
395 When a 'ZMQ_SCATTER' socket enters the 'mute' state due to having reached the
397 high water mark for all downstream _nodes_, or, for connection-oriented transports,
398 if the ZMQ_IMMEDIATE option is set and there are no downstream _nodes_ at all,
399 then any linkzmq:zmq_send[3] operations on the socket shall block until the mute
400 state ends or at least one downstream _node_ becomes available for sending;
401 messages are not discarded.
402 NOTE: 'ZMQ_SCATTER' sockets are threadsafe. They do not accept ZMQ_RCVMORE on receives.
404 This limits them to single part data.
405 [horizontal]
407 .Summary of ZMQ_SCATTER characteristics
408 Compatible peer sockets:: 'ZMQ_SCATTER'
409 Direction:: Unidirectional
410 Send/receive pattern:: Send only
411 Incoming routing strategy:: N/A
412 Outgoing routing strategy:: Round-robin
413 Action in mute state:: Block
414 ZMQ_GATHER
417 ^^^^^^^^
418 A socket of type 'ZMQ_GATHER' is used by a scatter-gather _node_ to receive messages
419 from upstream scatter-gather _nodes_. Messages are fair-queued from among all
420 connected upstream _nodes_. The _zmq_send()_ function is not implemented for
421 this socket type.
422 NOTE: 'ZMQ_GATHER' sockets are threadsafe. They do not accept ZMQ_RCVMORE on receives.
424 This limits them to single part data.
425 [horizontal]
427 .Summary of ZMQ_GATHER characteristics
428 Compatible peer sockets:: 'ZMQ_GATHER'
429 Direction:: Unidirectional
430 Send/receive pattern:: Receive only
431 Incoming routing strategy:: Fair-queued
432 Outgoing routing strategy:: N/A
433 Action in mute state:: Block
434 Exclusive pair pattern
437 The exclusive pair pattern is used to connect a peer to precisely
439 one other peer. This pattern is used for inter-thread communication
440 across the inproc transport.
441 The exclusive pair pattern is formally defined by
443 http://rfc.zeromq.org/spec:31.
444 ZMQ_PAIR
446 A socket of type ZMQ_PAIR can only be connected to a single peer at
447 any one time. No message routing or filtering is performed on
448 messages sent over a ZMQ_PAIR socket.
449 When a ZMQ_PAIR socket enters the mute state due to having reached
451 the high water mark for the connected peer, or, for
452 connection-oriented transports, if the ZMQ_IMMEDIATE option is set
453 and there is no connected peer, then any zmq_send(3) operations on
454 the socket shall block until the peer becomes available for
455 sending; messages are not discarded.
456 While ZMQ_PAIR sockets can be used over transports other than
458 zmq_inproc(7), their inability to auto-reconnect coupled with the
459 fact new incoming connections will be terminated while any previous
460 connections (including ones in a closing state) exist makes them
461 unsuitable for TCP in most cases.
462 Note
464 ZMQ_PAIR sockets are designed for inter-thread communication
465 across the zmq_inproc(7) transport and do not implement
466 functionality such as auto-reconnection.
467 Table 11. Summary of ZMQ_PAIR characteristics
469 Compatible peer sockets ZMQ_PAIR
470 Direction Bidirectional
472 Send/receive pattern Unrestricted
474 Incoming routing strategy N/A
476 Outgoing routing strategy N/A
478 Action in mute state Block
480 Peer-to-peer pattern
483 The peer-to-peer pattern is used to connect a peer to multiple peers.
484 Peer can both connect and bind and mix both of them with the same
485 socket. The peer-to-peer pattern is useful to build peer-to-peer
486 networks (e.g zyre, bitcoin, torrent) where a peer can both accept
487 connections from other peers or connect to them.
488 Note
490 Peer-to-peer is still in draft phase.
491 ZMQ_PEER
493 A ZMQ_PEER socket talks to a set of ZMQ_PEER sockets.
494 To connect and fetch the routing_id of the peer use
496 zmq_connect_peer(3).
497 Each received message has a routing_id that is a 32-bit unsigned
499 integer. The application can fetch this with zmq_msg_routing_id(3).
500 To send a message to a given ZMQ_PEER peer the application must set
502 the peer’s routing_id on the message, using
503 zmq_msg_set_routing_id(3).
504 If the routing_id is not specified, or does not refer to a
506 connected client peer, the send call will fail with EHOSTUNREACH.
507 If the outgoing buffer for the peer is full, the send call shall
508 block, unless ZMQ_DONTWAIT is used in the send, in which case it
509 shall fail with EAGAIN. The ZMQ_PEER socket shall not drop messages
510 in any case.
511 Note
513 ZMQ_PEER sockets are threadsafe. They do not accept the
514 ZMQ_SNDMORE option on sends not ZMQ_RCVMORE on receives. This
515 limits them to single part data.
516 Table 12. Summary of ZMQ_PEER characteristics
518 Compatible peer sockets ZMQ_PEER
519 Direction Bidirectional
521 Send/receive pattern Unrestricted
523 Outgoing routing strategy See text
525 Incoming routing strategy Fair-queued
527 Action in mute state Return EAGAIN
531 Channel pattern
534 The channel pattern is the thread-safe version of the exclusive pair pattern.
536 The channel pattern is used to connect a peer to precisely one other
537 peer. This pattern is used for inter-thread communication across the inproc
538 transport.
539 NOTE: Channel is still in draft phase.
541 ZMQ_CHANNEL
543 ^^^^^^^^
544 A socket of type 'ZMQ_CHANNEL' can only be connected to a single peer at any one
545 time. No message routing or filtering is performed on messages sent over a
546 'ZMQ_CHANNEL' socket.
547 When a 'ZMQ_CHANNEL' socket enters the 'mute' state due to having reached the
549 high water mark for the connected peer, or, for connection-oriented transports,
550 if the ZMQ_IMMEDIATE option is set and there is no connected peer, then
551 any linkzmq:zmq_send[3] operations on the socket shall block until the peer
552 becomes available for sending; messages are not discarded.
553 While 'ZMQ_CHANNEL' sockets can be used over transports other than linkzmq:zmq_inproc[7],
555 their inability to auto-reconnect coupled with the fact new incoming connections will
556 be terminated while any previous connections (including ones in a closing state)
557 exist makes them unsuitable for TCP in most cases.
558 NOTE: 'ZMQ_CHANNEL' sockets are designed for inter-thread communication across
560 the linkzmq:zmq_inproc[7] transport and do not implement functionality such
561 as auto-reconnection.
562 NOTE: 'ZMQ_CHANNEL' sockets are threadsafe. They do not accept ZMQ_RCVMORE on receives.
564 This limits them to single part data.
565 [horizontal]
567 .Summary of ZMQ_CHANNEL characteristics
568 Compatible peer sockets:: 'ZMQ_CHANNEL'
569 Direction:: Bidirectional
570 Send/receive pattern:: Unrestricted
571 Incoming routing strategy:: N/A
572 Outgoing routing strategy:: N/A
573 Action in mute state:: Block
574 Native Pattern
576 The native pattern is used for communicating with TCP peers and
578 allows asynchronous requests and replies in either direction.
579 ZMQ_STREAM
581 A socket of type ZMQ_STREAM is used to send and receive TCP data
582 from a non-0MQ peer, when using the tcp:// transport. A ZMQ_STREAM
583 socket can act as client and/or server, sending and/or receiving
584 TCP data asynchronously.
585 When receiving TCP data, a ZMQ_STREAM socket shall prepend a
587 message part containing the routing id of the originating peer to
588 the message before passing it to the application. Messages received
589 are fair-queued from among all connected peers.
590 When sending TCP data, a ZMQ_STREAM socket shall remove the first
592 part of the message and use it to determine the routing id of the
593 peer the message shall be routed to, and unroutable messages shall
594 cause an EHOSTUNREACH or EAGAIN error.
595 To open a connection to a server, use the zmq_connect call, and
597 then fetch the socket routing id using the zmq_getsockopt call with
598 the ZMQ_ROUTING_ID option.
599 To close a specific connection, send the routing id frame followed
601 by a zero-length message (see EXAMPLE section).
602 When a connection is made, a zero-length message will be received
604 by the application. Similarly, when the peer disconnects (or the
605 connection is lost), a zero-length message will be received by the
606 application.
607 You must send one routing id frame followed by one data frame. The
609 ZMQ_SNDMORE flag is required for routing id frames but is ignored
610 on data frames.
611 Table 13. Summary of ZMQ_STREAM characteristics
613 Compatible peer sockets none.
614 Direction Bidirectional
616 Send/receive pattern Unrestricted
618 Outgoing routing strategy See text
620 Incoming routing strategy Fair-queued
622 Action in mute state EAGAIN
624 Request-reply pattern
627 The request-reply pattern is used for sending requests from a ZMQ_REQ
628 client to one or more ZMQ_REP services, and receiving subsequent
629 replies to each request sent.
630 The request-reply pattern is formally defined by
632 http://rfc.zeromq.org/spec:28.
633 ZMQ_REQ
635 A socket of type ZMQ_REQ is used by a client to send requests to
636 and receive replies from a service. This socket type allows only an
637 alternating sequence of zmq_send(request) and subsequent
638 zmq_recv(reply) calls. Each request sent is round-robined among all
639 services, and each reply received is matched with the last issued
640 request.
641 For connection-oriented transports, If the ZMQ_IMMEDIATE option is
643 set and there is no service available, then any send operation on
644 the socket shall block until at least one service becomes
645 available. The REQ socket shall not discard messages.
646 Table 14. Summary of ZMQ_REQ characteristics
648 Compatible peer sockets ZMQ_REP, ZMQ_ROUTER
649 Direction Bidirectional
651 Send/receive pattern Send, Receive, Send,
653 Receive, ...
654 Outgoing routing strategy Round-robin
656 Incoming routing strategy Last peer
658 Action in mute state Block
660 ZMQ_REP
663 A socket of type ZMQ_REP is used by a service to receive requests
664 from and send replies to a client. This socket type allows only an
665 alternating sequence of zmq_recv(request) and subsequent
666 zmq_send(reply) calls. Each request received is fair-queued from
667 among all clients, and each reply sent is routed to the client that
668 issued the last request. If the original requester does not exist
669 any more the reply is silently discarded.
670 Table 15. Summary of ZMQ_REP characteristics
672 Compatible peer sockets ZMQ_REQ, ZMQ_DEALER
673 Direction Bidirectional
675 Send/receive pattern Receive, Send, Receive,
677 Send, ...
678 Incoming routing strategy Fair-queued
680 Outgoing routing strategy Last peer
682 ZMQ_DEALER
685 A socket of type ZMQ_DEALER is an advanced pattern used for
686 extending request/reply sockets. Each message sent is round-robined
687 among all connected peers, and each message received is fair-queued
688 from all connected peers.
689 When a ZMQ_DEALER socket enters the mute state due to having
691 reached the high water mark for all peers, or, for
692 connection-oriented transports, if the ZMQ_IMMEDIATE option is set
693 and there are no peers at all, then any zmq_send(3) operations on
694 the socket shall block until the mute state ends or at least one
695 peer becomes available for sending; messages are not discarded.
696 When a ZMQ_DEALER socket is connected to a ZMQ_REP socket each
698 message sent must consist of an empty message part, the delimiter,
699 followed by one or more body parts.
700 Table 16. Summary of ZMQ_DEALER characteristics
702 Compatible peer sockets ZMQ_ROUTER, ZMQ_REP,
703 ZMQ_DEALER
704 Direction Bidirectional
706 Send/receive pattern Unrestricted
708 Outgoing routing strategy Round-robin
710 Incoming routing strategy Fair-queued
712 Action in mute state Block
714 ZMQ_ROUTER
717 A socket of type ZMQ_ROUTER is an advanced socket type used for
718 extending request/reply sockets. When receiving messages a
719 ZMQ_ROUTER socket shall prepend a message part containing the
720 routing id of the originating peer to the message before passing it
721 to the application. Messages received are fair-queued from among
722 all connected peers. When sending messages a ZMQ_ROUTER socket
723 shall remove the first part of the message and use it to determine
724 the _routing id _ of the peer the message shall be routed to. If
725 the peer does not exist anymore, or has never existed, the message
726 shall be silently discarded. However, if ZMQ_ROUTER_MANDATORY
727 socket option is set to 1, the socket shall fail with EHOSTUNREACH
728 in both cases.
729 When a ZMQ_ROUTER socket enters the mute state due to having
731 reached the high water mark for all peers, then any messages sent
732 to the socket shall be dropped until the mute state ends. Likewise,
733 any messages routed to a peer for which the individual high water
734 mark has been reached shall also be dropped. If,
735 ZMQ_ROUTER_MANDATORY is set to 1, the socket shall block or return
736 EAGAIN in both cases.
737 When a ZMQ_ROUTER socket has ZMQ_ROUTER_MANDATORY flag set to 1,
739 the socket shall generate ZMQ_POLLIN events upon reception of
740 messages from one or more peers. Likewise, the socket shall
741 generate ZMQ_POLLOUT events when at least one message can be sent
742 to one or more peers.
743 When a ZMQ_REQ socket is connected to a ZMQ_ROUTER socket, in
745 addition to the routing id of the originating peer each message
746 received shall contain an empty delimiter message part. Hence, the
747 entire structure of each received message as seen by the
748 application becomes: one or more routing id parts, delimiter part,
749 one or more body parts. When sending replies to a ZMQ_REQ socket
750 the application must include the delimiter part.
751 Table 17. Summary of ZMQ_ROUTER characteristics
753 Compatible peer sockets ZMQ_DEALER, ZMQ_REQ,
754 ZMQ_ROUTER
755 Direction Bidirectional
757 Send/receive pattern Unrestricted
759 Outgoing routing strategy See text
761 Incoming routing strategy Fair-queued
763 Action in mute state Drop (see text)
765
768 The zmq_socket() function shall return an opaque handle to the newly
769 created socket if successful. Otherwise, it shall return NULL and set
770 errno to one of the values defined below.
771
773 EINVAL
774 The requested socket type is invalid.
775 EFAULT
777 The provided context is invalid.
778 EMFILE
780 The limit on the total number of open 0MQ sockets has been reached.
781 ETERM
783 The context specified was shutdown or terminated.
784
786 Creating a simple HTTP server using ZMQ_STREAM.
787 void *ctx = zmq_ctx_new ();
789 assert (ctx);
790 /* Create ZMQ_STREAM socket */
791 void *socket = zmq_socket (ctx, ZMQ_STREAM);
792 assert (socket);
793 int rc = zmq_bind (socket, "tcp://*:8080");
794 assert (rc == 0);
795 /* Data structure to hold the ZMQ_STREAM routing id */
796 uint8_t routing_id [256];
797 size_t routing_id_size = 256;
798 /* Data structure to hold the ZMQ_STREAM received data */
799 uint8_t raw [256];
800 size_t raw_size = 256;
801 while (1) {
802 /* Get HTTP request; routing id frame and then request */
803 routing_id_size = zmq_recv (socket, routing_id, 256, 0);
804 assert (routing_id_size > 0);
805 do {
806 raw_size = zmq_recv (socket, raw, 256, 0);
807 assert (raw_size >= 0);
808 } while (raw_size == 256);
809 /* Prepares the response */
810 char http_response [] =
811 "HTTP/1.0 200 OK\r\n"
812 "Content-Type: text/plain\r\n"
813 "\r\n"
814 "Hello, World!";
815 /* Sends the routing id frame followed by the response */
816 zmq_send (socket, routing_id, routing_id_size, ZMQ_SNDMORE);
817 zmq_send (socket, http_response, strlen (http_response), 0);
818 /* Closes the connection by sending the routing id frame followed by a zero response */
819 zmq_send (socket, routing_id, routing_id_size, ZMQ_SNDMORE);
820 zmq_send (socket, 0, 0, 0);
821 }
822 zmq_close (socket);
823 zmq_ctx_destroy (ctx);
824
827 zmq_init(3) zmq_setsockopt(3) zmq_bind(3) zmq_connect(3) zmq_send(3)
828 zmq_recv(3) zmq_inproc(7) zmq(7)
829
831 This page was written by the 0MQ community. To make a change please
832 read the 0MQ Contribution Policy at
833 http://www.zeromq.org/docs:contributing.
8340MQ 4.3.4 01/21/2023 ZMQ_SOCKET(3)