Initialize Tizen 2.3submit/tizen_2.3/20140531.1157412.3a_releasetizen_2.3

1 files changed, 380 insertions, 0 deletions

diff --git a/doc/zmq_socket_monitor.3 b/doc/zmq_socket_monitor.3
new file mode 100644
index 0000000..a0306fa
--- /dev/null
+++ b/doc/zmq_socket_monitor.3
@@ -0,0 +1,380 @@
+'\" t
+.\"     Title: zmq_ctx_socket_monitor
+.\"    Author: [see the "AUTHORS" section]
+.\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
+.\"      Date: 11/23/2012
+.\"    Manual: 0MQ Manual
+.\"    Source: 0MQ 3.2.1
+.\"  Language: English
+.\"
+.TH "ZMQ_CTX_SOCKET_MONIT" "3" "11/23/2012" "0MQ 3\&.2\&.1" "0MQ Manual"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+zmq_socket_monitor \- register a monitoring callback
+.SH "SYNOPSIS"
+.sp
+\fBint zmq_socket_monitor (void \fR\fB\fI*socket\fR\fR\fB, char * \fR\fB\fI*addr\fR\fR\fB, int \fR\fB\fIevents\fR\fR\fB);\fR
+.SH "DESCRIPTION"
+.sp
+The \fIzmq_socket_monitor()\fR function shall spawn a \fIPAIR\fR socket that publishes socket state changes (events) over the inproc:// transport to a given endpoint\&. Messages are \fIzmq_event_t\fR structs\&. It\(cqs recommended to connect via a \fIPAIR\fR socket in another application thread and handle monitoring events there\&. It\(cqs possible to also supply a bitmask (\fIZMQ_EVENT_ALL\fR or any combination of the \fIZMQ_EVENT_*\fR constants) of the events you\(cqre interested in\&.
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+// monitoring thread
+static void *req_socket_monitor (void *ctx)
+{
+    zmq_event_t event;
+    int rc;
+
+    void *s = zmq_socket (ctx, ZMQ_PAIR);
+    assert (s);
+
+    rc = zmq_connect (s, "inproc://monitor\&.req");
+    assert (rc == 0);
+    while (true) {
+        zmq_msg_t msg;
+        zmq_msg_init (&msg);
+        rc = zmq_recvmsg (s, &msg, 0);
+        if (rc == \-1 && zmq_errno() == ETERM) break;
+        assert (rc != \-1);
+        memcpy (&event, zmq_msg_data (&msg), sizeof (event));
+        switch (event\&.event) {
+        case ZMQ_EVENT_CONNECTED:
+            // handle socket connected event
+            break;
+        case ZMQ_EVENT_CLOSED:
+            // handle socket closed event
+            break;
+        }
+    }
+    zmq_close (s);
+    return NULL;
+}
+
+// register a monitor endpoint for all socket events
+rc = zmq_socket_monitor (req, "inproc://monitor\&.req", ZMQ_EVENT_ALL);
+assert (rc == 0);
+
+// spawn a monitoring thread
+rc = pthread_create (&threads [0], NULL, req_socket_monitor, ctx);
+assert (rc == 0);
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+Only connection oriented (tcp and ipc) transports are supported in this initial implementation\&.
+.sp
+Supported events are:
+.SS "ZMQ_EVENT_CONNECTED: connection established"
+.sp
+The \fIZMQ_EVENT_CONNECTED\fR event triggers when a connection has been established to a remote peer\&. This can happen either synchronous or asynchronous\&.
+.PP
+\fBEvent metadata:\fR. 
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+data\&.connected\&.addr // peer address
+data\&.connected\&.fd // socket descriptor
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+.SS "ZMQ_EVENT_CONNECT_DELAYED: synchronous connect failed, it\(cqs being polled"
+.sp
+The \fIZMQ_EVENT_CONNECT_DELAYED\fR event triggers when an immediate connection attempt is delayed and it\(cqs completion\(cqs being polled for\&.
+.PP
+\fBEvent metadata:\fR. 
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+data\&.connect_delayed\&.addr // peer address
+data\&.connect_delayed\&.err // errno value
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+.SS "ZMQ_EVENT_CONNECT_RETRIED: asynchronous connect / reconnection attempt"
+.sp
+The \fIZMQ_EVENT_CONNECT_RETRIED\fR event triggers when a connection attempt is being handled by reconnect timer\&. The reconnect interval\(cqs recomputed for each attempt\&.
+.PP
+\fBEvent metadata:\fR. 
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+data\&.connect_retried\&.addr // peer address
+data\&.connect_retried\&.interval // computed reconnect interval
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+.SS "ZMQ_EVENT_LISTENING: socket bound to an address, ready to accept connections"
+.sp
+The \fIZMQ_EVENT_LISTENING\fR event triggers when a socket\(cqs successfully bound to a an interface\&.
+.PP
+\fBEvent metadata:\fR. 
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+data\&.listening\&.addr //  listen address
+data\&.listening\&.fd // socket descriptor
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+.SS "ZMQ_EVENT_BIND_FAILED: socket could not bind to an address"
+.sp
+The \fIZMQ_EVENT_BIND_FAILED\fR event triggers when a socket could not bind to a given interface\&.
+.PP
+\fBEvent metadata:\fR. 
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+data\&.bind_failed\&.addr // listen address
+data\&.bind_failed\&.err // errno value
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+.SS "ZMQ_EVENT_ACCEPTED: connection accepted to bound interface"
+.sp
+The \fIZMQ_EVENT_ACCEPTED\fR event triggers when a connection from a remote peer has been established with a socket\(cqs listen address\&.
+.PP
+\fBEvent metadata:\fR. 
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+data\&.accepted\&.addr // listen address
+data\&.accepted\&.fd // socket descriptor
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+.SS "ZMQ_EVENT_ACCEPT_FAILED: could not accept client connection"
+.sp
+The \fIZMQ_EVENT_ACCEPT_FAILED\fR event triggers when a connection attempt to a socket\(cqs bound address fails\&.
+.PP
+\fBEvent metadata:\fR. 
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+data\&.accept_failed\&.addr // listen address
+data\&.accept_failed\&.err // errno value
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+.SS "ZMQ_EVENT_CLOSED: connection closed"
+.sp
+The \fIZMQ_EVENT_CLOSED\fR event triggers when a connection\(cqs underlying descriptor has been closed\&.
+.PP
+\fBEvent metadata:\fR. 
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+data\&.closed\&.addr // address
+data\&.closed\&.fd // socket descriptor
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+.SS "ZMQ_EVENT_CLOSE_FAILED: connection couldn\(cqt be closed"
+.sp
+The \fIZMQ_EVENT_CLOSE_FAILED\fR event triggers when a descriptor could not be released back to the OS\&.
+.PP
+\fBEvent metadata:\fR. 
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+data\&.close_failed\&.addr // address
+data\&.close_failed\&.err // errno value
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+.SS "ZMQ_EVENT_DISCONNECTED: broken session"
+.sp
+The \fIZMQ_EVENT_DISCONNECTED\fR event triggers when the stream engine (tcp and ipc specific) detects a corrupted / broken session\&.
+.PP
+\fBEvent metadata:\fR. 
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+data\&.disconnected\&.addr // address
+data\&.disconnected\&.fd // socket descriptor
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+.SH "RETURN VALUE"
+.sp
+The \fIzmq_socket_monitor()\fR function returns a value of 0 or greater if successful\&. Otherwise it returns \-1 and sets \fIerrno\fR to one of the values defined below\&.
+.SH "ERRORS"
+.PP
+\fBETERM\fR
+.RS 4
+The 0MQ
+\fIcontext\fR
+associated with the specified
+\fIsocket\fR
+was terminated\&.
+.RE
+.PP
+\fBEPROTONOSUPPORT\fR
+.RS 4
+The requested
+\fItransport\fR
+protocol is not supported\&. Monitor sockets are required to use the inproc:// transport\&.
+.RE
+.PP
+\fBEINVAL\fR
+.RS 4
+The endpoint supplied is invalid\&.
+.RE
+.SH "EXAMPLE"
+.PP
+\fBObserving a REP socket\(cqs connection state\fR. 
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+// REP socket monitor thread
+static void *rep_socket_monitor (void *ctx)
+{
+    zmq_event_t event;
+    int rc;
+
+    void *s = zmq_socket (ctx, ZMQ_PAIR);
+    assert (s);
+
+    rc = zmq_connect (s, "inproc://monitor\&.rep");
+    assert (rc == 0);
+    while (true) {
+        zmq_msg_t msg;
+        zmq_msg_init (&msg);
+        rc = zmq_recvmsg (s, &msg, 0);
+        if (rc == \-1 && zmq_errno() == ETERM) break;
+        assert (rc != \-1);
+        memcpy (&event, zmq_msg_data (&msg), sizeof (event));
+        switch (event\&.event) {
+        case ZMQ_EVENT_LISTENING:
+            printf ("listening socket descriptor %d\en", event\&.data\&.listening\&.fd);
+            printf ("listening socket address %s\en", event\&.data\&.listening\&.addr);
+            break;
+        case ZMQ_EVENT_ACCEPTED:
+            printf ("accepted socket descriptor %d\en", event\&.data\&.accepted\&.fd);
+            printf ("accepted socket address %s\en", event\&.data\&.accepted\&.addr);
+            break;
+        case ZMQ_EVENT_CLOSE_FAILED:
+            printf ("socket close failure error code %d\en", event\&.data\&.close_failed\&.err);
+            printf ("socket address %s\en", event\&.data\&.close_failed\&.addr);
+            break;
+        case ZMQ_EVENT_CLOSED:
+            printf ("closed socket descriptor %d\en", event\&.data\&.closed\&.fd);
+            printf ("closed socket address %s\en", event\&.data\&.closed\&.addr);
+            break;
+        case ZMQ_EVENT_DISCONNECTED:
+            printf ("disconnected socket descriptor %d\en", event\&.data\&.disconnected\&.fd);
+            printf ("disconnected socket address %s\en", event\&.data\&.disconnected\&.addr);
+            break;
+        }
+        zmq_msg_close (&msg);
+    }
+    zmq_close (s);
+    return NULL;
+}
+
+
+//  Create the infrastructure
+void *ctx = zmq_init (1);
+assert (ctx);
+
+// REP socket
+rep = zmq_socket (ctx, ZMQ_REP);
+assert (rep);
+
+// REP socket monitor, all events
+rc = zmq_socket_monitor (rep, "inproc://monitor\&.rep", ZMQ_EVENT_ALL);
+assert (rc == 0);
+rc = pthread_create (&threads [0], NULL, rep_socket_monitor, ctx);
+assert (rc == 0);
+
+rc = zmq_bind (rep, addr);
+assert (rc == 0);
+
+// Allow some time for event detection
+zmq_sleep (1);
+
+// Close the REP socket
+rc = zmq_close (rep);
+assert (rc == 0);
+
+zmq_term (ctx);
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+.SH "SEE ALSO"
+.sp
+\fBzmq\fR(7)
+.SH "AUTHORS"
+.sp
+This 0MQ manual page was written by Lourens Naud\('e <\m[blue]\fBlourens@methodmissing\&.com\fR\m[]\&\s-2\u[1]\d\s+2>
+.SH "NOTES"
+.IP " 1." 4
+lourens@methodmissing.com
+.RS 4
+\%mailto:lourens@methodmissing.com
+.RE