rbczmq 1.6.2 → 1.6.4

data/ext/czmq/doc/zstr.txt

@@ -0,0 +1,80 @@
+zstr(3)
+=======
+
+NAME
+----
+zstr - sending and receiving strings
+
+SYNOPSIS
+--------
+----
+//  Receive a string off a socket, caller must free it
+CZMQ_EXPORT char *
+    zstr_recv (void *socket);
+
+//  Receive a string off a socket if socket had input waiting
+CZMQ_EXPORT char *
+    zstr_recv_nowait (void *socket);
+
+//  Send a formatted string to a socket
+CZMQ_EXPORT int
+    zstr_send (void *socket, const char *format, ...);
+
+//  Send a formatted string to a socket, with MORE flag
+CZMQ_EXPORT int
+    zstr_sendm (void *socket, const char *format, ...);
+
+//  Self test of this class
+CZMQ_EXPORT int
+    zstr_test (bool verbose);
+----
+
+DESCRIPTION
+-----------
+
+The zstr class provides utility functions for sending and receiving C
+strings across 0MQ sockets. It sends strings without a terminating null,
+and appends a null byte on received strings. This class is for simple
+message sending.
+
+
+EXAMPLE
+-------
+.From zstr_test method
+----
+    zctx_t *ctx = zctx_new ();
+    assert (ctx);
+
+    void *output = zsocket_new (ctx, ZMQ_PAIR);
+    assert (output);
+    zsocket_bind (output, "inproc://zstr.test");
+    void *input = zsocket_new (ctx, ZMQ_PAIR);
+    assert (input);
+    zsocket_connect (input, "inproc://zstr.test");
+
+    //  Send ten strings, five strings with MORE flag and then END
+    int string_nbr;
+    for (string_nbr = 0; string_nbr < 10; string_nbr++)
+        zstr_send (output, "this is string %d", string_nbr);
+    for (string_nbr = 0; string_nbr < 5; string_nbr++)
+        zstr_sendm (output, "this is string %d", string_nbr);
+    zstr_send (output, "END");
+
+    //  Read and count until we receive END
+    string_nbr = 0;
+    for (string_nbr = 0;; string_nbr++) {
+        char *string = zstr_recv (input);
+        if (streq (string, "END")) {
+            free (string);
+            break;
+        }
+        free (string);
+    }
+    assert (string_nbr == 15);
+
+    zctx_destroy (&ctx);
+----
+
+SEE ALSO
+--------
+linkczmq:czmq[7]

data/ext/czmq/doc/zsys.txt

@@ -0,0 +1,44 @@
+zsys(3)
+=======
+
+NAME
+----
+zsys - system wrapper
+
+SYNOPSIS
+--------
+----
+//  Callback for interrupt signal handler
+typedef void (zsys_handler_fn) (int signal_value);
+
+//  Set interrupt handler (NULL means external handler)
+CZMQ_EXPORT void
+    zsys_handler_set (zsys_handler_fn *handler_fn);
+
+//  Reset interrupt handler, call this at exit if needed
+CZMQ_EXPORT void
+    zsys_handler_reset (void);
+
+//  Self test of this class
+CZMQ_EXPORT int
+    zsys_test (bool verbose);
+----
+
+DESCRIPTION
+-----------
+
+The zsys class provides a portable wrapper for miscellaneous functions
+that we want to wrap but which don't fit into any of the existing
+classes. Eventually all non-portable functionality might be moved here
+but for now it covers only file systems.
+
+
+EXAMPLE
+-------
+.From zsys_test method
+----
+----
+
+SEE ALSO
+--------
+linkczmq:czmq[7]

data/ext/czmq/doc/zthread.txt

@@ -0,0 +1,126 @@
+zthread(3)
+==========
+
+NAME
+----
+zthread - working with system threads
+
+SYNOPSIS
+--------
+----
+//  Detached threads follow POSIX pthreads API
+typedef void *(zthread_detached_fn) (void *args);
+
+//  Attached threads get context and pipe from parent
+typedef void (zthread_attached_fn) (void *args, zctx_t *ctx, void *pipe);
+
+//  Create a detached thread. A detached thread operates autonomously
+//  and is used to simulate a separate process. It gets no ctx, and no
+//  pipe.
+CZMQ_EXPORT int
+    zthread_new (zthread_detached_fn *thread_fn, void *args);
+
+//  Create an attached thread. An attached thread gets a ctx and a PAIR
+//  pipe back to its parent. It must monitor its pipe, and exit if the
+//  pipe becomes unreadable. Do not destroy the ctx, the thread does this
+//  automatically when it ends.
+CZMQ_EXPORT void *
+    zthread_fork (zctx_t *ctx, zthread_attached_fn *thread_fn, void *args);
+
+//  Self test of this class
+CZMQ_EXPORT int
+    zthread_test (bool verbose);
+----
+
+DESCRIPTION
+-----------
+
+The zthread class wraps OS thread creation. It creates detached threads
+that look like normal OS threads, or attached threads that share the
+caller's 0MQ context, and get an inproc pipe to talk back to the parent
+thread. Detached threads create their own 0MQ contexts as needed.
+
+We have several use cases for multiple threads. One is to simulate many
+processes, so we can test 0MQ designs and flows more easily. Another is
+to create APIs that can send and receive 0MQ messages in the background.
+
+zthread solves these two use cases separately, using the zthread_new
+and zthead_fork methods respectively. These methods wrap the native
+system calls needed to start threads, so your code can remain fully
+portable.
+
+Detached threads follow the POSIX pthreads API; they accept a void *
+argument and return a void * result (always NULL in our case).
+
+Attached thread receive a void * argument, a zctx_t context, and a pipe
+socket. The pipe socket is a PAIR socket that is connected back to the
+caller. When you call zthread_fork, it returns you a PAIR socket that
+is the other end of this pipe. Thus attached threads can talk back to
+their parent threads over the pipe. We use this very heavily when making
+so-called "asynchronous" APIs, which you can see in the Guide examples
+like 'clone'.
+
+To recap some rules about threading: do not share sockets between
+threads or your code will crash. You can migrate a socket from one
+thread to a child thread, if you stop using it in the parent thread
+immediately after creating the child thread. If you want to connect
+sockets over inproc:// they must share the same 0MQ context, i.e. be
+attached threads. You should always use zthread_fork to create an
+attached thread; it is not sufficient to pass a zctx_t structure to
+a detached thread (this will crash).
+
+If you want to communicate over ipc:// or tcp:// you may be sharing
+the same context, or use separate contexts. Thus, every detached thread
+usually starts by creating its own zctx_t instance.    
+
+EXAMPLE
+-------
+.From zthread_test method
+----
+static void *
+s_test_detached (void *args)
+{
+    //  Create a socket to check it'll be automatically deleted
+    zctx_t *ctx = zctx_new ();
+    assert (ctx);
+
+    void *push = zsocket_new (ctx, ZMQ_PUSH);
+    assert (push);
+    zctx_destroy (&ctx);
+    return NULL;
+}
+
+static void
+s_test_attached (void *args, zctx_t *ctx, void *pipe)
+{
+    //  Create a socket to check it'll be automatically deleted
+    zsocket_new (ctx, ZMQ_PUSH);
+    //  Wait for our parent to ping us, and pong back
+    free (zstr_recv (pipe));
+    zstr_send (pipe, "pong");
+}
+
+    zctx_t *ctx = zctx_new ();
+    assert (ctx);
+    int rc = 0;
+
+    //  Create a detached thread, let it run
+    rc = zthread_new (s_test_detached, NULL);
+    assert (rc == 0);
+    zclock_sleep (100);
+
+    //  Create an attached thread, check it's safely alive
+    void *pipe = zthread_fork (ctx, s_test_attached, NULL);
+    assert (pipe);
+    zstr_send (pipe, "ping");
+    char *pong = zstr_recv (pipe);
+    assert (streq (pong, "pong"));
+    free (pong);
+
+    //  Everything should be cleanly closed now
+    zctx_destroy (&ctx);
+----
+
+SEE ALSO
+--------
+linkczmq:czmq[7]

data/ext/czmq/doc/ztree.txt

@@ -0,0 +1,236 @@
+ztree(3)
+========
+
+NAME
+----
+ztree - generic type-free red-black tree container
+
+SYNOPSIS
+--------
+----
+//  Callback function for ztee_walk method
+typedef int (ztree_walk_fn) (const char *key, void *value, void *argument);
+
+//  Callback function for ztree_freefn method
+typedef void (ztree_free_fn) (void *data);
+
+//  Comparison function for ztree ordering
+//  returns -1 for key1 < key2, 0 if key1 == key 2, 1 for key1 > key2
+//  if key's are strings okay to use strcmp as function
+typedef int (ztree_compare_fn) (const char *key1, const char *key2);
+
+//  Create a new tree container
+CZMQ_EXPORT ztree_t *
+    ztree_new (ztree_compare_fn *compare_func);
+
+//  Destroy a tree container
+CZMQ_EXPORT void
+    ztree_destroy (ztree_t **self_p);
+
+//  Insert node into tree with specified key and value
+//  If key is already present returns -1 and leaves existing node unchanged
+//  Returns 0 on success.
+CZMQ_EXPORT int
+    ztree_insert (ztree_t *self, const char *key, void *value);
+
+//  Update node in tree with specified key and value.
+//  If key is already present, destroys old value and inserts new one.
+//  Use free_fn method to ensure deallocator is properly called on value.
+CZMQ_EXPORT void
+    ztree_update (ztree_t *self, const char *key, void *value);
+
+//  Remove a node specified by key from the tree. If there was no such
+//  node, this function does nothing.
+CZMQ_EXPORT void
+    ztree_delete (ztree_t *self, const char *key);
+
+//  Return the value at the specified key, or null
+CZMQ_EXPORT void *
+    ztree_lookup (ztree_t *self, const char *key);
+
+//  Set a free function for the specified tree node. When the value is
+//  destroyed, the free function, if any, is called on that node.
+//  Use this when tree values are dynamically allocated, to ensure that
+//  you don't have memory leaks. You can pass 'free' or NULL as a free_fn.
+//  Returns the item, or NULL if there is no such item.
+CZMQ_EXPORT void *
+    ztree_freefn (ztree_t *self, const char *key, ztree_free_fn *free_fn);
+
+//  Return the number of keys/values in the tree
+CZMQ_EXPORT size_t
+    ztree_size (ztree_t *self);
+
+//  Return keys for nodes in tree
+CZMQ_EXPORT zlist_t *
+    ztree_keys (ztree_t *self);
+
+//  Copy the entire tree, return the copy
+CZMQ_EXPORT ztree_t *
+    ztree_dup (ztree_t *self);
+
+// Walk the tree depth-first, left-to-right order.
+// Stops if callback function returns non-zero and returns
+// final return code from callback function (zero = success).
+CZMQ_EXPORT int
+    ztree_walk (ztree_t *self, ztree_walk_fn *callback, void *argument);
+
+//  Save tree to a text file in name=value format. Values must be
+//  printable strings; keys may not contain '=' character. Returns 0 if OK,
+//  else -1 if a file error occurred.
+CZMQ_EXPORT int
+    ztree_save (ztree_t *self, const char *filename);
+
+//  Load tree from a text file in name=value format; tree must
+//  already exist. Tree values must printable strings; keys may not contain
+//  '=' character. Returns 0 if OK, else -1 if a file was not readable.
+CZMQ_EXPORT int
+    ztree_load (ztree_t *self, const char *filename);
+
+//  Set tree for automatic value destruction
+CZMQ_EXPORT void
+    ztree_autofree (ztree_t *self);
+
+//  Self test of this class
+CZMQ_EXPORT void
+    ztree_test (int verbose);
+----
+
+DESCRIPTION
+-----------
+
+Red black tree container
+
+
+EXAMPLE
+-------
+.From ztree_test method
+----
+    ztree_t *tree = ztree_new (strcmp);
+    assert (tree);
+    assert (ztree_size (tree) == 0);
+
+    assert (ztree_lookup (tree, "NOTHING") == NULL);
+
+    //  Insert some nodes
+    int rc;
+    rc = ztree_insert (tree, "DEADBEEF", "dead beef");
+    assert (rc == 0);
+    rc = ztree_insert (tree, "ABADCAFE", "a bad cafe");
+    assert (rc == 0);
+    rc = ztree_insert (tree, "C0DEDBAD", "coded bad");
+    assert (rc == 0);
+    rc = ztree_insert (tree, "DEADF00D", "dead food");
+    assert (rc == 0);
+    assert (ztree_size (tree) == 4);
+
+    //  Look for existing nodes
+    char *value;
+    value = (char *) ztree_lookup (tree, "DEADBEEF");
+    assert (streq (value, "dead beef"));
+    value = (char *) ztree_lookup (tree, "ABADCAFE");
+    assert (streq (value, "a bad cafe"));
+    value = (char *) ztree_lookup (tree, "C0DEDBAD");
+    assert (streq (value, "coded bad"));
+    value = (char *) ztree_lookup (tree, "DEADF00D");
+    assert (streq (value, "dead food"));
+
+    //  Look for non-existent nodes
+    value = (char *) ztree_lookup (tree, "foo");
+    assert (value == NULL);
+
+    //  Try to insert duplicate nodes
+    rc = ztree_insert (tree, "DEADBEEF", "foo");
+    assert (rc == -1);
+    value = (char *) ztree_lookup (tree, "DEADBEEF");
+    assert (streq (value, "dead beef"));
+
+    //  Test keys method
+    zlist_t *keys = ztree_keys (tree);
+    assert (zlist_size (keys) == 4);
+
+    // Test that keys are in order
+    void *key, *pred;
+    pred = zlist_first (keys);
+    assert(pred);
+    while ((key = zlist_next (keys))) {
+	assert(strcmp(key, pred) > 0);
+	pred = key;
+    }
+    zlist_destroy (&keys);
+
+    //  Test dup method
+    ztree_t *copy = ztree_dup (tree);
+    assert (ztree_size (copy) == ztree_size (tree));
+    value = (char *) ztree_lookup (copy, "DEADF00D");
+    assert (value);
+    assert (streq (value, "dead food"));
+    ztree_destroy (&copy);
+
+    // Test walk
+    assert (0 == ztree_walk(tree, test_walk, tree));
+    assert (-1 == ztree_walk(tree, test_walk_error, tree));
+
+    //  Test save and load
+    ztree_save (tree, ".cache");
+    copy = ztree_new (strcasecmp);
+    ztree_load (copy, ".cache");
+    assert (ztree_size (copy) == ztree_size (tree));
+    value = (char *) ztree_lookup (copy, "DEADBEEF");
+    assert (value);
+    assert (streq (value, "dead beef"));
+    ztree_destroy (&copy);
+#if (defined (WIN32))
+    DeleteFile (".cache");
+#else
+    unlink (".cache");
+#endif
+
+    //  Delete some nodes
+    assert (ztree_size (tree) == 4);
+    ztree_delete (tree, "DEADF00D");
+    value = (char *) ztree_lookup (tree, "DEADF00D");
+    assert (value == NULL);
+    assert (ztree_size (tree) == 3);
+
+    ztree_delete (tree, "C0DEDBAD");
+    value = (char *) ztree_lookup (tree, "C0DEDBAD");
+    assert (value == NULL);
+    assert (ztree_size (tree) == 2);
+
+    //  Check that the queue is robust against random usage
+    struct {
+        char name [100];
+        bool exists;
+    } testset [200];
+    memset (testset, 0, sizeof (testset));
+    int testmax = 200, testnbr, iteration;
+
+    srandom ((unsigned) time (NULL));
+    for (iteration = 0; iteration < 25000; iteration++) {
+        testnbr = randof (testmax);
+        if (testset [testnbr].exists) {
+            value = (char *) ztree_lookup (tree, testset [testnbr].name);
+            assert (value);
+            ztree_delete (tree, testset [testnbr].name);
+            testset [testnbr].exists = false;
+        }
+        else {
+            sprintf (testset [testnbr].name, "%x-%x", rand (), rand ());
+            if (ztree_insert (tree, testset [testnbr].name, "") == 0)
+                testset [testnbr].exists = true;
+        }
+    }
+
+    //  Test 10K lookups
+    for (iteration = 0; iteration < 10000; iteration++)
+        value = (char *) ztree_lookup (tree, "DEADBEEFABADCAFE");
+
+    //  Destructor should be safe to call twice
+    ztree_destroy (&tree);
+    ztree_destroy (&tree);
+    assert (tree == NULL);
+----
+
+SEE ALSO
+--------
+linkczmq:czmq[7]