1ZMQ_SOCKET(3)                     0MQ Manual                     ZMQ_SOCKET(3)
2
3
4

NAME

6       zmq_socket - create 0MQ socket
7

SYNOPSIS

9       void *zmq_socket (void *context, int type);
10

DESCRIPTION

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
17       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
23       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
32       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
37       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
45       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
50       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
54       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
58   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
64       The client-server pattern is formally defined by
65       http://rfc.zeromq.org/spec:41.
66
67           Note
68           Server-client is still in draft phase.
69
70       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
75           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
83           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
89           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
95               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
101           Table 1. Summary of ZMQ_CLIENT characteristics
102           Compatible peer sockets     ZMQ_SERVER
103
104           Direction                   Bidirectional
105
106           Send/receive pattern        Unrestricted
107
108           Outgoing routing strategy   Round-robin
109
110           Incoming routing strategy   Fair-queued
111
112           Action in mute state        Block
113
114
115       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
120           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
126           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
133               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
139           Table 2. Summary of ZMQ_SERVER characteristics
140           Compatible peer sockets     ZMQ_CLIENT
141
142           Direction                   Bidirectional
143
144           Send/receive pattern        Unrestricted
145
146           Outgoing routing strategy   See text
147
148           Incoming routing strategy   Fair-queued
149
150           Action in mute state        Return EAGAIN
151
152
153   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
157       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
160       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
164       Groups are matched using exact matching (vs prefix matching of PubSub).
165
166           Note
167           Radio-dish is still in draft phase.
168
169       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
176           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
182               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
187           Table 3. Summary of ZMQ_RADIO characteristics
188           Compatible peer sockets     ZMQ_DISH
189
190           Direction                   Unidirectional
191
192           Send/receive pattern        Send only
193
194           Incoming routing strategy   N/A
195
196           Outgoing routing strategy   Fan out
197
198
199
200           Action in mute state        Drop
201
202
203       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
210               Note
211               ZMQ_DISH sockets are threadsafe. They do not accept ZMQ_RCVMORE
212               on receives. This limits them to single part data.
213
214           Table 4. Summary of ZMQ_DISH characteristics
215           Compatible peer sockets     ZMQ_RADIO
216
217           Direction                   Unidirectional
218
219           Send/receive pattern        Receive only
220
221           Incoming routing strategy   Fair-queued
222
223           Outgoing routing strategy   N/A
224
225
226   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
231       The publish-subscribe pattern is formally defined by
232       http://rfc.zeromq.org/spec:29.
233
234       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
240           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
246           Table 5. Summary of ZMQ_PUB characteristics
247           Compatible peer sockets     ZMQ_SUB, ZMQ_XSUB
248
249           Direction                   Unidirectional
250
251           Send/receive pattern        Send only
252
253           Incoming routing strategy   N/A
254
255           Outgoing routing strategy   Fan out
256
257           Action in mute state        Drop
258
259
260       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
267           Table 6. Summary of ZMQ_SUB characteristics
268           Compatible peer sockets     ZMQ_PUB, ZMQ_XPUB
269
270           Direction                   Unidirectional
271
272           Send/receive pattern        Receive only
273
274           Incoming routing strategy   Fair-queued
275
276           Outgoing routing strategy   N/A
277
278
279       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
286           Table 7. Summary of ZMQ_XPUB characteristics
287           Compatible peer sockets     ZMQ_SUB, ZMQ_XSUB
288
289           Direction                   Unidirectional
290
291           Send/receive pattern        Send messages, receive
292                                       subscriptions
293
294           Incoming routing strategy   N/A
295
296           Outgoing routing strategy   Fan out
297
298           Action in mute state        Drop
299
300
301       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
308           Table 8. Summary of ZMQ_XSUB characteristics
309           Compatible peer sockets     ZMQ_PUB, ZMQ_XPUB
310
311           Direction                   Unidirectional
312
313           Send/receive pattern        Receive messages, send
314                                       subscriptions
315
316           Incoming routing strategy   Fair-queued
317
318           Outgoing routing strategy   N/A
319
320           Action in mute state        Drop
321
322
323   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
330       The pipeline pattern is formally defined by
331       http://rfc.zeromq.org/spec:30.
332
333       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
339           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
347           Table 9. Summary of ZMQ_PUSH characteristics
348           Compatible peer sockets     ZMQ_PULL
349
350           Direction                   Unidirectional
351
352           Send/receive pattern        Send only
353
354           Incoming routing strategy   N/A
355
356           Outgoing routing strategy   Round-robin
357
358           Action in mute state        Block
359
360
361       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
367           Table 10. Summary of ZMQ_PULL characteristics
368           Compatible peer sockets     ZMQ_PUSH
369
370           Direction                   Unidirectional
371
372           Send/receive pattern        Receive only
373
374           Incoming routing strategy   Fair-queued
375
376           Outgoing routing strategy   N/A
377
378           Action in mute state        Block
379
380
381           Scatter-gather pattern
382
383               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
389               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
396               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
403               NOTE: 'ZMQ_SCATTER' sockets are threadsafe. They do not accept ZMQ_RCVMORE on receives.
404               This limits them to single part data.
405
406               [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
415
416               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
423               NOTE: 'ZMQ_GATHER' sockets are threadsafe. They do not accept ZMQ_RCVMORE on receives.
424               This limits them to single part data.
425
426               [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
435
436               Exclusive pair pattern
437
438           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
442           The exclusive pair pattern is formally defined by
443           http://rfc.zeromq.org/spec:31.
444
445       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
450           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
457           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
463               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
468           Table 11. Summary of ZMQ_PAIR characteristics
469           Compatible peer sockets     ZMQ_PAIR
470
471           Direction                   Bidirectional
472
473           Send/receive pattern        Unrestricted
474
475           Incoming routing strategy   N/A
476
477           Outgoing routing strategy   N/A
478
479           Action in mute state        Block
480
481
482   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
489           Note
490           Peer-to-peer is still in draft phase.
491
492       ZMQ_PEER
493           A ZMQ_PEER socket talks to a set of ZMQ_PEER sockets.
494
495           To connect and fetch the routing_id of the peer use
496           zmq_connect_peer(3).
497
498           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
501           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
505           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
512               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
517           Table 12. Summary of ZMQ_PEER characteristics
518           Compatible peer sockets     ZMQ_PEER
519
520           Direction                   Bidirectional
521
522           Send/receive pattern        Unrestricted
523
524           Outgoing routing strategy   See text
525
526           Incoming routing strategy   Fair-queued
527
528
529
530           Action in mute state        Return EAGAIN
531
532
533           Channel pattern
534
535               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
540               NOTE: Channel is still in draft phase.
541
542               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
548               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
554               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
559               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
563               NOTE: 'ZMQ_CHANNEL' sockets are threadsafe. They do not accept ZMQ_RCVMORE on receives.
564               This limits them to single part data.
565
566               [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
575               Native Pattern
576
577           The native pattern is used for communicating with TCP peers and
578           allows asynchronous requests and replies in either direction.
579
580       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
586           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
591           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
596           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
600           To close a specific connection, send the routing id frame followed
601           by a zero-length message (see EXAMPLE section).
602
603           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
608           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
612           Table 13. Summary of ZMQ_STREAM characteristics
613           Compatible peer sockets     none.
614
615           Direction                   Bidirectional
616
617           Send/receive pattern        Unrestricted
618
619           Outgoing routing strategy   See text
620
621           Incoming routing strategy   Fair-queued
622
623           Action in mute state        EAGAIN
624
625
626   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
631       The request-reply pattern is formally defined by
632       http://rfc.zeromq.org/spec:28.
633
634       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
642           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
647           Table 14. Summary of ZMQ_REQ characteristics
648           Compatible peer sockets     ZMQ_REP, ZMQ_ROUTER
649
650           Direction                   Bidirectional
651
652           Send/receive pattern        Send, Receive, Send,
653                                       Receive, ...
654
655           Outgoing routing strategy   Round-robin
656
657           Incoming routing strategy   Last peer
658
659           Action in mute state        Block
660
661
662       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
671           Table 15. Summary of ZMQ_REP characteristics
672           Compatible peer sockets     ZMQ_REQ, ZMQ_DEALER
673
674           Direction                   Bidirectional
675
676           Send/receive pattern        Receive, Send, Receive,
677                                       Send, ...
678
679           Incoming routing strategy   Fair-queued
680
681           Outgoing routing strategy   Last peer
682
683
684       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
690           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
697           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
701           Table 16. Summary of ZMQ_DEALER characteristics
702           Compatible peer sockets     ZMQ_ROUTER, ZMQ_REP,
703                                       ZMQ_DEALER
704
705           Direction                   Bidirectional
706
707           Send/receive pattern        Unrestricted
708
709           Outgoing routing strategy   Round-robin
710
711           Incoming routing strategy   Fair-queued
712
713           Action in mute state        Block
714
715
716       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
730           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
738           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
744           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
752           Table 17. Summary of ZMQ_ROUTER characteristics
753           Compatible peer sockets     ZMQ_DEALER, ZMQ_REQ,
754                                       ZMQ_ROUTER
755
756           Direction                   Bidirectional
757
758           Send/receive pattern        Unrestricted
759
760           Outgoing routing strategy   See text
761
762           Incoming routing strategy   Fair-queued
763
764           Action in mute state        Drop (see text)
765
766

RETURN VALUE

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

ERRORS

773       EINVAL
774           The requested socket type is invalid.
775
776       EFAULT
777           The provided context is invalid.
778
779       EMFILE
780           The limit on the total number of open 0MQ sockets has been reached.
781
782       ETERM
783           The context specified was shutdown or terminated.
784

EXAMPLE

786       Creating a simple HTTP server using ZMQ_STREAM.
787
788           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
825

SEE ALSO

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

AUTHORS

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.
834
835
836
8370MQ 4.3.4                         01/21/2023                     ZMQ_SOCKET(3)
Impressum