<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" />
<meta name="generator" content="AsciiDoc 8.6.9" />
<title>zmq_socket(3)</title>
<style type="text/css">
/* Shared CSS for AsciiDoc xhtml11 and html5 backends */
/* Default font. */
body {
font-family: Georgia,serif;
}
/* Title font. */
h1, h2, h3, h4, h5, h6,
div.title, caption.title,
thead, p.table.header,
#toctitle,
#author, #revnumber, #revdate, #revremark,
#footer {
font-family: Arial,Helvetica,sans-serif;
}
body {
margin: 1em 5% 1em 5%;
}
a {
color: blue;
text-decoration: underline;
}
a:visited {
color: fuchsia;
}
em {
font-style: italic;
color: navy;
}
strong {
font-weight: bold;
color: #083194;
}
h1, h2, h3, h4, h5, h6 {
color: #527bbd;
margin-top: 1.2em;
margin-bottom: 0.5em;
line-height: 1.3;
}
h1, h2, h3 {
border-bottom: 2px solid silver;
}
h2 {
padding-top: 0.5em;
}
h3 {
float: left;
}
h3 + * {
clear: left;
}
h5 {
font-size: 1.0em;
}
div.sectionbody {
margin-left: 0;
}
hr {
border: 1px solid silver;
}
p {
margin-top: 0.5em;
margin-bottom: 0.5em;
}
ul, ol, li > p {
margin-top: 0;
}
ul > li { color: #aaa; }
ul > li > * { color: black; }
.monospaced, code, pre {
font-family: "Courier New", Courier, monospace;
font-size: inherit;
color: navy;
padding: 0;
margin: 0;
}
pre {
white-space: pre-wrap;
}
#author {
color: #527bbd;
font-weight: bold;
font-size: 1.1em;
}
#email {
}
#revnumber, #revdate, #revremark {
}
#footer {
font-size: small;
border-top: 2px solid silver;
padding-top: 0.5em;
margin-top: 4.0em;
}
#footer-text {
float: left;
padding-bottom: 0.5em;
}
#footer-badges {
float: right;
padding-bottom: 0.5em;
}
#preamble {
margin-top: 1.5em;
margin-bottom: 1.5em;
}
div.imageblock, div.exampleblock, div.verseblock,
div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
div.admonitionblock {
margin-top: 1.0em;
margin-bottom: 1.5em;
}
div.admonitionblock {
margin-top: 2.0em;
margin-bottom: 2.0em;
margin-right: 10%;
color: #606060;
}
div.content { /* Block element content. */
padding: 0;
}
/* Block element titles. */
div.title, caption.title {
color: #527bbd;
font-weight: bold;
text-align: left;
margin-top: 1.0em;
margin-bottom: 0.5em;
}
div.title + * {
margin-top: 0;
}
td div.title:first-child {
margin-top: 0.0em;
}
div.content div.title:first-child {
margin-top: 0.0em;
}
div.content + div.title {
margin-top: 0.0em;
}
div.sidebarblock > div.content {
background: #ffffee;
border: 1px solid #dddddd;
border-left: 4px solid #f0f0f0;
padding: 0.5em;
}
div.listingblock > div.content {
border: 1px solid #dddddd;
border-left: 5px solid #f0f0f0;
background: #f8f8f8;
padding: 0.5em;
}
div.quoteblock, div.verseblock {
padding-left: 1.0em;
margin-left: 1.0em;
margin-right: 10%;
border-left: 5px solid #f0f0f0;
color: #888;
}
div.quoteblock > div.attribution {
padding-top: 0.5em;
text-align: right;
}
div.verseblock > pre.content {
font-family: inherit;
font-size: inherit;
}
div.verseblock > div.attribution {
padding-top: 0.75em;
text-align: left;
}
/* DEPRECATED: Pre version 8.2.7 verse style literal block. */
div.verseblock + div.attribution {
text-align: left;
}
div.admonitionblock .icon {
vertical-align: top;
font-size: 1.1em;
font-weight: bold;
text-decoration: underline;
color: #527bbd;
padding-right: 0.5em;
}
div.admonitionblock td.content {
padding-left: 0.5em;
border-left: 3px solid #dddddd;
}
div.exampleblock > div.content {
border-left: 3px solid #dddddd;
padding-left: 0.5em;
}
div.imageblock div.content { padding-left: 0; }
span.image img { border-style: none; vertical-align: text-bottom; }
a.image:visited { color: white; }
dl {
margin-top: 0.8em;
margin-bottom: 0.8em;
}
dt {
margin-top: 0.5em;
margin-bottom: 0;
font-style: normal;
color: navy;
}
dd > *:first-child {
margin-top: 0.1em;
}
ul, ol {
list-style-position: outside;
}
ol.arabic {
list-style-type: decimal;
}
ol.loweralpha {
list-style-type: lower-alpha;
}
ol.upperalpha {
list-style-type: upper-alpha;
}
ol.lowerroman {
list-style-type: lower-roman;
}
ol.upperroman {
list-style-type: upper-roman;
}
div.compact ul, div.compact ol,
div.compact p, div.compact p,
div.compact div, div.compact div {
margin-top: 0.1em;
margin-bottom: 0.1em;
}
tfoot {
font-weight: bold;
}
td > div.verse {
white-space: pre;
}
div.hdlist {
margin-top: 0.8em;
margin-bottom: 0.8em;
}
div.hdlist tr {
padding-bottom: 15px;
}
dt.hdlist1.strong, td.hdlist1.strong {
font-weight: bold;
}
td.hdlist1 {
vertical-align: top;
font-style: normal;
padding-right: 0.8em;
color: navy;
}
td.hdlist2 {
vertical-align: top;
}
div.hdlist.compact tr {
margin: 0;
padding-bottom: 0;
}
.comment {
background: yellow;
}
.footnote, .footnoteref {
font-size: 0.8em;
}
span.footnote, span.footnoteref {
vertical-align: super;
}
#footnotes {
margin: 20px 0 20px 0;
padding: 7px 0 0 0;
}
#footnotes div.footnote {
margin: 0 0 5px 0;
}
#footnotes hr {
border: none;
border-top: 1px solid silver;
height: 1px;
text-align: left;
margin-left: 0;
width: 20%;
min-width: 100px;
}
div.colist td {
padding-right: 0.5em;
padding-bottom: 0.3em;
vertical-align: top;
}
div.colist td img {
margin-top: 0.3em;
}
@media print {
#footer-badges { display: none; }
}
#toc {
margin-bottom: 2.5em;
}
#toctitle {
color: #527bbd;
font-size: 1.1em;
font-weight: bold;
margin-top: 1.0em;
margin-bottom: 0.1em;
}
div.toclevel0, div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
margin-top: 0;
margin-bottom: 0;
}
div.toclevel2 {
margin-left: 2em;
font-size: 0.9em;
}
div.toclevel3 {
margin-left: 4em;
font-size: 0.9em;
}
div.toclevel4 {
margin-left: 6em;
font-size: 0.9em;
}
span.aqua { color: aqua; }
span.black { color: black; }
span.blue { color: blue; }
span.fuchsia { color: fuchsia; }
span.gray { color: gray; }
span.green { color: green; }
span.lime { color: lime; }
span.maroon { color: maroon; }
span.navy { color: navy; }
span.olive { color: olive; }
span.purple { color: purple; }
span.red { color: red; }
span.silver { color: silver; }
span.teal { color: teal; }
span.white { color: white; }
span.yellow { color: yellow; }
span.aqua-background { background: aqua; }
span.black-background { background: black; }
span.blue-background { background: blue; }
span.fuchsia-background { background: fuchsia; }
span.gray-background { background: gray; }
span.green-background { background: green; }
span.lime-background { background: lime; }
span.maroon-background { background: maroon; }
span.navy-background { background: navy; }
span.olive-background { background: olive; }
span.purple-background { background: purple; }
span.red-background { background: red; }
span.silver-background { background: silver; }
span.teal-background { background: teal; }
span.white-background { background: white; }
span.yellow-background { background: yellow; }
span.big { font-size: 2em; }
span.small { font-size: 0.6em; }
span.underline { text-decoration: underline; }
span.overline { text-decoration: overline; }
span.line-through { text-decoration: line-through; }
div.unbreakable { page-break-inside: avoid; }
/*
* xhtml11 specific
*
* */
div.tableblock {
margin-top: 1.0em;
margin-bottom: 1.5em;
}
div.tableblock > table {
border: 3px solid #527bbd;
}
thead, p.table.header {
font-weight: bold;
color: #527bbd;
}
p.table {
margin-top: 0;
}
/* Because the table frame attribute is overriden by CSS in most browsers. */
div.tableblock > table[frame="void"] {
border-style: none;
}
div.tableblock > table[frame="hsides"] {
border-left-style: none;
border-right-style: none;
}
div.tableblock > table[frame="vsides"] {
border-top-style: none;
border-bottom-style: none;
}
/*
* html5 specific
*
* */
table.tableblock {
margin-top: 1.0em;
margin-bottom: 1.5em;
}
thead, p.tableblock.header {
font-weight: bold;
color: #527bbd;
}
p.tableblock {
margin-top: 0;
}
table.tableblock {
border-width: 3px;
border-spacing: 0px;
border-style: solid;
border-color: #527bbd;
border-collapse: collapse;
}
th.tableblock, td.tableblock {
border-width: 1px;
padding: 4px;
border-style: solid;
border-color: #527bbd;
}
table.tableblock.frame-topbot {
border-left-style: hidden;
border-right-style: hidden;
}
table.tableblock.frame-sides {
border-top-style: hidden;
border-bottom-style: hidden;
}
table.tableblock.frame-none {
border-style: hidden;
}
th.tableblock.halign-left, td.tableblock.halign-left {
text-align: left;
}
th.tableblock.halign-center, td.tableblock.halign-center {
text-align: center;
}
th.tableblock.halign-right, td.tableblock.halign-right {
text-align: right;
}
th.tableblock.valign-top, td.tableblock.valign-top {
vertical-align: top;
}
th.tableblock.valign-middle, td.tableblock.valign-middle {
vertical-align: middle;
}
th.tableblock.valign-bottom, td.tableblock.valign-bottom {
vertical-align: bottom;
}
/*
* manpage specific
*
* */
body.manpage h1 {
padding-top: 0.5em;
padding-bottom: 0.5em;
border-top: 2px solid silver;
border-bottom: 2px solid silver;
}
body.manpage h2 {
border-style: none;
}
body.manpage div.sectionbody {
margin-left: 3em;
}
@media print {
body.manpage div#toc { display: none; }
}
</style>
<script type="text/javascript">
/*<+'])');
// Function that scans the DOM tree for header elements (the DOM2
// nodeIterator API would be a better technique but not supported by all
// browsers).
var iterate = function (el) {
for (var i = el.firstChild; i != null; i = i.nextSibling) {
if (i.nodeType == 1 /* Node.ELEMENT_NODE */) {
var mo = re.exec(i.tagName);
if (mo && (i.getAttribute("class") || i.getAttribute("className")) != "float") {
result[result.length] = new TocEntry(i, getText(i), mo[1]-1);
}
iterate(i);
}
}
}
iterate(el);
return result;
}
var toc = document.getElementById("toc");
if (!toc) {
return;
}
// Delete existing TOC entries in case we're reloading the TOC.
var tocEntriesToRemove = [];
var i;
for (i = 0; i < toc.childNodes.length; i++) {
var entry = toc.childNodes[i];
if (entry.nodeName.toLowerCase() == 'div'
&& entry.getAttribute("class")
&& entry.getAttribute("class").match(/^toclevel/))
tocEntriesToRemove.push(entry);
}
for (i = 0; i < tocEntriesToRemove.length; i++) {
toc.removeChild(tocEntriesToRemove[i]);
}
// Rebuild TOC entries.
var entries = tocEntries(document.getElementById("content"), toclevels);
for (var i = 0; i < entries.length; ++i) {
var entry = entries[i];
if (entry.element.id == "")
entry.element.id = "_toc_" + i;
var a = document.createElement("a");
a.href = "#" + entry.element.id;
a.appendChild(document.createTextNode(entry.text));
var div = document.createElement("div");
div.appendChild(a);
div.className = "toclevel" + entry.toclevel;
toc.appendChild(div);
}
if (entries.length == 0)
toc.parentNode.removeChild(toc);
},
/////////////////////////////////////////////////////////////////////
// Footnotes generator
/////////////////////////////////////////////////////////////////////
/* Based on footnote generation code from:
* http://www.brandspankingnew.net/archive/2005/07/format_footnote.html
*/
footnotes: function () {
// Delete existing footnote entries in case we're reloading the footnodes.
var i;
var noteholder = document.getElementById("footnotes");
if (!noteholder) {
return;
}
var entriesToRemove = [];
for (i = 0; i < noteholder.childNodes.length; i++) {
var entry = noteholder.childNodes[i];
if (entry.nodeName.toLowerCase() == 'div' && entry.getAttribute("class") == "footnote")
entriesToRemove.push(entry);
}
for (i = 0; i < entriesToRemove.length; i++) {
noteholder.removeChild(entriesToRemove[i]);
}
// Rebuild footnote entries.
var cont = document.getElementById("content");
var spans = cont.getElementsByTagName("span");
var refs = {};
var n = 0;
for (i=0; i<spans.length; i++) {
if (spans[i].className == "footnote") {
n++;
var note = spans[i].getAttribute("data-note");
if (!note) {
// Use [\s\S] in place of . so multi-line matches work.
// Because JavaScript has no s (dotall) regex flag.
note = spans[i].innerHTML.match(/\s*\[([\s\S]*)]\s*/)[1];
spans[i].innerHTML =
"[<a id='_footnoteref_" + n + "' href='#_footnote_" + n +
"' title='View footnote' class='footnote'>" + n + "</a>]";
spans[i].setAttribute("data-note", note);
}
noteholder.innerHTML +=
"<div class='footnote' id='_footnote_" + n + "'>" +
"<a href='#_footnoteref_" + n + "' title='Return to text'>" +
n + "</a>. " + note + "</div>";
var id =spans[i].getAttribute("id");
if (id != null) refs["#"+id] = n;
}
}
if (n == 0)
noteholder.parentNode.removeChild(noteholder);
else {
// Process footnoterefs.
for (i=0; i<spans.length; i++) {
if (spans[i].className == "footnoteref") {
var href = spans[i].getElementsByTagName("a")[0].getAttribute("href");
href = href.match(/#.*/)[0]; // Because IE return full URL.
n = refs[href];
spans[i].innerHTML =
"[<a href='#_footnote_" + n +
"' title='View footnote' class='footnote'>" + n + "</a>]";
}
}
}
},
install: function(toclevels) {
var timerId;
function reinstall() {
asciidoc.footnotes();
if (toclevels) {
asciidoc.toc(toclevels);
}
}
function reinstallAndRemoveTimer() {
clearInterval(timerId);
reinstall();
}
timerId = setInterval(reinstall, 500);
if (document.addEventListener)
document.addEventListener("DOMContentLoaded", reinstallAndRemoveTimer, false);
else
window.onload = reinstallAndRemoveTimer;
}
}
asciidoc.install();
/*]]>*/
</script>
</head>
<body class="manpage">
<div id="header">
<h1>
zmq_socket(3) Manual Page
</h1>
<h2>NAME</h2>
<div class="sectionbody">
<p>zmq_socket -
create 0MQ socket
</p>
</div>
</div>
<div id="content">
<div class="sect1">
<h2 id="_synopsis">SYNOPSIS</h2>
<div class="sectionbody">
<div class="paragraph"><p><strong>void *zmq_socket (void <em>*context</em>, int <em>type</em>);</strong></p></div>
</div>
</div>
<div class="sect1">
<h2 id="_description">DESCRIPTION</h2>
<div class="sectionbody">
<div class="paragraph"><p>The <em>zmq_socket()</em> function shall create a ØMQ socket within the specified
<em>context</em> and return an opaque handle to the newly created socket. The <em>type</em>
argument specifies the socket type, which determines the semantics of
communication over the socket.</p></div>
<div class="paragraph"><p>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 <a href="zmq_connect.html">zmq_connect(3)</a>, or at least one
endpoint must be created for accepting incoming connections with
<a href="zmq_bind.html">zmq_bind(3)</a>.</p></div>
<div class="paragraph"><div class="title">Key differences to conventional sockets</div><p>Generally speaking, conventional sockets present a <em>synchronous</em> 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 <em>message queue</em>, 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 <em>messages</em>.</p></div>
<div class="paragraph"><p>ØMQ sockets being <em>asynchronous</em> 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 <em>queued</em> in
the event that a peer is unavailable to receive them.</p></div>
<div class="paragraph"><p>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 <em>ZMQ_PAIR</em>, ØMQ sockets may be connected
<strong>to multiple endpoints</strong> using <em>zmq_connect()</em>, while simultaneously accepting
incoming connections <strong>from multiple endpoints</strong> bound to the socket using
<em>zmq_bind()</em>, thus allowing many-to-many relationships.</p></div>
<div class="paragraph"><div class="title">Thread safety</div><p>ØMQ has both thread safe socket type and <em>not</em> thread safe socket types.
Applications MUST NOT use a <em>not</em> thread safe socket
from multiple threads except after migrating a socket from one thread to
another with a "full fence" memory barrier.</p></div>
<div class="paragraph"><p>Following are the thread safe sockets:
* ZMQ_CLIENT
* ZMQ_SERVER
* ZMQ_DISH
* ZMQ_RADIO
* ZMQ_SCATTER
* ZMQ_GATHER</p></div>
<div class="paragraph"><div class="title">Socket types</div><p>The following sections present the socket types defined by ØMQ, grouped by the
general <em>messaging pattern</em> which is built from related socket types.</p></div>
<div class="sect2">
<h3 id="_client_server_pattern">Client-server pattern</h3>
<div class="paragraph"><p>The client-server pattern is used to allow a single <em>ZMQ_SERVER</em> <em>server</em> talk
to one or more <em>ZMQ_CLIENT</em> <em>clients</em>. The client always starts the conversation,
after which either peer can send messages asynchronously, to the other.</p></div>
<div class="paragraph"><p>The client-server pattern is formally defined by <a href="http://rfc.zeromq.org/spec:41">http://rfc.zeromq.org/spec:41</a>.</p></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">Server-client is still in draft phase.</td>
</tr></table>
</div>
<div class="sect3">
<h4 id="_zmq_client">ZMQ_CLIENT</h4>
<div class="paragraph"><p>A <em>ZMQ_CLIENT</em> socket talks to a <em>ZMQ_SERVER</em> socket. Either peer can connect,
though the usual and recommended model is to bind the <em>ZMQ_SERVER</em> and connect
the <em>ZMQ_CLIENT</em>.</p></div>
<div class="paragraph"><p>If the <em>ZMQ_CLIENT</em> socket has established a connection, <a href="zmq_send.html">zmq_send(3)</a>
will accept messages, queue them, and send them as rapidly as the network
allows. The outgoing buffer limit is defined by the high water mark for the
socket. If the outgoing buffer is full, or if there is no connected peer,
<a href="zmq_send.html">zmq_send(3)</a> will block, by default. The <em>ZMQ_CLIENT</em> socket will not
drop messages.</p></div>
<div class="paragraph"><p>When a <em>ZMQ_CLIENT</em> socket is connected to multiple <em>ZMQ_SERVER</em> sockets,
outgoing messages are distributed between connected peers on a round-robin
basis. Likewise, the <em>ZMQ_CLIENT</em> socket receives messages fairly from each
connected peer. This usage is sensible only for stateless protocols.</p></div>
<div class="paragraph"><p><em>ZMQ_CLIENT</em> sockets are threadsafe and can be used from multiple threads
at the same time. Note that replies from a <em>ZMQ_SERVER</em> socket will go to
the first client thread that calls <a href="zmq_msg_recv.html">zmq_msg_recv(3)</a>. If you need to get
replies back to the originating thread, use one <em>ZMQ_CLIENT</em> socket per
thread.</p></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content"><em>ZMQ_CLIENT</em> sockets are threadsafe. They do not accept the ZMQ_SNDMORE
option on sends not ZMQ_RCVMORE on receives. This limits them to single part
data. The intention is to extend the API to allow scatter/gather of multi-part
data.</td>
</tr></table>
</div>
<div class="hdlist"><div class="title">Summary of ZMQ_CLIENT characteristics</div><table>
<tr>
<td class="hdlist1">
Compatible peer sockets
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
<em>ZMQ_SERVER</em>
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Direction
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
Bidirectional
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Send/receive pattern
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
Unrestricted
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Outgoing routing strategy
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
Round-robin
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Incoming routing strategy
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
Fair-queued
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Action in mute state
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
Block
</p>
</td>
</tr>
</table></div>
</div>
<div class="sect3">
<h4 id="_zmq_server">ZMQ_SERVER</h4>
<div class="paragraph"><p>A <em>ZMQ_SERVER</em> socket talks to a set of <em>ZMQ_CLIENT</em> sockets. A <em>ZMQ_SERVER</em>
socket can only reply to an incoming message: the <em>ZMQ_CLIENT</em> peer must
always initiate a conversation.</p></div>
<div class="paragraph"><p>Each received message has a <em>routing_id</em> that is a 32-bit unsigned integer.
The application can fetch this with <a href="zmq_msg_routing_id.html">zmq_msg_routing_id(3)</a>. To send
a message to a given <em>ZMQ_CLIENT</em> peer the application must set the peer’s
<em>routing_id</em> on the message, using <a href="zmq_msg_set_routing_id.html">zmq_msg_set_routing_id(3)</a>.</p></div>
<div class="paragraph"><p>If the <em>routing_id</em> is not specified, or does not refer to a connected client
peer, the send call will fail with EHOSTUNREACH. If the outgoing buffer for
the client peer is full, the send call shall block, unless ZMQ_DONT_WAIT is
used in the send, in which case it shall fail with EAGAIN. The <em>ZMQ_SERVER</em>
socket shall not drop messages in any case.</p></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content"><em>ZMQ_SERVER</em> sockets are threadsafe. They do not accept the ZMQ_SNDMORE
option on sends not ZMQ_RCVMORE on receives. This limits them to single part
data. The intention is to extend the API to allow scatter/gather of multi-part
data.</td>
</tr></table>
</div>
<div class="hdlist"><div class="title">Summary of ZMQ_SERVER characteristics</div><table>
<tr>
<td class="hdlist1">
Compatible peer sockets
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
<em>ZMQ_CLIENT</em>
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Direction
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
Bidirectional
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Send/receive pattern
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
Unrestricted
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Outgoing routing strategy
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
See text
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Incoming routing strategy
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
Fair-queued
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Action in mute state
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
Return EAGAIN
</p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="sect2">
<h3 id="_radio_dish_pattern">Radio-dish pattern</h3>
<div class="paragraph"><p>The radio-dish pattern is used for one-to-many distribution of data from
a single <em>publisher</em> to multiple <em>subscribers</em> in a fan out fashion.</p></div>
<div class="paragraph"><p>Radio-dish is using groups (vs Pub-sub topics), Dish sockets can join a group
and each message sent by Radio sockets belong to a group.</p></div>
<div class="paragraph"><p>Groups are null terminated strings limited to 16 chars length (including null).
The intention is to increase the length to 40 chars (including null).
The encoding of groups shall be UTF8.</p></div>
<div class="paragraph"><p>Groups are matched using exact matching (vs prefix matching of PubSub).</p></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">Radio-dish is still in draft phase.</td>
</tr></table>
</div>
<div class="sect3">
<h4 id="_zmq_radio">ZMQ_RADIO</h4>
<div class="paragraph"><p>A socket of type <em>ZMQ_RADIO</em> is used by a <em>publisher</em> to distribute data.
Each message belong to a group, a group is specified with <a href="zmq_msg_set_group.html">zmq_msg_set_group(3)</a>.
Messages are distributed to all members of a group.
The <a href="zmq_recv.html">zmq_recv(3)</a> function is not implemented for this socket type.</p></div>
<div class="paragraph"><p>When a <em>ZMQ_RADIO</em> socket enters the <em>mute</em> state due to having reached the
high water mark for a <em>subscriber</em>, then any messages that would be sent to the
<em>subscriber</em> in question shall instead be dropped until the mute state
ends. The <em>zmq_send()</em> function shall never block for this socket type.</p></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content"><em>ZMQ_RADIO</em> sockets are threadsafe. They do not accept the ZMQ_SNDMORE
option on sends. This limits them to single part data.</td>
</tr></table>
</div>
<div class="hdlist"><div class="title">Summary of ZMQ_RADIO characteristics</div><table>
<tr>
<td class="hdlist1">
Compatible peer sockets
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
<em>ZMQ_DISH</em>
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Direction
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
Unidirectional
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Send/receive pattern
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
Send only
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Incoming routing strategy
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
N/A
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Outgoing routing strategy
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
Fan out
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Action in mute state
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
Drop
</p>
</td>
</tr>
</table></div>
</div>
<div class="sect3">
<h4 id="_zmq_dish">ZMQ_DISH</h4>
<div class="paragraph"><p>A socket of type <em>ZMQ_DISH</em> is used by a <em>subscriber</em> to subscribe to groups
distributed by a <em>radio</em>. Initially a <em>ZMQ_DISH</em> socket is not subscribed to
any groups, use <a href="zmq_join.html">zmq_join(3)</a> to
join a group.
To get the group the message belong to call <a href="zmq_msg_group.html">zmq_msg_group(3)</a>.
The <em>zmq_send()</em> function is not implemented for this socket type.</p></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content"><em>ZMQ_DISH</em> sockets are threadsafe. They do not accept ZMQ_RCVMORE on receives.
This limits them to single part data.</td>
</tr></table>
</div>
<div class="hdlist"><div class="title">Summary of ZMQ_DISH characteristics</div><table>
<tr>
<td class="hdlist1">
Compatible peer sockets
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
<em>ZMQ_RADIO</em>
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Direction
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
Unidirectional
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Send/receive pattern
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
Receive only
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Incoming routing strategy
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
Fair-queued
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Outgoing routing strategy
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
N/A
</p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="sect2">
<h3 id="_publish_subscribe_pattern">Publish-subscribe pattern</h3>
<div class="paragraph"><p>The publish-subscribe pattern is used for one-to-many distribution of data from
a single <em>publisher</em> to multiple <em>subscribers</em> in a fan out fashion.</p></div>
<div class="paragraph"><p>The publish-subscribe pattern is formally defined by <a href="http://rfc.zeromq.org/spec:29">http://rfc.zeromq.org/spec:29</a>.</p></div>
<div class="sect3">
<h4 id="_zmq_pub">ZMQ_PUB</h4>
<div class="paragraph"><p>A socket of type <em>ZMQ_PUB</em> is used by a <em>publisher</em> to distribute data.
Messages sent are distributed in a fan out fashion to all connected peers.
The <a href="zmq_recv.html">zmq_recv(3)</a> function is not implemented for this socket type.</p></div>
<div class="paragraph"><p>When a <em>ZMQ_PUB</em> socket enters the <em>mute</em> state due to having reached the
high water mark for a <em>subscriber</em>, then any messages that would be sent to the
<em>subscriber</em> in question shall instead be dropped until the mute state
ends. The <em>zmq_send()</em> function shall never block for this socket type.</p></div>
<div class="hdlist"><div class="title">Summary of ZMQ_PUB characteristics</div><table>
<tr>
<td class="hdlist1">
Compatible peer sockets
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
<em>ZMQ_SUB</em>, <em>ZMQ_XSUB</em>
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Direction
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
Unidirectional
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Send/receive pattern
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
Send only
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Incoming routing strategy
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
N/A
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Outgoing routing strategy
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
Fan out
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Action in mute state
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
Drop
</p>
</td>
</tr>
</table></div>
</div>
<div class="sect3">
<h4 id="_zmq_sub">ZMQ_SUB</h4>
<div class="paragraph"><p>A socket of type <em>ZMQ_SUB</em> is used by a <em>subscriber</em> to subscribe to data
distributed by a <em>publisher</em>. Initially a <em>ZMQ_SUB</em> socket is not subscribed to
any messages, use the <em>ZMQ_SUBSCRIBE</em> option of <a href="zmq_setsockopt.html">zmq_setsockopt(3)</a> to
specify which messages to subscribe to. The <em>zmq_send()</em> function is not
implemented for this socket type.</p></div>
<div class="hdlist"><div class="title">Summary of ZMQ_SUB characteristics</div><table>
<tr>
<td class="hdlist1">
Compatible peer sockets
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
<em>ZMQ_PUB</em>, <em>ZMQ_XPUB</em>
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Direction
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
Unidirectional
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Send/receive pattern
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
Receive only
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Incoming routing strategy
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
Fair-queued
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Outgoing routing strategy
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
N/A
</p>
</td>
</tr>
</table></div>
</div>
<div class="sect3">
<h4 id="_zmq_xpub">ZMQ_XPUB</h4>
<div class="paragraph"><p>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.</p></div>
<div class="hdlist"><div class="title">Summary of ZMQ_XPUB characteristics</div><table>
<tr>
<td class="hdlist1">
Compatible peer sockets
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
<em>ZMQ_SUB</em>, <em>ZMQ_XSUB</em>
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Direction
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
Unidirectional
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Send/receive pattern
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
Send messages, receive subscriptions
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Incoming routing strategy
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
N/A
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Outgoing routing strategy
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
Fan out
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Action in mute state
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
Drop
</p>
</td>
</tr>
</table></div>
</div>
<div class="sect3">
<h4 id="_zmq_xsub">ZMQ_XSUB</h4>
<div class="paragraph"><p>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.</p></div>
<div class="hdlist"><div class="title">Summary of ZMQ_XSUB characteristics</div><table>
<tr>
<td class="hdlist1">
Compatible peer sockets
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
<em>ZMQ_PUB</em>, <em>ZMQ_XPUB</em>
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Direction
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
Unidirectional
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Send/receive pattern
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
Receive messages, send subscriptions
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Incoming routing strategy
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
Fair-queued
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Outgoing routing strategy
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
N/A
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Action in mute state
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
Drop
</p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="sect2">
<h3 id="_pipeline_pattern">Pipeline pattern</h3>
<div class="paragraph"><p>The pipeline pattern is used for distributing data to <em>nodes</em> arranged in
a pipeline. Data always flows down the pipeline, and each stage of the pipeline
is connected to at least one <em>node</em>. When a pipeline stage is connected to
multiple <em>nodes</em> data is round-robined among all connected <em>nodes</em>.</p></div>
<div class="paragraph"><p>The pipeline pattern is formally defined by <a href="http://rfc.zeromq.org/spec:30">http://rfc.zeromq.org/spec:30</a>.</p></div>
<div class="sect3">
<h4 id="_zmq_push">ZMQ_PUSH</h4>
<div class="paragraph"><p>A socket of type <em>ZMQ_PUSH</em> is used by a pipeline <em>node</em> to send messages
to downstream pipeline <em>nodes</em>. Messages are round-robined to all connected
downstream <em>nodes</em>. The <em>zmq_recv()</em> function is not implemented for this
socket type.</p></div>
<div class="paragraph"><p>When a <em>ZMQ_PUSH</em> socket enters the <em>mute</em> state due to having reached the
high water mark for all downstream <em>nodes</em>, or if there are no downstream
<em>nodes</em> at all, then any <a href="zmq_send.html">zmq_send(3)</a> operations on the socket shall
block until the mute state ends or at least one downstream <em>node</em>
becomes available for sending; messages are not discarded.</p></div>
<div class="hdlist"><div class="title">Summary of ZMQ_PUSH characteristics</div><table>
<tr>
<td class="hdlist1">
Compatible peer sockets
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
<em>ZMQ_PULL</em>
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Direction
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
Unidirectional
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Send/receive pattern
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
Send only
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Incoming routing strategy
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
N/A
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Outgoing routing strategy
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
Round-robin
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Action in mute state
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
Block
</p>
</td>
</tr>
</table></div>
</div>
<div class="sect3">
<h4 id="_zmq_pull">ZMQ_PULL</h4>
<div class="paragraph"><p>A socket of type <em>ZMQ_PULL</em> is used by a pipeline <em>node</em> to receive messages
from upstream pipeline <em>nodes</em>. Messages are fair-queued from among all
connected upstream <em>nodes</em>. The <em>zmq_send()</em> function is not implemented for
this socket type.</p></div>
<div class="hdlist"><div class="title">Summary of ZMQ_PULL characteristics</div><table>
<tr>
<td class="hdlist1">
Compatible peer sockets
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
<em>ZMQ_PUSH</em>
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Direction
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
Unidirectional
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Send/receive pattern
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
Receive only
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Incoming routing strategy
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
Fair-queued
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Outgoing routing strategy
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
N/A
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Action in mute state
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
Block
</p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="sect2">
<h3 id="_exclusive_pair_pattern">Exclusive pair pattern</h3>
<div class="paragraph"><p>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.</p></div>
<div class="paragraph"><p>The exclusive pair pattern is formally defined by <a href="http://rfc.zeromq.org/spec:31">http://rfc.zeromq.org/spec:31</a>.</p></div>
<div class="sect3">
<h4 id="_zmq_pair">ZMQ_PAIR</h4>
<div class="paragraph"><p>A socket of type <em>ZMQ_PAIR</em> can only be connected to a single peer at any one
time. No message routing or filtering is performed on messages sent over a
<em>ZMQ_PAIR</em> socket.</p></div>
<div class="paragraph"><p>When a <em>ZMQ_PAIR</em> socket enters the <em>mute</em> state due to having reached the
high water mark for the connected peer, or if no peer is connected, then
any <a href="zmq_send.html">zmq_send(3)</a> operations on the socket shall block until the peer
becomes available for sending; messages are not discarded.</p></div>
<div class="paragraph"><p>While <em>ZMQ_PAIR</em> sockets can be used over transports other than <a href="zmq_inproc.html">zmq_inproc(7)</a>,
their inability to auto-reconnect coupled with the fact new incoming connections will
be terminated while any previous connections (including ones in a closing state)
exist makes them unsuitable for TCP in most cases.</p></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content"><em>ZMQ_PAIR</em> sockets are designed for inter-thread communication across
the <a href="zmq_inproc.html">zmq_inproc(7)</a> transport and do not implement functionality such
as auto-reconnection.</td>
</tr></table>
</div>
<div class="hdlist"><div class="title">Summary of ZMQ_PAIR characteristics</div><table>
<tr>
<td class="hdlist1">
Compatible peer sockets
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
<em>ZMQ_PAIR</em>
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Direction
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
Bidirectional
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Send/receive pattern
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
Unrestricted
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Incoming routing strategy
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
N/A
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Outgoing routing strategy
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
N/A
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Action in mute state
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
Block
</p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="sect2">
<h3 id="_native_pattern">Native Pattern</h3>
<div class="paragraph"><p>The native pattern is used for communicating with TCP peers and allows
asynchronous requests and replies in either direction.</p></div>
<div class="sect3">
<h4 id="_zmq_stream">ZMQ_STREAM</h4>
<div class="paragraph"><p>A socket of type <em>ZMQ_STREAM</em> is used to send and receive TCP data from a
non-ØMQ peer, when using the tcp:// transport. A <em>ZMQ_STREAM</em> socket can
act as client and/or server, sending and/or receiving TCP data asynchronously.</p></div>
<div class="paragraph"><p>When receiving TCP data, a <em>ZMQ_STREAM</em> socket shall prepend a message part
containing the <em>routing id</em> of the originating peer to the message before passing
it to the application. Messages received are fair-queued from among all
connected peers.</p></div>
<div class="paragraph"><p>When sending TCP data, a <em>ZMQ_STREAM</em> socket shall remove the first part of the
message and use it to determine the <em>routing id</em> of the peer the message shall be
routed to, and unroutable messages shall cause an EHOSTUNREACH or EAGAIN error.</p></div>
<div class="paragraph"><p>To open a connection to a server, use the zmq_connect call, and then fetch the
socket routing id using the zmq_getsockopt call with the ZMQ_ROUTING_ID option.</p></div>
<div class="paragraph"><p>To close a specific connection, send the routing id frame followed by a
zero-length message (see EXAMPLE section).</p></div>
<div class="paragraph"><p>When a connection is made, a zero-length message will be received by the
application. Similarly, when the peer disconnects (or the connection is lost),
a zero-length message will be received by the application.</p></div>
<div class="paragraph"><p>You must send one routing id frame followed by one data frame. The ZMQ_SNDMORE
flag is required for routing id frames but is ignored on data frames.</p></div>
<div class="hdlist"><div class="title">Summary of ZMQ_STREAM characteristics</div><table>
<tr>
<td class="hdlist1">
Compatible peer sockets
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
none.
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Direction
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
Bidirectional
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Send/receive pattern
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
Unrestricted
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Outgoing routing strategy
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
See text
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Incoming routing strategy
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
Fair-queued
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Action in mute state
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
EAGAIN
</p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="sect2">
<h3 id="_request_reply_pattern">Request-reply pattern</h3>
<div class="paragraph"><p>The request-reply pattern is used for sending requests from a ZMQ_REQ <em>client</em>
to one or more ZMQ_REP <em>services</em>, and receiving subsequent replies to each
request sent.</p></div>
<div class="paragraph"><p>The request-reply pattern is formally defined by <a href="http://rfc.zeromq.org/spec:28">http://rfc.zeromq.org/spec:28</a>.</p></div>
<div class="sect3">
<h4 id="_zmq_req">ZMQ_REQ</h4>
<div class="paragraph"><p>A socket of type <em>ZMQ_REQ</em> is used by a <em>client</em> to send requests to and
receive replies from a <em>service</em>. This socket type allows only an alternating
sequence of <em>zmq_send(request)</em> and subsequent <em>zmq_recv(reply)</em> calls. Each
request sent is round-robined among all <em>services</em>, and each reply received is
matched with the last issued request.</p></div>
<div class="paragraph"><p>If no services are available, then any send operation on the socket shall
block until at least one <em>service</em> becomes available. The REQ socket shall
not discard messages.</p></div>
<div class="hdlist"><div class="title">Summary of ZMQ_REQ characteristics</div><table>
<tr>
<td class="hdlist1">
Compatible peer sockets
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
<em>ZMQ_REP</em>, <em>ZMQ_ROUTER</em>
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Direction
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
Bidirectional
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Send/receive pattern
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
Send, Receive, Send, Receive, …
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Outgoing routing strategy
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
Round-robin
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Incoming routing strategy
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
Last peer
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Action in mute state
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
Block
</p>
</td>
</tr>
</table></div>
</div>
<div class="sect3">
<h4 id="_zmq_rep">ZMQ_REP</h4>
<div class="paragraph"><p>A socket of type <em>ZMQ_REP</em> is used by a <em>service</em> to receive requests from and
send replies to a <em>client</em>. This socket type allows only an alternating
sequence of <em>zmq_recv(request)</em> and subsequent <em>zmq_send(reply)</em> calls. Each
request received is fair-queued from among all <em>clients</em>, and each reply sent
is routed to the <em>client</em> that issued the last request. If the original
requester does not exist any more the reply is silently discarded.</p></div>
<div class="hdlist"><div class="title">Summary of ZMQ_REP characteristics</div><table>
<tr>
<td class="hdlist1">
Compatible peer sockets
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
<em>ZMQ_REQ</em>, <em>ZMQ_DEALER</em>
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Direction
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
Bidirectional
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Send/receive pattern
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
Receive, Send, Receive, Send, …
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Incoming routing strategy
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
Fair-queued
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Outgoing routing strategy
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
Last peer
</p>
</td>
</tr>
</table></div>
</div>
<div class="sect3">
<h4 id="_zmq_dealer">ZMQ_DEALER</h4>
<div class="paragraph"><p>A socket of type <em>ZMQ_DEALER</em> 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.</p></div>
<div class="paragraph"><p>When a <em>ZMQ_DEALER</em> socket enters the <em>mute</em> state due to having reached the
high water mark for all peers, or if there are no peers at all, then any
<a href="zmq_send.html">zmq_send(3)</a> operations on the socket shall block until the mute
state ends or at least one peer becomes available for sending; messages are not
discarded.</p></div>
<div class="paragraph"><p>When a <em>ZMQ_DEALER</em> socket is connected to a <em>ZMQ_REP</em> socket each message sent
must consist of an empty message part, the <em>delimiter</em>, followed by one or more
<em>body parts</em>.</p></div>
<div class="hdlist"><div class="title">Summary of ZMQ_DEALER characteristics</div><table>
<tr>
<td class="hdlist1">
Compatible peer sockets
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
<em>ZMQ_ROUTER</em>, <em>ZMQ_REP</em>, <em>ZMQ_DEALER</em>
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Direction
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
Bidirectional
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Send/receive pattern
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
Unrestricted
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Outgoing routing strategy
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
Round-robin
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Incoming routing strategy
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
Fair-queued
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Action in mute state
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
Block
</p>
</td>
</tr>
</table></div>
</div>
<div class="sect3">
<h4 id="_zmq_router">ZMQ_ROUTER</h4>
<div class="paragraph"><p>A socket of type <em>ZMQ_ROUTER</em> is an advanced socket type used for extending
request/reply sockets. When receiving messages a <em>ZMQ_ROUTER</em> socket shall
prepend a message part containing the <em>routing id</em> 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 <em>ZMQ_ROUTER</em> socket shall
remove the first part of the message and use it to determine the _routing id _ of
the peer the message shall be routed to. If the peer does not exist anymore, or
has never existed, the message shall be silently discarded. However, if
<em>ZMQ_ROUTER_MANDATORY</em> socket option is set to <em>1</em>, the socket shall fail
with EHOSTUNREACH in both cases.</p></div>
<div class="paragraph"><p>When a <em>ZMQ_ROUTER</em> socket enters the <em>mute</em> 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. If,
<em>ZMQ_ROUTER_MANDATORY</em> is set to <em>1</em>, the socket shall block or return EAGAIN in
both cases.</p></div>
<div class="paragraph"><p>When a <em>ZMQ_ROUTER</em> socket has <em>ZMQ_ROUTER_MANDATORY</em> flag set to <em>1</em>, the
socket shall generate <em>ZMQ_POLLIN</em> events upon reception of messages from one
or more peers. Likewise, the socket shall generate <em>ZMQ_POLLOUT</em> events when
at least one message can be sent to one or more peers.</p></div>
<div class="paragraph"><p>When a <em>ZMQ_REQ</em> socket is connected to a <em>ZMQ_ROUTER</em> socket, in addition to the
<em>routing id</em> of the originating peer each message received shall contain an empty
<em>delimiter</em> message part. Hence, the entire structure of each received message
as seen by the application becomes: one or more <em>routing id</em> parts, <em>delimiter</em>
part, one or more <em>body parts</em>. When sending replies to a <em>ZMQ_REQ</em> socket the
application must include the <em>delimiter</em> part.</p></div>
<div class="hdlist"><div class="title">Summary of ZMQ_ROUTER characteristics</div><table>
<tr>
<td class="hdlist1">
Compatible peer sockets
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
<em>ZMQ_DEALER</em>, <em>ZMQ_REQ</em>, <em>ZMQ_ROUTER</em>
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Direction
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
Bidirectional
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Send/receive pattern
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
Unrestricted
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Outgoing routing strategy
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
See text
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Incoming routing strategy
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
Fair-queued
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Action in mute state
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
Drop (see text)
</p>
</td>
</tr>
</table></div>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_return_value">RETURN VALUE</h2>
<div class="sectionbody">
<div class="paragraph"><p>The <em>zmq_socket()</em> function shall return an opaque handle to the newly created
socket if successful. Otherwise, it shall return NULL and set <em>errno</em> to one of
the values defined below.</p></div>
</div>
</div>
<div class="sect1">
<h2 id="_errors">ERRORS</h2>
<div class="sectionbody">
<div class="dlist"><dl>
<dt class="hdlist1">
<strong>EINVAL</strong>
</dt>
<dd>
<p>
The requested socket <em>type</em> is invalid.
</p>
</dd>
<dt class="hdlist1">
<strong>EFAULT</strong>
</dt>
<dd>
<p>
The provided <em>context</em> is invalid.
</p>
</dd>
<dt class="hdlist1">
<strong>EMFILE</strong>
</dt>
<dd>
<p>
The limit on the total number of open ØMQ sockets has been reached.
</p>
</dd>
<dt class="hdlist1">
<strong>ETERM</strong>
</dt>
<dd>
<p>
The context specified was terminated.
</p>
</dd>
</dl></div>
</div>
</div>
<div class="sect1">
<h2 id="_example">EXAMPLE</h2>
<div class="sectionbody">
<div class="listingblock">
<div class="title">Creating a simple HTTP server using ZMQ_STREAM</div>
<div class="content">
<pre><code>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 routing id */
uint8_t routing_id [256];
size_t routing_id_size = 256;
/* Data structure to hold the ZMQ_STREAM received data */
uint8_t raw [256];
size_t raw_size = 256;
while (1) {
/* Get HTTP request; routing id frame and then request */
routing_id_size = zmq_recv (socket, routing_id, 256, 0);
assert (routing_id_size > 0);
do {
raw_size = zmq_recv (socket, raw, 256, 0);
assert (raw_size >= 0);
} while (raw_size == 256);
/* 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 routing id frame followed by the response */
zmq_send (socket, routing_id, routing_id_size, ZMQ_SNDMORE);
zmq_send (socket, http_response, strlen (http_response), 0);
/* Closes the connection by sending the routing id frame followed by a zero response */
zmq_send (socket, routing_id, routing_id_size, ZMQ_SNDMORE);
zmq_send (socket, 0, 0, 0);
}
zmq_close (socket);
zmq_ctx_destroy (ctx);</code></pre>
</div></div>
</div>
</div>
<div class="sect1">
<h2 id="_see_also">SEE ALSO</h2>
<div class="sectionbody">
<div class="paragraph"><p><a href="zmq_init.html">zmq_init(3)</a>
<a href="zmq_setsockopt.html">zmq_setsockopt(3)</a>
<a href="zmq_bind.html">zmq_bind(3)</a>
<a href="zmq_connect.html">zmq_connect(3)</a>
<a href="zmq_send.html">zmq_send(3)</a>
<a href="zmq_recv.html">zmq_recv(3)</a>
<a href="zmq_inproc.html">zmq_inproc(7)</a>
<a href="zmq.html">zmq(7)</a></p></div>
</div>
</div>
<div class="sect1">
<h2 id="_authors">AUTHORS</h2>
<div class="sectionbody">
<div class="paragraph"><p>This page was written by the ØMQ community. To make a change please
read the ØMQ Contribution Policy at <a href="http://www.zeromq.org/docs:contributing">http://www.zeromq.org/docs:contributing</a>.</p></div>
</div>
</div>
</div>
<div id="footnotes"><hr /></div>
<div id="footer">
<div id="footer-text">
ØMQ 4.3.1<br />
Last updated 2019-01-12 16:17:39 UTC
</div>
</div>
</body>
</html>
distrib
>
Mageia
>
7
>
armv7hl
>
media
>
core-release
>
by-pkgid
>
92695e6ed30b46bac9b8c2c73cac6425
>
files
>
68
