rbczmq 1.7.1 → 1.7.2

data/ext/zeromq/doc/zmq_socket.txt

@@ -71,11 +71,9 @@ sequence of _zmq_send(request)_ and subsequent _zmq_recv(reply)_ calls. Each
 request sent is round-robined among all _services_, and each reply received is
 matched with the last issued request.
 
-When a 'ZMQ_REQ' socket enters the 'mute' state due to having reached the
-high water mark for all _services_, or if there are no _services_ at all, then
-any linkzmq:zmq_send[3] operations on the socket shall block until the
-'mute' state ends or at least one _service_ becomes available for sending;
-messages are not discarded.
+If no services are available, then any send operation on the socket shall 
+block until at least one _service_ becomes available. The REQ socket shall
+not discard messages.
 
 [horizontal]
 .Summary of ZMQ_REQ characteristics
@@ -94,11 +92,7 @@ send replies to a _client_. This socket type allows only an alternating
 sequence of _zmq_recv(request)_ and subsequent _zmq_send(reply)_ calls. Each
 request received is fair-queued from among all _clients_, and each reply sent
 is routed to the _client_ that issued the last request. If the original
-requester doesn't exist any more the reply is silently discarded.
-
-When a 'ZMQ_REP' socket enters the 'mute' state due to having reached the
-high water mark for a _client_, then any replies sent to the _client_ in
-question shall be dropped until the mute state ends.
+requester does not exist any more the reply is silently discarded.
 
 [horizontal]
 .Summary of ZMQ_REP characteristics
@@ -107,7 +101,6 @@ Direction:: Bidirectional
 Send/receive pattern:: Receive, Send, Receive, Send, ...
 Incoming routing strategy:: Fair-queued
 Outgoing routing strategy:: Last peer
-Action in mute state:: Drop
 
 
 ZMQ_DEALER
@@ -126,8 +119,6 @@ When a 'ZMQ_DEALER' socket is connected to a 'ZMQ_REP' socket each message sent
 must consist of an empty message part, the _delimiter_, followed by one or more
 _body parts_.
 
-Deprecated alias: 'ZMQ_XREQ'.
-
 [horizontal]
 .Summary of ZMQ_DEALER characteristics
 Compatible peer sockets:: 'ZMQ_ROUTER', 'ZMQ_REP', 'ZMQ_DEALER'
@@ -147,7 +138,7 @@ message before passing it to the application. Messages received are fair-queued
 from among all connected peers. When sending messages a 'ZMQ_ROUTER' socket shall
 remove the first part of the message and use it to determine the _identity_ of
 the peer the message shall be routed to. If the peer does not exist anymore
-the message shall be silently discarded by default, unless 'ZMQ_ROUTER_BEHAVIOR'
+the message shall be silently discarded by default, unless 'ZMQ_ROUTER_MANDATORY'
 socket option is set to '1'.
 
 When a 'ZMQ_ROUTER' socket enters the 'mute' state due to having reached the
@@ -162,8 +153,6 @@ as seen by the application becomes: one or more _identity_ parts, _delimiter_
 part, one or more _body parts_. When sending replies to a 'ZMQ_REQ' socket the
 application must include the _delimiter_ part.
 
-Deprecated alias: 'ZMQ_XREP'.
-
 [horizontal]
 .Summary of ZMQ_ROUTER characteristics
 Compatible peer sockets:: 'ZMQ_DEALER', 'ZMQ_REQ', 'ZMQ_ROUTER'
@@ -216,7 +205,6 @@ Direction:: Unidirectional
 Send/receive pattern:: Receive only
 Incoming routing strategy:: Fair-queued
 Outgoing routing strategy:: N/A
-Action in mute state:: Drop
 
 
 ZMQ_XPUB
@@ -224,7 +212,8 @@ ZMQ_XPUB
 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.
+body. Messages without a sub/unsub prefix are also received, but have no
+effect on subscription status.
 
 [horizontal]
 .Summary of ZMQ_XPUB characteristics
@@ -240,7 +229,8 @@ ZMQ_XSUB
 ^^^^^^^^
 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.
+(for unsubscriptions) followed by the subscription body. Messages without a
+sub/unsub prefix may also be sent, but have no effect on subscription status.
 
 [horizontal]
 .Summary of ZMQ_XSUB characteristics
@@ -333,6 +323,49 @@ Outgoing routing strategy:: N/A
 Action in mute state:: Block
 
 
+Native Pattern
+~~~~~~~~~~~~~~
+The native pattern is used for communicating with TCP peers and allows 
+asynchronous requests and replies in either direction.
+
+
+ZMQ_STREAM
+^^^^^^^^^^
+A socket of type 'ZMQ_STREAM' is used to send and receive TCP data from a 
+non-0MQ peer, when using the tcp:// transport. A 'ZMQ_STREAM' socket can 
+act as client and/or server, sending and/or receiving TCP data asynchronously.
+
+When receiving TCP data, a 'ZMQ_STREAM' socket shall prepend a message part
+containing the _identity_ 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 TCP data, a 'ZMQ_STREAM' socket shall remove the first part of the 
+message and use it to determine the _identity_ of the peer the message shall be 
+routed to, and unroutable messages shall cause an EHOSTUNREACH or EAGAIN error.
+
+To open a connection to a server, use the zmq_connect call, and then fetch the 
+socket identity using the ZMQ_IDENTITY zmq_getsockopt call.
+
+To close a specific client connection, as a server, send the identity frame
+followed by a zero-length message (see EXAMPLE section).
+
+The ZMQ_MSGMORE flag is ignored on data frames. You must send one identity frame
+followed by one data frame.
+
+Also, please note that omitting the ZMQ_MSGMORE flag will prevent sending further
+data (from any client) on the same socket.
+
+[horizontal]
+.Summary of ZMQ_STREAM characteristics
+Compatible peer sockets:: none.
+Direction:: Bidirectional
+Send/receive pattern:: Unrestricted
+Outgoing routing strategy:: See text
+Incoming routing strategy:: Fair-queued
+Action in mute state:: EAGAIN
+
+
 RETURN VALUE
 ------------
 The _zmq_socket()_ function shall return an opaque handle to the newly created
@@ -351,6 +384,44 @@ The limit on the total number of open 0MQ sockets has been reached.
 *ETERM*::
 The context specified was terminated.
 
+EXAMPLE
+-------
+.Creating a simple HTTP server using ZMQ_STREAM
+----
+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 ID */
+uint8_t id [256];
+size_t id_size = 256;
+while (1) {
+	/*  Get HTTP request; ID frame and then request */
+	id_size = zmq_recv (server, id, 256, 0);
+	assert (id_size > 0);
+	/* 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 ID frame followed by the response */
+	zmq_send (socket, id, id_size, ZMQ_SNDMORE);
+	zmq_send (socket, http_response, strlen (http_response), ZMQ_SNDMORE);
+	/* Closes the connection by sending the ID frame followed by a zero response */
+	zmq_send (socket, id, id_size, ZMQ_SNDMORE);
+	zmq_send (socket, 0, 0, ZMQ_SNDMORE);
+	/* NOTE: If we don't use ZMQ_SNDMORE, then we won't be able to send more */
+	/* message to any client */
+}
+zmq_close (socket);
+zmq_ctx_destroy (ctx);
+----
+
+
 SEE ALSO
 --------
 linkzmq:zmq_init[3]
@@ -365,5 +436,5 @@ linkzmq:zmq[7]
 
 AUTHORS
 -------
-This 0MQ manual page was written by Martin Sustrik <sustrik@250bpm.com>,
-Martin Lucina <mato@kotelna.sk>, and Pieter Hintjens <ph@imatix.com>.
+This page was written by the 0MQ community. To make a change please
+read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.

data/ext/zeromq/doc/zmq_socket_monitor.txt

@@ -17,168 +17,100 @@ DESCRIPTION
 -----------
 The _zmq_socket_monitor()_ function shall spawn a 'PAIR' socket that publishes
 socket state changes (events) over the inproc:// transport to a given endpoint.
-Messages are 'zmq_event_t' structs. It's recommended to connect via a 'PAIR'
-socket in another application thread and handle monitoring events there. It's
-possible to also supply a bitmask ('ZMQ_EVENT_ALL' or any combination of the
-'ZMQ_EVENT_*' constants) of the events you're interested in.
 
-----
-// monitoring thread
-static void *req_socket_monitor (void *ctx)
-{
-    zmq_event_t event;
-    int rc;
+Messages consist of 2 Frames, the first containing the event-id and the
+associated value. The second frame holds the affected endpoint as string.
 
-    void *s = zmq_socket (ctx, ZMQ_PAIR);
-    assert (s);
+The layout of the first Frame is:
+  16 bit event id
+  32 bit event value
 
-    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;
-}
+event id and value are in the native byte order (for the machine the
+application is running on). There is no padding between the fields.
 
-// register a monitor endpoint for all socket events
-rc = zmq_socket_monitor (req, "inproc://monitor.req", ZMQ_EVENT_ALL);
-assert (rc == 0);
+The event value has to be interpreted in the context of the event id.
+See 'Supported events' below for details.
 
-// spawn a monitoring thread
-rc = pthread_create (&threads [0], NULL, req_socket_monitor, ctx);
-assert (rc == 0);
 ----
 
 Only connection oriented (tcp and ipc) transports are supported in this initial
 implementation.
 
-Supported events are:
+----
 
+Supported events
+----------------
 
 ZMQ_EVENT_CONNECTED: connection established
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 The 'ZMQ_EVENT_CONNECTED' event triggers when a connection has been established
 to a remote peer. This can happen either synchronous or asynchronous.
+Value is the FD of the newly connected socket.
 
-.Event metadata:
-----
-data.connected.addr // peer address
-data.connected.fd // socket descriptor
-----
 
 ZMQ_EVENT_CONNECT_DELAYED: synchronous connect failed, it's being polled
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 The 'ZMQ_EVENT_CONNECT_DELAYED' event triggers when an immediate connection
-attempt is delayed and it's completion's being polled for.
+attempt is delayed and its completion is being polled for.
+Value has no meaning.
 
-.Event metadata:
-----
-data.connect_delayed.addr // peer address
-data.connect_delayed.err // errno value
-----
 
 ZMQ_EVENT_CONNECT_RETRIED: asynchronous connect / reconnection attempt
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 The 'ZMQ_EVENT_CONNECT_RETRIED' event triggers when a connection attempt
 is being handled by reconnect timer. The reconnect interval's recomputed
 for each attempt.
+Value is the reconnect interval.
 
-.Event metadata:
-----
-data.connect_retried.addr // peer address
-data.connect_retried.interval // computed reconnect interval
-----
 
 ZMQ_EVENT_LISTENING: socket bound to an address, ready to accept connections
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 The 'ZMQ_EVENT_LISTENING' event triggers when a socket's successfully bound
 to a an interface.
+Value is the FD of the newly bound socket.
 
-.Event metadata:
-----
-data.listening.addr //  listen address
-data.listening.fd // socket descriptor
-----
 
 ZMQ_EVENT_BIND_FAILED: socket could not bind to an address
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 The 'ZMQ_EVENT_BIND_FAILED' event triggers when a socket could not bind to
 a given interface.
+Value is the errno generated by the bind call.
 
-.Event metadata:
-----
-data.bind_failed.addr // listen address
-data.bind_failed.err // errno value
-----
 
 ZMQ_EVENT_ACCEPTED: connection accepted to bound interface
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 The 'ZMQ_EVENT_ACCEPTED' event triggers when a connection from a remote peer
 has been established with a socket's listen address.
+Value is the FD of the accepted socket.
 
-.Event metadata:
-----
-data.accepted.addr // listen address
-data.accepted.fd // socket descriptor
-----
 
 ZMQ_EVENT_ACCEPT_FAILED: could not accept client connection
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 The 'ZMQ_EVENT_ACCEPT_FAILED' event triggers when a connection attempt to
 a socket's bound address fails.
+Value is the errno generated by accept.
 
-.Event metadata:
-----
-data.accept_failed.addr // listen address
-data.accept_failed.err // errno value
-----
 
 ZMQ_EVENT_CLOSED: connection closed
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 The 'ZMQ_EVENT_CLOSED' event triggers when a connection's underlying descriptor
-has been closed. 
+has been closed.
+Value is the former FD of the for the closed socket. FD has been closed already!
 
-.Event metadata:
-----
-data.closed.addr // address
-data.closed.fd // socket descriptor
-----
 
 ZMQ_EVENT_CLOSE_FAILED: connection couldn't be closed
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 The 'ZMQ_EVENT_CLOSE_FAILED' event triggers when a descriptor could not be
-released back to the OS.
+released back to the OS. Implementation note: ONLY FOR IPC SOCKETS.
+Value is the errno generated by unlink.
 
-.Event metadata:
-----
-data.close_failed.addr // address
-data.close_failed.err // errno value
-----
 
 ZMQ_EVENT_DISCONNECTED: broken session
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 The 'ZMQ_EVENT_DISCONNECTED' event triggers when the stream engine (tcp and ipc
 specific) detects a corrupted / broken session.
+Value is the FD of the socket.
 
-.Event metadata:
-----
-data.disconnected.addr // address
-data.disconnected.fd // socket descriptor
-----
 
 RETURN VALUE
 ------------
@@ -203,78 +135,116 @@ EXAMPLE
 -------
 .Observing a 'REP' socket's connection state 
 ----
+#include <stdio.h>
+#include <zmq.h>
+#include <pthread.h>
+#include <string.h>
+#include <assert.h>
+
+static int read_msg(void* s, zmq_event_t* event, char* ep)
+{
+    int rc ;
+    zmq_msg_t msg1;  // binary part
+    zmq_msg_init (&msg1);
+    zmq_msg_t msg2;  //  address part
+    zmq_msg_init (&msg2);
+    rc = zmq_msg_recv (&msg1, s, 0);
+    if (rc == -1 && zmq_errno() == ETERM)
+	return 1 ;
+    assert (rc != -1);
+    assert (zmq_msg_more(&msg1) != 0);
+    rc = zmq_msg_recv (&msg2, s, 0);
+    if (rc == -1 && zmq_errno() == ETERM)
+	return 1;
+    assert (rc != -1);
+    assert (zmq_msg_more(&msg2) == 0);
+    // copy binary data to event struct
+    const char* data = (char*)zmq_msg_data(&msg1);
+    memcpy(&(event->event), data, sizeof(event->event));
+    memcpy(&(event->value), data+sizeof(event->event), sizeof(event->value));
+    // copy address part
+    const size_t len = zmq_msg_size(&msg2) ;
+    ep = memcpy(ep, zmq_msg_data(&msg2), len);
+    *(ep + len) = 0 ;
+    return 0 ;
+}
+
 // REP socket monitor thread
 static void *rep_socket_monitor (void *ctx)
 {
     zmq_event_t event;
+    static char addr[1025] ;
     int rc;
 
+    printf("starting monitor...\n");
+
     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));
+    while (!read_msg(s, &event, addr)) {
         switch (event.event) {
         case ZMQ_EVENT_LISTENING:
-            printf ("listening socket descriptor %d\n", event.data.listening.fd);
-            printf ("listening socket address %s\n", event.data.listening.addr);
+            printf ("listening socket descriptor %d\n", event.value);
+            printf ("listening socket address %s\n", addr);
             break;
         case ZMQ_EVENT_ACCEPTED:
-            printf ("accepted socket descriptor %d\n", event.data.accepted.fd);
-            printf ("accepted socket address %s\n", event.data.accepted.addr);
+            printf ("accepted socket descriptor %d\n", event.value);
+            printf ("accepted socket address %s\n", addr);
             break;
         case ZMQ_EVENT_CLOSE_FAILED:
-            printf ("socket close failure error code %d\n", event.data.close_failed.err);
-            printf ("socket address %s\n", event.data.close_failed.addr);
+            printf ("socket close failure error code %d\n", event.value);
+            printf ("socket address %s\n", addr);
             break;
         case ZMQ_EVENT_CLOSED:
-            printf ("closed socket descriptor %d\n", event.data.closed.fd);
-            printf ("closed socket address %s\n", event.data.closed.addr);
+            printf ("closed socket descriptor %d\n", event.value);
+            printf ("closed socket address %s\n", addr);
             break;
         case ZMQ_EVENT_DISCONNECTED:
-            printf ("disconnected socket descriptor %d\n", event.data.disconnected.fd);
-            printf ("disconnected socket address %s\n", event.data.disconnected.addr);
+            printf ("disconnected socket descriptor %d\n", event.value);
+            printf ("disconnected socket address %s\n", addr);
             break;
         }
-        zmq_msg_close (&msg);
     }
     zmq_close (s);
     return NULL;
 }
 
 
-//  Create the infrastructure
-void *ctx = zmq_init (1);
-assert (ctx);
+int main()
+{
+    const char* addr = "tcp://127.0.0.1:6666" ;
+    pthread_t thread ;
+
+    //  Create the infrastructure
+    void *ctx = zmq_init (1);
+    assert (ctx);
+
+    // REP socket
+    void* rep = zmq_socket (ctx, ZMQ_REP);
+    assert (rep);
 
-// REP socket
-rep = zmq_socket (ctx, ZMQ_REP);
-assert (rep);
+    // REP socket monitor, all events
+    int rc = zmq_socket_monitor (rep, "inproc://monitor.rep", ZMQ_EVENT_ALL);
+    assert (rc == 0);
+    rc = pthread_create (&thread, NULL, rep_socket_monitor, ctx);
+    assert (rc == 0);
 
-// 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);
 
-rc = zmq_bind (rep, addr);
-assert (rc == 0);
+    // Allow some time for event detection
+    zmq_sleep (1);
 
-// Allow some time for event detection
-zmq_sleep (1);
+    // Close the REP socket
+    rc = zmq_close (rep);
+    assert (rc == 0);
 
-// Close the REP socket
-rc = zmq_close (rep);
-assert (rc == 0);
+    zmq_term (ctx);
 
-zmq_term (ctx);
+    return 0 ;
+}
 ----
 
 
@@ -285,4 +255,5 @@ linkzmq:zmq[7]
 
 AUTHORS
 -------
-This 0MQ manual page was written by Lourens Naudé <lourens@methodmissing.com>
+This page was written by the 0MQ community. To make a change please
+read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.