3
3
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
5
5
<meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" />
6
<meta name="generator" content="AsciiDoc 8.6.3" />
6
<meta name="generator" content="AsciiDoc 8.6.4" />
7
7
<title>zmq_socket(3)</title>
8
8
<style type="text/css">
9
9
/* Sans-serif font. */
394
394
font-size: 0.9em;
397
span.aqua { color: aqua; }
398
span.black { color: black; }
399
span.blue { color: blue; }
400
span.fuchsia { color: fuchsia; }
401
span.gray { color: gray; }
402
span.green { color: green; }
403
span.lime { color: lime; }
404
span.maroon { color: maroon; }
405
span.navy { color: navy; }
406
span.olive { color: olive; }
407
span.purple { color: purple; }
408
span.red { color: red; }
409
span.silver { color: silver; }
410
span.teal { color: teal; }
411
span.white { color: white; }
412
span.yellow { color: yellow; }
414
span.aqua-background { background: aqua; }
415
span.black-background { background: black; }
416
span.blue-background { background: blue; }
417
span.fuchsia-background { background: fuchsia; }
418
span.gray-background { background: gray; }
419
span.green-background { background: green; }
420
span.lime-background { background: lime; }
421
span.maroon-background { background: maroon; }
422
span.navy-background { background: navy; }
423
span.olive-background { background: olive; }
424
span.purple-background { background: purple; }
425
span.red-background { background: red; }
426
span.silver-background { background: silver; }
427
span.teal-background { background: teal; }
428
span.white-background { background: white; }
429
span.yellow-background { background: yellow; }
431
span.big { font-size: 2em; }
432
span.small { font-size: 0.6em; }
397
433
/* Overrides for manpage documents */
399
435
padding-top: 0.5em;
598
634
<div class="paragraph"><div class="title">Thread safety</div><p>ØMQ <em>sockets</em> are <em>not</em> thread safe. Applications MUST NOT use a socket
599
635
from multiple threads except after migrating a socket from one thread to
600
636
another with a "full fence" memory barrier.</p></div>
601
<div class="paragraph"><div class="title">Socket types</div><p>ØMQ defines several messaging patterns which encapsulate exact semantics of
602
a particular topology. For example, publush-subscribe pattern defines data
603
distribution trees while request-reply defines networks of shared stateless
604
services. Each pattern defines several socket types (roles in the pattern).</p></div>
605
<div class="paragraph"><p>The following sections present the socket types defined by ØMQ:</p></div>
637
<div class="paragraph"><div class="title">Socket types</div><p>The following sections present the socket types defined by ØMQ, grouped by the
638
general <em>messaging pattern</em> which is built from related socket types.</p></div>
606
639
<div class="sect2">
607
640
<h3 id="_request_reply_pattern">Request-reply pattern</h3>
608
641
<div class="paragraph"><p>The request-reply pattern is used for sending requests from a <em>client</em> to one
609
or more instances of a stateless <em>service</em>, and receiving subsequent replies
610
to each request sent.</p></div>
642
or more instances of a <em>service</em>, and receiving subsequent replies to each
643
request sent.</p></div>
611
644
<div class="sect3">
612
645
<h4 id="_zmq_req">ZMQ_REQ</h4>
613
646
<div class="paragraph"><p>A socket of type <em>ZMQ_REQ</em> is used by a <em>client</em> to send requests to and
614
647
receive replies from a <em>service</em>. This socket type allows only an alternating
615
648
sequence of <em>zmq_send(request)</em> and subsequent <em>zmq_recv(reply)</em> calls. Each
616
request sent is load-balanced among all <em>services</em>, and each reply received is
649
request sent is round-robined among all <em>services</em>, and each reply received is
617
650
matched with the last issued request.</p></div>
618
651
<div class="paragraph"><p>When a <em>ZMQ_REQ</em> socket enters an exceptional state due to having reached the
619
652
high water mark for all <em>services</em>, or if there are no <em>services</em> at all, then
750
805
<div class="sect3">
751
<h4 id="_zmq_xreq">ZMQ_XREQ</h4>
752
<div class="paragraph"><p>A socket of type <em>ZMQ_XREQ</em> is a socket type underlying <em>ZMQ_REQ</em>. It doesn’t
753
impose the strict order of sends and recvs as <em>ZMQ_REQ</em> does and it is
754
intended for use in intermediate devices in request-reply topologies.</p></div>
755
<div class="paragraph"><p>Each message sent is load-balanced among all connected
806
<h4 id="_zmq_dealer">ZMQ_DEALER</h4>
807
<div class="paragraph"><p>A socket of type <em>ZMQ_DEALER</em> is an advanced pattern used for extending
808
request/reply sockets. Each message sent is round-robined among all connected
756
809
peers, and each message received is fair-queued from all connected peers.</p></div>
757
<div class="paragraph"><p>When a <em>ZMQ_XREQ</em> socket enters an exceptional state due to having reached the
810
<div class="paragraph"><p>When a <em>ZMQ_DEALER</em> socket enters an exceptional state due to having reached the
758
811
high water mark for all peers, or if there are no peers at all, then any
759
812
<a href="zmq_send.html">zmq_send(3)</a> operations on the socket shall block until the exceptional
760
813
state ends or at least one peer becomes available for sending; messages are not
761
814
discarded.</p></div>
762
<div class="hdlist"><div class="title">Summary of ZMQ_XREQ characteristics</div><table>
815
<div class="paragraph"><p>When a <em>ZMQ_DEALER</em> socket is connected to a <em>ZMQ_REP</em> socket each message sent
816
must consist of an empty message part, the <em>delimiter</em>, followed by one or more
817
<em>body parts</em>.</p></div>
818
<div class="paragraph"><p>Deprecated alias: <em>ZMQ_XREQ</em>.</p></div>
819
<div class="hdlist"><div class="title">Summary of ZMQ_DEALER characteristics</div><table>
764
821
<td class="hdlist1">
765
822
Compatible peer sockets
820
888
<div class="sect3">
821
<h4 id="_zmq_xrep">ZMQ_XREP</h4>
822
<div class="paragraph"><p>A socket of type <em>ZMQ_XREP</em> is a socket type underlying <em>ZMQ_REP</em>. It doesn’t
823
impose the strict order of sends and recvs as <em>ZMQ_REQ</em> does and it is
824
intended for use in intermediate devices in request-reply topologies.</p></div>
825
<div class="paragraph"><p>Messages received are fair-queued from among all connected peers. The outbound
826
messages are routed to a specific peer, as explained below.</p></div>
827
<div class="paragraph"><p>When a <em>ZMQ_XREP</em> socket enters an exceptional state due to having reached the
889
<h4 id="_zmq_router">ZMQ_ROUTER</h4>
890
<div class="paragraph"><p>A socket of type <em>ZMQ_ROUTER</em> is an advanced socket type used for extending
891
request/reply sockets. When receiving messages a <em>ZMQ_ROUTER</em> socket shall
892
prepend a message part containing the <em>identity</em> of the originating peer to the
893
message before passing it to the application. Messages received are fair-queued
894
from among all connected peers. When sending messages a <em>ZMQ_ROUTER</em> socket shall
895
remove the first part of the message and use it to determine the <em>identity</em> of
896
the peer the message shall be routed to. If the peer does not exist anymore
897
the message shall be silently discarded.</p></div>
898
<div class="paragraph"><p>When a <em>ZMQ_ROUTER</em> socket enters an exceptional state due to having reached the
828
899
high water mark for all peers, or if there are no peers at all, then any
829
900
messages sent to the socket shall be dropped until the exceptional state ends.
830
Likewise, any messages to be routed to a non-existent peer or a peer for which
831
the individual high water mark has been reached shall also be dropped.</p></div>
832
<div class="hdlist"><div class="title">Summary of ZMQ_XREP characteristics</div><table>
901
Likewise, any messages routed to a non-existent peer or a peer for which the
902
individual high water mark has been reached shall also be dropped.</p></div>
903
<div class="paragraph"><p>When a <em>ZMQ_REQ</em> socket is connected to a <em>ZMQ_ROUTER</em> socket, in addition to the
904
<em>identity</em> of the originating peer each message received shall contain an empty
905
<em>delimiter</em> message part. Hence, the entire structure of each received message
906
as seen by the application becomes: one or more <em>identity</em> parts, <em>delimiter</em>
907
part, one or more <em>body parts</em>. When sending replies to a <em>ZMQ_REQ</em> socket the
908
application must include the <em>delimiter</em> part.</p></div>
909
<div class="paragraph"><p>Deprecated alias: <em>ZMQ_XREP</em>.</p></div>
910
<div class="hdlist"><div class="title">Summary of ZMQ_ROUTER characteristics</div><table>
834
912
<td class="hdlist1">
835
913
Compatible peer sockets
1157
1290
<div class="paragraph"><p>The pipeline pattern is used for distributing data to <em>nodes</em> arranged in
1158
1291
a pipeline. Data always flows down the pipeline, and each stage of the pipeline
1159
1292
is connected to at least one <em>node</em>. When a pipeline stage is connected to
1160
multiple <em>nodes</em> data is load-balanced among all connected <em>nodes</em>.</p></div>
1293
multiple <em>nodes</em> data is round-robined among all connected <em>nodes</em>.</p></div>
1161
1294
<div class="sect3">
1162
1295
<h4 id="_zmq_push">ZMQ_PUSH</h4>
1163
1296
<div class="paragraph"><p>A socket of type <em>ZMQ_PUSH</em> is used by a pipeline <em>node</em> to send messages
1164
to downstream pipeline <em>nodes</em>. Messages are load-balanced to all connected
1297
to downstream pipeline <em>nodes</em>. Messages are round-robined to all connected
1165
1298
downstream <em>nodes</em>. The <em>zmq_recv()</em> function is not implemented for this
1166
1299
socket type.</p></div>
1167
1300
<div class="paragraph"><p>When a <em>ZMQ_PUSH</em> socket enters an exceptional state due to having reached the
1317
1450
<div class="sect2">
1318
1451
<h3 id="_exclusive_pair_pattern">Exclusive pair pattern</h3>
1319
<div class="paragraph"><p>The exclusive pair is an advanced pattern used for communicating exclusively
1320
between two peers.</p></div>
1452
<div class="paragraph"><p>The exclusive pair pattern is used to connect a peer to precisely one other
1453
peer. This pattern is used for inter-thread communication across the inproc
1454
transport.</p></div>
1321
1455
<div class="sect3">
1322
1456
<h4 id="_zmq_pair">ZMQ_PAIR</h4>
1323
1457
<div class="paragraph"><p>A socket of type <em>ZMQ_PAIR</em> can only be connected to a single peer at any one
1332
1466
<td class="icon">
1333
1467
<div class="title">Note</div>
1335
<td class="content"><em>ZMQ_PAIR</em> sockets are experimental, and are currently missing several
1336
features such as auto-reconnection.</td>
1469
<td class="content"><em>ZMQ_PAIR</em> sockets are designed for inter-thread communication across
1470
the <a href="zmq_inproc.html">zmq_inproc(7)</a> transport and do not implement functionality such
1471
as auto-reconnection. <em>ZMQ_PAIR</em> sockets are considered experimental and may
1472
have other missing or broken aspects.</td>
1339
1475
<div class="hdlist"><div class="title">Summary of ZMQ_PAIR characteristics</div><table>
1464
1600
<a href="zmq_connect.html">zmq_connect(3)</a>
1465
1601
<a href="zmq_send.html">zmq_send(3)</a>
1466
1602
<a href="zmq_recv.html">zmq_recv(3)</a>
1603
<a href="zmq_inproc.html">zmq_inproc(7)</a>
1467
1604
<a href="zmq.html">zmq(7)</a></p></div>
1470
1607
<div class="sect1">
1471
1608
<h2 id="_authors">AUTHORS</h2>
1472
1609
<div class="sectionbody">
1473
<div class="paragraph"><p>The ØMQ documentation was written by Martin Sustrik <<a href="mailto:sustrik@250bpm.com">sustrik@250bpm.com</a>> and
1474
Martin Lucina <<a href="mailto:martin@lucina.net">martin@lucina.net</a>>.</p></div>
1610
<div class="paragraph"><p>This ØMQ manual page was written by Martin Sustrik <<a href="mailto:sustrik@250bpm.com">sustrik@250bpm.com</a>>,
1611
Martin Lucina <<a href="mailto:mato@kotelna.sk">mato@kotelna.sk</a>>, and Pieter Hintjens <<a href="mailto:ph@imatix.com">ph@imatix.com</a>>.</p></div>
1478
1615
<div id="footnotes"><hr /></div>
1479
1616
<div id="footer">
1480
1617
<div id="footer-text">
1482
Last updated 2011-12-18 11:17:56 CET
1619
Last updated 2012-06-05 09:39:30 CEST
added
removed
doc/zmq_socket.html
