rbczmq 1.6.2 → 1.6.4

data/ext/czmq/doc/zloop.txt

@@ -0,0 +1,106 @@
+zloop(3)
+========
+
+NAME
+----
+zloop - event-driven reactor
+
+SYNOPSIS
+--------
+----
+//  Callback function for reactor events
+typedef int (zloop_fn) (zloop_t *loop, zmq_pollitem_t *item, void *arg);
+
+//  Create a new zloop reactor
+CZMQ_EXPORT zloop_t *
+    zloop_new (void);
+
+//  Destroy a reactor
+CZMQ_EXPORT void
+    zloop_destroy (zloop_t **self_p);
+
+//  Register pollitem with the reactor. When the pollitem is ready, will call
+//  the handler, passing the arg. Returns 0 if OK, -1 if there was an error.
+//  If you register the pollitem more than once, each instance will invoke its
+//  corresponding handler.
+CZMQ_EXPORT int
+    zloop_poller (zloop_t *self, zmq_pollitem_t *item, zloop_fn handler, void *arg);
+
+//  Cancel a pollitem from the reactor, specified by socket or FD. If both
+//  are specified, uses only socket. If multiple poll items exist for same
+//  socket/FD, cancels ALL of them.
+CZMQ_EXPORT void
+    zloop_poller_end (zloop_t *self, zmq_pollitem_t *item);
+
+//  Register a timer that expires after some delay and repeats some number of
+//  times. At each expiry, will call the handler, passing the arg. To
+//  run a timer forever, use 0 times. Returns 0 if OK, -1 if there was an
+//  error.
+CZMQ_EXPORT int
+    zloop_timer (zloop_t *self, size_t delay, size_t times, zloop_fn handler, void *arg);
+
+//  Cancel all timers for a specific argument (as provided in zloop_timer)
+CZMQ_EXPORT int
+    zloop_timer_end (zloop_t *self, void *arg);
+
+//  Set verbose tracing of reactor on/off
+CZMQ_EXPORT void
+    zloop_set_verbose (zloop_t *self, bool verbose);
+
+//  Start the reactor. Takes control of the thread and returns when the 0MQ
+//  context is terminated or the process is interrupted, or any event handler
+//  returns -1. Event handlers may register new sockets and timers, and
+//  cancel sockets. Returns 0 if interrupted, -1 if cancelled by a handler.
+CZMQ_EXPORT int
+    zloop_start (zloop_t *self);
+
+//  Self test of this class
+CZMQ_EXPORT void
+    zloop_test (bool verbose);
+----
+
+DESCRIPTION
+-----------
+
+The zloop class provides an event-driven reactor pattern. The reactor
+handles zmq_pollitem_t items (pollers or writers, sockets or fds), and
+once-off or repeated timers. Its resolution is 1 msec. It uses a tickless
+timer to reduce CPU interrupts in inactive processes.
+
+
+EXAMPLE
+-------
+.From zloop_test method
+----
+    zctx_t *ctx = zctx_new ();
+    assert (ctx);
+
+    void *output = zsocket_new (ctx, ZMQ_PAIR);
+    assert (output);
+    zsocket_bind (output, "inproc://zloop.test");
+    void *input = zsocket_new (ctx, ZMQ_PAIR);
+    assert (input);
+    zsocket_connect (input, "inproc://zloop.test");
+
+    zloop_t *loop = zloop_new ();
+    assert (loop);
+    zloop_set_verbose (loop, verbose);
+
+    //  After 10 msecs, send a ping message to output
+    zloop_timer (loop, 10, 1, s_timer_event, output);
+    
+    //  When we get the ping message, end the reactor
+    zmq_pollitem_t poll_input = { input, 0, ZMQ_POLLIN };
+    rc = zloop_poller (loop, &poll_input, s_socket_event, NULL);
+    assert (rc == 0);
+    zloop_start (loop);
+
+    zloop_destroy (&loop);
+    assert (loop == NULL);
+
+    zctx_destroy (&ctx);
+----
+
+SEE ALSO
+--------
+linkczmq:czmq[7]

data/ext/czmq/doc/zmsg.txt

@@ -0,0 +1,315 @@
+zmsg(3)
+=======
+
+NAME
+----
+zmsg - working with multipart messages
+
+SYNOPSIS
+--------
+----
+//  Create a new empty message object
+CZMQ_EXPORT zmsg_t *
+    zmsg_new (void);
+
+//  Destroy a message object and all frames it contains
+CZMQ_EXPORT void
+    zmsg_destroy (zmsg_t **self_p);
+
+//  Read 1 or more frames off the socket, into a new message object
+CZMQ_EXPORT zmsg_t *
+    zmsg_recv (void *socket);
+
+//  Send a message to the socket, and then destroy it
+CZMQ_EXPORT int
+    zmsg_send (zmsg_t **self_p, void *socket);
+
+//  Return number of frames in message
+CZMQ_EXPORT size_t
+    zmsg_size (zmsg_t *self);
+
+//  Return combined size of all frames in message
+CZMQ_EXPORT size_t
+    zmsg_content_size (zmsg_t *self);
+
+//  Push frame to front of message, before first frame
+CZMQ_EXPORT int
+    zmsg_push (zmsg_t *self, zframe_t *frame);
+
+//  Pop frame off front of message, caller now owns frame
+CZMQ_EXPORT zframe_t *
+    zmsg_pop (zmsg_t *self);
+
+//  Add frame to end of message, after last frame
+CZMQ_EXPORT int
+    zmsg_add (zmsg_t *self, zframe_t *frame);
+
+//  Push block of memory as new frame to front of message.
+//  Returns 0 on success, -1 on error.
+CZMQ_EXPORT int
+    zmsg_pushmem (zmsg_t *self, const void *src, size_t size);
+
+//  Push block of memory as new frame to end of message.
+//  Returns 0 on success, -1 on error.
+CZMQ_EXPORT int
+    zmsg_addmem (zmsg_t *self, const void *src, size_t size);
+    
+//  Push block of memory as new frame to end of message.
+//  The frame is constructed using zero-copy.
+//  Returns 0 on success, -1 on error.
+CZMQ_EXPORT int
+    zmsg_addmem_zero_copy (zmsg_t *self, void *src, size_t size, zframe_free_fn *free_fn, void *arg);
+
+//  Push string as new frame to front of message.
+//  Returns 0 on success, -1 on error.
+CZMQ_EXPORT int
+    zmsg_pushstr (zmsg_t *self, const char *format, ...);
+
+//  Push string as new frame to end of message.
+//  Returns 0 on success, -1 on error.
+CZMQ_EXPORT int
+    zmsg_addstr (zmsg_t *self, const char *format, ...);
+
+//  Pop frame off front of message, return as fresh string
+CZMQ_EXPORT char *
+    zmsg_popstr (zmsg_t *self);
+
+//  Push frame to front of message, before first frame
+//  Pushes an empty frame in front of frame
+CZMQ_EXPORT void
+    zmsg_wrap (zmsg_t *self, zframe_t *frame);
+
+//  Pop frame off front of message, caller now owns frame
+//  If next frame is empty, pops and destroys that empty frame.
+CZMQ_EXPORT zframe_t *
+    zmsg_unwrap (zmsg_t *self);
+
+//  Remove frame from message, at any position, caller owns it
+CZMQ_EXPORT void
+    zmsg_remove (zmsg_t *self, zframe_t *frame);
+
+//  Return first frame in message, or null
+CZMQ_EXPORT zframe_t *
+    zmsg_first (zmsg_t *self);
+
+//  Return next frame in message, or null
+CZMQ_EXPORT zframe_t *
+    zmsg_next (zmsg_t *self);
+
+//  Return last frame in message, or null
+CZMQ_EXPORT zframe_t *
+    zmsg_last (zmsg_t *self);
+
+//  Save message to an open file, return 0 if OK, else -1.
+CZMQ_EXPORT int
+    zmsg_save (zmsg_t *self, FILE *file);
+
+//  Load/append an open file into message, create new message if
+//  null message provided.
+CZMQ_EXPORT zmsg_t *
+    zmsg_load (zmsg_t *self, FILE *file);
+
+//  Encode message to a new buffer, return buffer size
+CZMQ_EXPORT size_t
+    zmsg_encode (zmsg_t *self, byte **buffer);
+
+//  Decode a buffer into a new message, returns NULL if buffer is not
+//  properly formatted.
+CZMQ_EXPORT zmsg_t *
+    zmsg_decode (byte *buffer, size_t buffer_size);
+
+//  Create copy of message, as new message object
+CZMQ_EXPORT zmsg_t *
+    zmsg_dup (zmsg_t *self);
+
+//  Print message to stderr, for debugging
+CZMQ_EXPORT void
+    zmsg_dump (zmsg_t *self);
+
+//  Self test of this class
+CZMQ_EXPORT int
+    zmsg_test (bool verbose);
+----
+
+DESCRIPTION
+-----------
+
+The zmsg class provides methods to send and receive multipart messages
+across 0MQ sockets. This class provides a list-like container interface,
+with methods to work with the overall container. zmsg_t messages are
+composed of zero or more zframe_t frames.
+
+
+EXAMPLE
+-------
+.From zmsg_test method
+----
+    zctx_t *ctx = zctx_new ();
+    assert (ctx);
+
+    void *output = zsocket_new (ctx, ZMQ_PAIR);
+    assert (output);
+    zsocket_bind (output, "inproc://zmsg.test");
+    void *input = zsocket_new (ctx, ZMQ_PAIR);
+    assert (input);
+    zsocket_connect (input, "inproc://zmsg.test");
+
+    //  Test send and receive of single-frame message
+    zmsg_t *msg = zmsg_new ();
+    assert (msg);
+    zframe_t *frame = zframe_new ("Hello", 5);
+    assert (frame);
+    zmsg_push (msg, frame);
+    assert (zmsg_size (msg) == 1);
+    assert (zmsg_content_size (msg) == 5);
+    rc = zmsg_send (&msg, output);
+    assert (msg == NULL);
+    assert (rc == 0);
+
+    msg = zmsg_recv (input);
+    assert (msg);
+    assert (zmsg_size (msg) == 1);
+    assert (zmsg_content_size (msg) == 5);
+    zmsg_destroy (&msg);
+
+    //  Test send and receive of multi-frame message
+    msg = zmsg_new ();
+    assert (msg);
+    rc = zmsg_addmem (msg, "Frame0", 6);
+    assert (rc == 0);
+    rc = zmsg_addmem (msg, "Frame1", 6);
+    assert (rc == 0);
+    rc = zmsg_addmem (msg, "Frame2", 6);
+    assert (rc == 0);
+    rc = zmsg_addmem (msg, "Frame3", 6);
+    assert (rc == 0);
+    rc = zmsg_addmem (msg, "Frame4", 6);
+    assert (rc == 0);
+    rc = zmsg_addmem (msg, "Frame5", 6);
+    assert (rc == 0);
+    rc = zmsg_addmem (msg, "Frame6", 6);
+    assert (rc == 0);
+    rc = zmsg_addmem (msg, "Frame7", 6);
+    assert (rc == 0);
+    rc = zmsg_addmem (msg, "Frame8", 6);
+    assert (rc == 0);
+    rc = zmsg_addmem (msg, "Frame9", 6);
+    assert (rc == 0);
+    zmsg_t *copy = zmsg_dup (msg);
+    assert (copy);
+    rc = zmsg_send (&copy, output);
+    assert (rc == 0);
+    rc = zmsg_send (&msg, output);
+    assert (rc == 0);
+
+    copy = zmsg_recv (input);
+    assert (copy);
+    assert (zmsg_size (copy) == 10);
+    assert (zmsg_content_size (copy) == 60);
+    zmsg_destroy (&copy);
+
+    msg = zmsg_recv (input);
+    assert (msg);
+    assert (zmsg_size (msg) == 10);
+    assert (zmsg_content_size (msg) == 60);
+    if (verbose)
+        zmsg_dump (msg);
+
+    //  Save to a file, read back
+    FILE *file = fopen ("zmsg.test", "w");
+    assert (file);
+    rc = zmsg_save (msg, file);
+    assert (rc == 0);
+    fclose (file);
+
+    file = fopen ("zmsg.test", "r");
+    rc = zmsg_save (msg, file);
+    assert (rc == -1);
+    fclose (file);
+    zmsg_destroy (&msg);
+
+    file = fopen ("zmsg.test", "r");
+    msg = zmsg_load (NULL, file);
+    assert (msg);
+    fclose (file);
+    remove ("zmsg.test");
+    assert (zmsg_size (msg) == 10);
+    assert (zmsg_content_size (msg) == 60);
+
+    //  Remove all frames except first and last
+    int frame_nbr;
+    for (frame_nbr = 0; frame_nbr < 8; frame_nbr++) {
+        zmsg_first (msg);
+        frame = zmsg_next (msg);
+        zmsg_remove (msg, frame);
+        zframe_destroy (&frame);
+    }
+    //  Test message frame manipulation
+    assert (zmsg_size (msg) == 2);
+    frame = zmsg_last (msg);
+    assert (zframe_streq (frame, "Frame9"));
+    assert (zmsg_content_size (msg) == 12);
+    frame = zframe_new ("Address", 7);
+    assert (frame);
+    zmsg_wrap (msg, frame);
+    assert (zmsg_size (msg) == 4);
+    rc = zmsg_addstr (msg, "Body");
+    assert (rc == 0);
+    assert (zmsg_size (msg) == 5);
+    frame = zmsg_unwrap (msg);
+    zframe_destroy (&frame);
+    assert (zmsg_size (msg) == 3);
+    char *body = zmsg_popstr (msg);
+    assert (streq (body, "Frame0"));
+    free (body);
+    zmsg_destroy (&msg);
+
+    //  Test encoding/decoding
+    msg = zmsg_new ();
+    assert (msg);
+    byte *blank = (byte *) zmalloc (100000);
+    assert (blank);
+    rc = zmsg_addmem (msg, blank, 0);
+    assert (rc == 0);
+    rc = zmsg_addmem (msg, blank, 1);
+    assert (rc == 0);
+    rc = zmsg_addmem (msg, blank, 253);
+    assert (rc == 0);
+    rc = zmsg_addmem (msg, blank, 254);
+    assert (rc == 0);
+    rc = zmsg_addmem (msg, blank, 255);
+    assert (rc == 0);
+    rc = zmsg_addmem (msg, blank, 256);
+    assert (rc == 0);
+    rc = zmsg_addmem (msg, blank, 65535);
+    assert (rc == 0);
+    rc = zmsg_addmem (msg, blank, 65536);
+    assert (rc == 0);
+    rc = zmsg_addmem (msg, blank, 65537);
+    assert (rc == 0);
+    free (blank);
+    assert (zmsg_size (msg) == 9);
+    byte *buffer;
+    size_t buffer_size = zmsg_encode (msg, &buffer);
+    zmsg_destroy (&msg);
+    msg = zmsg_decode (buffer, buffer_size);
+    assert (msg);
+    free (buffer);
+    zmsg_destroy (&msg);
+
+    //  Now try methods on an empty message
+    msg = zmsg_new ();
+    assert (msg);
+    assert (zmsg_size (msg) == 0);
+    assert (zmsg_first (msg) == NULL);
+    assert (zmsg_last (msg) == NULL);
+    assert (zmsg_next (msg) == NULL);
+    assert (zmsg_pop (msg) == NULL);
+    zmsg_destroy (&msg);
+
+    zctx_destroy (&ctx);
+----
+
+SEE ALSO
+--------
+linkczmq:czmq[7]

data/ext/czmq/doc/zmutex.txt

@@ -0,0 +1,54 @@
+zmutex(3)
+=========
+
+NAME
+----
+zmutex - working with mutexes
+
+SYNOPSIS
+--------
+----
+//  Create a new mutex container
+CZMQ_EXPORT zmutex_t *
+    zmutex_new (void);
+
+//  Destroy a mutex container
+CZMQ_EXPORT void
+    zmutex_destroy (zmutex_t **self_p);
+
+//  Lock mutex
+CZMQ_EXPORT void
+    zmutex_lock (zmutex_t *self);
+
+//  Unlock mutex
+CZMQ_EXPORT void
+    zmutex_unlock (zmutex_t *self);
+
+//  Self test of this class
+CZMQ_EXPORT int
+    zmutex_test (bool verbose);
+----
+
+DESCRIPTION
+-----------
+
+The zmutex class provides a portable wrapper for mutexes. Please do not
+use this class to do multi-threading. It is for the rare case where you
+absolutely need thread-safe global state. This should happen in system
+code only. DO NOT USE THIS TO SHARE SOCKETS BETWEEN THREADS, OR DARK 
+THINGS WILL HAPPEN TO YOUR CODE.
+
+
+EXAMPLE
+-------
+.From zmutex_test method
+----
+    zmutex_t *mutex = zmutex_new ();
+    zmutex_lock (mutex);
+    zmutex_unlock (mutex);
+    zmutex_destroy (&mutex);
+----
+
+SEE ALSO
+--------
+linkczmq:czmq[7]