1
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
2
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
3
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
5
<meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" />
6
<meta name="generator" content="AsciiDoc 8.6.4" />
7
<title>zmq_ctx_set_monitor(3)</title>
8
<style type="text/css">
10
h1, h2, h3, h4, h5, h6,
11
div.title, caption.title,
12
thead, p.table.header,
14
span#author, span#revnumber, span#revdate, span#revremark,
16
font-family: Arial,Helvetica,sans-serif;
21
font-family: Georgia,"Times New Roman",Times,serif;
30
margin: 1em 5% 1em 5%;
35
text-decoration: underline;
56
h1, h2, h3, h4, h5, h6 {
64
border-bottom: 2px solid silver;
81
border: 1px solid silver;
92
ul > li { color: #aaa; }
93
ul > li > * { color: black; }
107
span#revnumber, span#revdate, span#revremark {
112
border-top: 2px solid silver;
118
padding-bottom: 0.5em;
122
padding-bottom: 0.5em;
127
margin-bottom: 1.5em;
129
div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
130
div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
131
div.admonitionblock {
133
margin-bottom: 1.5em;
135
div.admonitionblock {
137
margin-bottom: 2.0em;
142
div.content { /* Block element content. */
146
/* Block element titles. */
147
div.title, caption.title {
152
margin-bottom: 0.5em;
158
td div.title:first-child {
161
div.content div.title:first-child {
164
div.content + div.title {
168
div.sidebarblock > div.content {
170
border: 1px solid #dddddd;
171
border-left: 4px solid #f0f0f0;
175
div.listingblock > div.content {
176
border: 1px solid #dddddd;
177
border-left: 5px solid #f0f0f0;
182
div.quoteblock, div.verseblock {
186
border-left: 5px solid #f0f0f0;
190
div.quoteblock > div.attribution {
195
div.verseblock > pre.content {
196
font-family: inherit;
199
div.verseblock > div.attribution {
203
/* DEPRECATED: Pre version 8.2.7 verse style literal block. */
204
div.verseblock + div.attribution {
208
div.admonitionblock .icon {
212
text-decoration: underline;
214
padding-right: 0.5em;
216
div.admonitionblock td.content {
218
border-left: 3px solid #dddddd;
221
div.exampleblock > div.content {
222
border-left: 3px solid #dddddd;
226
div.imageblock div.content { padding-left: 0; }
227
span.image img { border-style: none; }
228
a.image:visited { color: white; }
232
margin-bottom: 0.8em;
245
list-style-position: outside;
248
list-style-type: decimal;
251
list-style-type: lower-alpha;
254
list-style-type: upper-alpha;
257
list-style-type: lower-roman;
260
list-style-type: upper-roman;
263
div.compact ul, div.compact ol,
264
div.compact p, div.compact p,
265
div.compact div, div.compact div {
267
margin-bottom: 0.1em;
270
div.tableblock > table {
271
border: 3px solid #527bbd;
273
thead, p.table.header {
286
/* Because the table frame attribute is overriden by CSS in most browsers. */
287
div.tableblock > table[frame="void"] {
290
div.tableblock > table[frame="hsides"] {
291
border-left-style: none;
292
border-right-style: none;
294
div.tableblock > table[frame="vsides"] {
295
border-top-style: none;
296
border-bottom-style: none;
302
margin-bottom: 0.8em;
305
padding-bottom: 15px;
307
dt.hdlist1.strong, td.hdlist1.strong {
313
padding-right: 0.8em;
319
div.hdlist.compact tr {
328
.footnote, .footnoteref {
332
span.footnote, span.footnoteref {
333
vertical-align: super;
337
margin: 20px 0 20px 0;
341
#footnotes div.footnote {
347
border-top: 1px solid silver;
356
padding-right: 0.5em;
357
padding-bottom: 0.3em;
365
div#footer-badges { display: none; }
369
margin-bottom: 2.5em;
377
margin-bottom: 0.1em;
380
div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
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; }
433
/* Overrides for manpage documents */
436
padding-bottom: 0.5em;
437
border-top: 2px solid silver;
438
border-bottom: 2px solid silver;
448
div#toc { display: none; }
452
<script type="text/javascript">
454
window.onload = function(){asciidoc.footnotes();}
455
var asciidoc = { // Namespace.
457
/////////////////////////////////////////////////////////////////////
458
// Table Of Contents generator
459
/////////////////////////////////////////////////////////////////////
461
/* Author: Mihai Bazon, September 2002
462
* http://students.infoiasi.ro/~mishoo
464
* Table Of Content generator
467
* Feel free to use this script under the terms of the GNU General Public
468
* License, as long as you do not remove or alter this notice.
471
/* modified by Troy D. Hanson, September 2006. License: GPL */
472
/* modified by Stuart Rackham, 2006, 2009. License: GPL */
475
toc: function (toclevels) {
477
function getText(el) {
479
for (var i = el.firstChild; i != null; i = i.nextSibling) {
480
if (i.nodeType == 3 /* Node.TEXT_NODE */) // IE doesn't speak constants.
482
else if (i.firstChild != null)
488
function TocEntry(el, text, toclevel) {
491
this.toclevel = toclevel;
494
function tocEntries(el, toclevels) {
495
var result = new Array;
496
var re = new RegExp('[hH]([2-'+(toclevels+1)+'])');
497
// Function that scans the DOM tree for header elements (the DOM2
498
// nodeIterator API would be a better technique but not supported by all
500
var iterate = function (el) {
501
for (var i = el.firstChild; i != null; i = i.nextSibling) {
502
if (i.nodeType == 1 /* Node.ELEMENT_NODE */) {
503
var mo = re.exec(i.tagName);
504
if (mo && (i.getAttribute("class") || i.getAttribute("className")) != "float") {
505
result[result.length] = new TocEntry(i, getText(i), mo[1]-1);
515
var toc = document.getElementById("toc");
516
var entries = tocEntries(document.getElementById("content"), toclevels);
517
for (var i = 0; i < entries.length; ++i) {
518
var entry = entries[i];
519
if (entry.element.id == "")
520
entry.element.id = "_toc_" + i;
521
var a = document.createElement("a");
522
a.href = "#" + entry.element.id;
523
a.appendChild(document.createTextNode(entry.text));
524
var div = document.createElement("div");
526
div.className = "toclevel" + entry.toclevel;
527
toc.appendChild(div);
529
if (entries.length == 0)
530
toc.parentNode.removeChild(toc);
534
/////////////////////////////////////////////////////////////////////
535
// Footnotes generator
536
/////////////////////////////////////////////////////////////////////
538
/* Based on footnote generation code from:
539
* http://www.brandspankingnew.net/archive/2005/07/format_footnote.html
542
footnotes: function () {
543
var cont = document.getElementById("content");
544
var noteholder = document.getElementById("footnotes");
545
var spans = cont.getElementsByTagName("span");
548
for (i=0; i<spans.length; i++) {
549
if (spans[i].className == "footnote") {
551
// Use [\s\S] in place of . so multi-line matches work.
552
// Because JavaScript has no s (dotall) regex flag.
553
note = spans[i].innerHTML.match(/\s*\[([\s\S]*)]\s*/)[1];
554
noteholder.innerHTML +=
555
"<div class='footnote' id='_footnote_" + n + "'>" +
556
"<a href='#_footnoteref_" + n + "' title='Return to text'>" +
557
n + "</a>. " + note + "</div>";
559
"[<a id='_footnoteref_" + n + "' href='#_footnote_" + n +
560
"' title='View footnote' class='footnote'>" + n + "</a>]";
561
var id =spans[i].getAttribute("id");
562
if (id != null) refs["#"+id] = n;
566
noteholder.parentNode.removeChild(noteholder);
568
// Process footnoterefs.
569
for (i=0; i<spans.length; i++) {
570
if (spans[i].className == "footnoteref") {
571
var href = spans[i].getElementsByTagName("a")[0].getAttribute("href");
572
href = href.match(/#.*/)[0]; // Because IE return full URL.
575
"[<a href='#_footnote_" + n +
576
"' title='View footnote' class='footnote'>" + n + "</a>]";
586
<body class="manpage">
589
zmq_ctx_set_monitor(3) Manual Page
592
<div class="sectionbody">
593
<p>zmq_ctx_set_monitor -
594
register a monitoring callback
600
<h2 id="_synopsis">SYNOPSIS</h2>
601
<div class="sectionbody">
602
<div class="paragraph"><p><strong>int zmq_ctx_set_monitor (void <em>*context</em>, zmq_monitor_fn <em>*monitor</em>);</strong></p></div>
606
<h2 id="_description">DESCRIPTION</h2>
607
<div class="sectionbody">
608
<div class="paragraph"><p>The <em>zmq_ctx_set_monitor()</em> function shall register a callback function specified by
609
the <em>monitor</em> argument. This is an event sink for changes in per socket
610
connection and mailbox (work in progress) states.</p></div>
611
<div class="listingblock">
612
<div class="title">The <em>zmq_ctx_set_monitor()</em> callback function is expected to have this prototype:</div>
613
<div class="content">
614
<pre><tt>typedef void (zmq_monitor_fn) (void *s, int event, zmq_event_data_t *data);</tt></pre>
616
<div class="paragraph"><p>The callback is global (per context), with the socket that triggered the event
617
passed to the handler as well. Each event also populates a <em>zmq_event_data_t</em>
618
union with additional metadata which can be used for correlation.</p></div>
619
<div class="admonitionblock">
622
<div class="title">Caution</div>
624
<td class="content"><em>zmq_ctx_set_monitor()</em> is intended for monitoring infrastructure / operations
625
concerns only - NOT BUSINESS LOGIC. An event is a representation of something
626
that happened - you cannot change the past, but only react to them. The
627
implementation is also only concerned with a single session. No state of peers,
628
other sessions etc. are tracked - this will only pollute internals and is the
629
responsibility of application authors to either implement or correlate in
630
another datastore. Monitor events are exceptional conditions and are thus not
631
directly in the messaging critical path. However, still be careful with what
632
you’re doing in the callback function as excess time spent in the handler will
633
block the socket’s application thread.</td>
636
<div class="paragraph"><p>Only tcp and ipc specific transport events are supported in this initial
637
implementation.</p></div>
638
<div class="paragraph"><p>Supported events are:</p></div>
640
<h3 id="_zmq_event_connected_connection_established">ZMQ_EVENT_CONNECTED: connection established</h3>
641
<div class="paragraph"><p>The <em>ZMQ_EVENT_CONNECTED</em> event triggers when a connection has been established
642
to a remote peer. This can happen either synchronous or asynchronous.</p></div>
643
<div class="listingblock">
644
<div class="title">Callback metadata:</div>
645
<div class="content">
646
<pre><tt>data.connected.addr // peer address
647
data.connected.fd // socket descriptor</tt></pre>
651
<h3 id="_zmq_event_connect_delayed_synchronous_connect_failed_it_8217_s_being_polled">ZMQ_EVENT_CONNECT_DELAYED: synchronous connect failed, it’s being polled</h3>
652
<div class="paragraph"><p>The <em>ZMQ_EVENT_CONNECT_DELAYED</em> event triggers when an immediate connection
653
attempt is delayed and it’s completion’s being polled for.</p></div>
654
<div class="listingblock">
655
<div class="title">Callback metadata:</div>
656
<div class="content">
657
<pre><tt>data.connect_delayed.addr // peer address
658
data.connect_delayed.err // errno</tt></pre>
662
<h3 id="_zmq_event_connect_retried_asynchronous_connect_reconnection_attempt">ZMQ_EVENT_CONNECT_RETRIED: asynchronous connect / reconnection attempt</h3>
663
<div class="paragraph"><p>The <em>ZMQ_EVENT_CONNECT_RETRIED</em> event triggers when a connection attempt
664
is being handled by reconnect timer. The reconnect interval’s recomputed
665
for each attempt.</p></div>
666
<div class="listingblock">
667
<div class="title">Callback metadata:</div>
668
<div class="content">
669
<pre><tt>data.connect_retried.addr // peer address
670
data.connect_retried.interval // computed reconnect interval</tt></pre>
674
<h3 id="_zmq_event_listening_socket_bound_to_an_address_ready_to_accept_connections">ZMQ_EVENT_LISTENING: socket bound to an address, ready to accept connections</h3>
675
<div class="paragraph"><p>The <em>ZMQ_EVENT_LISTENING</em> event triggers when a socket’s successfully bound
676
to a an interface.</p></div>
677
<div class="listingblock">
678
<div class="title">Callback metadata:</div>
679
<div class="content">
680
<pre><tt>data.listening.addr // listen address
681
data.listening.fd // socket descriptor</tt></pre>
685
<h3 id="_zmq_event_bind_failed_socket_could_not_bind_to_an_address">ZMQ_EVENT_BIND_FAILED: socket could not bind to an address</h3>
686
<div class="paragraph"><p>The <em>ZMQ_EVENT_BIND_FAILED</em> event triggers when a socket could not bind to
687
a given interface.</p></div>
688
<div class="listingblock">
689
<div class="title">Callback metadata:</div>
690
<div class="content">
691
<pre><tt>data.bind_failed.addr // listen address
692
data.bind_failed.err // errno</tt></pre>
696
<h3 id="_zmq_event_accepted_connection_accepted_to_bound_interface">ZMQ_EVENT_ACCEPTED: connection accepted to bound interface</h3>
697
<div class="paragraph"><p>The <em>ZMQ_EVENT_ACCEPTED</em> event triggers when a connection from a remote peer
698
has been established with a socket’s listen address.</p></div>
699
<div class="listingblock">
700
<div class="title">Callback metadata:</div>
701
<div class="content">
702
<pre><tt>data.accepted.addr // listen address
703
data.accepted.fd // socket descriptor</tt></pre>
707
<h3 id="_zmq_event_accept_failed_could_not_accept_client_connection">ZMQ_EVENT_ACCEPT_FAILED: could not accept client connection</h3>
708
<div class="paragraph"><p>The <em>ZMQ_EVENT_ACCEPT_FAILED</em> event triggers when a connection attempt to
709
a socket’s bound address fails.</p></div>
710
<div class="listingblock">
711
<div class="title">Callback metadata:</div>
712
<div class="content">
713
<pre><tt>data.accept_failed.addr // listen address
714
data.accept_failed.err // errno</tt></pre>
718
<h3 id="_zmq_event_closed_connection_closed">ZMQ_EVENT_CLOSED: connection closed</h3>
719
<div class="paragraph"><p>The <em>ZMQ_EVENT_CLOSED</em> event triggers when a connection’s underlying descriptor
720
has been closed.</p></div>
721
<div class="listingblock">
722
<div class="title">Callback metadata:</div>
723
<div class="content">
724
<pre><tt>data.closed.addr // address
725
data.closed.fd // socket descriptor</tt></pre>
729
<h3 id="_zmq_event_close_failed_connection_couldn_8217_t_be_closed">ZMQ_EVENT_CLOSE_FAILED: connection couldn’t be closed</h3>
730
<div class="paragraph"><p>The <em>ZMQ_EVENT_CLOSE_FAILED</em> event triggers when a descriptor could not be
731
released back to the OS.</p></div>
732
<div class="listingblock">
733
<div class="title">Callback metadata:</div>
734
<div class="content">
735
<pre><tt>data.close_failed.addr // address
736
data.close_failed.err // errno</tt></pre>
740
<h3 id="_zmq_event_disconnected_broken_session">ZMQ_EVENT_DISCONNECTED: broken session</h3>
741
<div class="paragraph"><p>The <em>ZMQ_EVENT_DISCONNECTED</em> event triggers when the stream engine (tcp and ipc
742
specific) detects a corrupted / broken session.</p></div>
743
<div class="listingblock">
744
<div class="title">Callback metadata:</div>
745
<div class="content">
746
<pre><tt>data.disconnected.addr // address
747
data.disconnected.fd // socket descriptor</tt></pre>
753
<h2 id="_return_value">RETURN VALUE</h2>
754
<div class="sectionbody">
755
<div class="paragraph"><p>The <em>zmq_ctx_set_monitor()</em> function returns a value of 0 or greater if successful.
756
Otherwise it returns <tt>-1</tt> and sets <em>errno</em> to one of the values defined
761
<h2 id="_errors">ERRORS</h2>
762
<div class="sectionbody">
763
<div class="dlist"><dl>
765
<strong>EINVAL</strong>
769
The requested callback function <em>monitor</em> is invalid.
776
<h2 id="_example">EXAMPLE</h2>
777
<div class="sectionbody">
778
<div class="listingblock">
779
<div class="title">Observing a <em>PUB</em> socket’s connection state</div>
780
<div class="content">
781
<pre><tt>void socket_monitor (void *s, int event_, zmq_event_data_t *data_)
784
case ZMQ_EVENT_LISTENING:
785
printf ("Socket bound to %s, socket descriptor is %d\n",
786
data.listening.addr, data.listening.fd);
788
case ZMQ_EVENT_ACCEPTED:
789
printf ("Accepted connection to %s, socket descriptor is %d\n",
790
data.accepted.addr, data.accepted.fd);
795
void *context = zmq_ctx_new ();
796
int rc = zmq_ctx_set_monitor (context, socket_monitor);
798
void *pub = zmq_socket (context, ZMQ_PUB);
800
void *sub = zmq_socket (context, ZMQ_SUB);
802
rc = zmq_bind (pub, "tcp://127.0.0.1:5560");
804
rc = zmq_connect (sub, "tcp://127.0.0.1:5560");
807
// Allow a window for socket events as connect can be async
810
rc = zmq_close (pub);
812
rc = zmq_close (sub);
815
zmq_term (context);</tt></pre>
820
<h2 id="_see_also">SEE ALSO</h2>
821
<div class="sectionbody">
822
<div class="paragraph"><p><a href="zmq.html">zmq(7)</a></p></div>
826
<h2 id="_authors">AUTHORS</h2>
827
<div class="sectionbody">
828
<div class="paragraph"><p>This ØMQ manual page was written by Lourens Naudé <<a href="mailto:lourens@methodmissing.com">lourens@methodmissing.com</a>></p></div>
832
<div id="footnotes"><hr /></div>
834
<div id="footer-text">
836
Last updated 2012-06-05 09:39:30 CEST
added
removed
doc/zmq_ctx_set_monitor.html
