rbczmq 1.6.2 → 1.6.4

data/ext/czmq/doc/zframe.txt

@@ -0,0 +1,222 @@
+zframe(3)
+=========
+
+NAME
+----
+zframe - working with single message frames
+
+SYNOPSIS
+--------
+----
+#define ZFRAME_MORE     1
+#define ZFRAME_REUSE    2
+#define ZFRAME_DONTWAIT 4
+
+//  Create a new frame with optional size, and optional data
+CZMQ_EXPORT zframe_t *
+    zframe_new (const void *data, size_t size);
+
+//  Create an empty (zero-sized) frame
+CZMQ_EXPORT zframe_t *
+    zframe_new_empty (void);
+
+//  Destroy a frame
+CZMQ_EXPORT void
+    zframe_destroy (zframe_t **self_p);
+
+//  Receive frame from socket, returns zframe_t object or NULL if the recv
+//  was interrupted. Does a blocking recv, if you want to not block then use
+//  zframe_recv_nowait().
+CZMQ_EXPORT zframe_t *
+    zframe_recv (void *socket);
+
+//  Receive a new frame off the socket. Returns newly allocated frame, or
+//  NULL if there was no input waiting, or if the read was interrupted.
+CZMQ_EXPORT zframe_t *
+    zframe_recv_nowait (void *socket);
+
+// Send a frame to a socket, destroy frame after sending.
+// Return -1 on error, 0 on success.
+CZMQ_EXPORT int
+    zframe_send (zframe_t **self_p, void *socket, int flags);
+
+//  Return number of bytes in frame data
+CZMQ_EXPORT size_t
+    zframe_size (zframe_t *self);
+
+//  Return address of frame data
+CZMQ_EXPORT byte *
+    zframe_data (zframe_t *self);
+
+//  Create a new frame that duplicates an existing frame
+CZMQ_EXPORT zframe_t *
+    zframe_dup (zframe_t *self);
+
+//  Return frame data encoded as printable hex string
+CZMQ_EXPORT char *
+    zframe_strhex (zframe_t *self);
+
+//  Return frame data copied into freshly allocated string
+CZMQ_EXPORT char *
+    zframe_strdup (zframe_t *self);
+
+//  Return TRUE if frame body is equal to string, excluding terminator
+CZMQ_EXPORT bool
+    zframe_streq (zframe_t *self, const char *string);
+
+//  Return frame MORE indicator (1 or 0), set when reading frame from socket
+//  or by the zframe_set_more() method
+CZMQ_EXPORT int
+    zframe_more (zframe_t *self);
+
+//  Set frame MORE indicator (1 or 0). Note this is NOT used when sending 
+//  frame to socket, you have to specify flag explicitly.
+CZMQ_EXPORT void
+    zframe_set_more (zframe_t *self, int more);
+    
+//  Return TRUE if two frames have identical size and data
+//  If either frame is NULL, equality is always false.
+CZMQ_EXPORT bool
+    zframe_eq (zframe_t *self, zframe_t *other);
+
+//  Print contents of frame to stderr
+CZMQ_EXPORT void
+    zframe_print (zframe_t *self, const char *prefix);
+
+//  Set new contents for frame
+CZMQ_EXPORT void
+    zframe_reset (zframe_t *self, const void *data, size_t size);
+
+//  Callback function for zframe_free_fn method
+//  DEPRECATED - will be removed for next stable release
+typedef void (zframe_free_fn) (void *data, void *arg);
+
+//  Create a zero-copy frame
+//  DEPRECATED - will be removed for next stable release
+CZMQ_EXPORT zframe_t *
+    zframe_new_zero_copy (void *data, size_t size,
+                          zframe_free_fn *free_fn, void *arg);
+
+// Return frame zero copy indicator (1 or 0)
+//  DEPRECATED - will be removed for next stable release
+CZMQ_EXPORT int
+    zframe_zero_copy (zframe_t *self);
+
+//  Set the free callback for frame
+//  DEPRECATED - will be removed at next stable release
+CZMQ_EXPORT void
+    zframe_freefn (zframe_t *self, zframe_free_fn *free_fn, void *arg);
+
+//  Self test of this class
+CZMQ_EXPORT int
+    zframe_test (bool verbose);
+----
+
+DESCRIPTION
+-----------
+
+The zframe class provides methods to send and receive single message
+frames across 0MQ sockets. A 'frame' corresponds to one zmq_msg_t. When
+you read a frame from a socket, the zframe_more() method indicates if the
+frame is part of an unfinished multipart message. The zframe_send method
+normally destroys the frame, but with the ZFRAME_REUSE flag, you can send
+the same frame many times. Frames are binary, and this class has no
+special support for text data.
+
+
+EXAMPLE
+-------
+.From zframe_test method
+----
+    zctx_t *ctx = zctx_new ();
+    assert (ctx);
+    
+    void *output = zsocket_new (ctx, ZMQ_PAIR);
+    assert (output);
+    zsocket_bind (output, "inproc://zframe.test");
+    void *input = zsocket_new (ctx, ZMQ_PAIR);
+    assert (input);
+    zsocket_connect (input, "inproc://zframe.test");
+
+    //  Send five different frames, test ZFRAME_MORE
+    int frame_nbr;
+    for (frame_nbr = 0; frame_nbr < 5; frame_nbr++) {
+        frame = zframe_new ("Hello", 5);
+        rc = zframe_send (&frame, output, ZFRAME_MORE);
+        assert (rc == 0);
+    }
+    //  Send same frame five times, test ZFRAME_REUSE
+    frame = zframe_new ("Hello", 5);
+    assert (frame);
+    for (frame_nbr = 0; frame_nbr < 5; frame_nbr++) {
+        rc = zframe_send (&frame, output, ZFRAME_MORE + ZFRAME_REUSE);
+        assert (rc == 0);
+    }
+    assert (frame);
+    zframe_t *copy = zframe_dup (frame);
+    assert (zframe_eq (frame, copy));
+    zframe_destroy (&frame);
+    assert (!zframe_eq (frame, copy));
+    assert (zframe_size (copy) == 5);
+    zframe_destroy (&copy);
+    assert (!zframe_eq (frame, copy));
+	
+    //  Test zframe_new_empty
+    frame = zframe_new_empty ();
+    assert (frame);
+    assert (zframe_size (frame) == 0);
+    zframe_destroy (&frame);
+
+    //  Send END frame
+    frame = zframe_new ("NOT", 3);
+    assert (frame);
+    zframe_reset (frame, "END", 3);
+    char *string = zframe_strhex (frame);
+    assert (streq (string, "454E44"));
+    free (string);
+    string = zframe_strdup (frame);
+    assert (streq (string, "END"));
+    free (string);
+    rc = zframe_send (&frame, output, 0);
+    assert (rc == 0);
+
+    //  Read and count until we receive END
+    frame_nbr = 0;
+    for (frame_nbr = 0;; frame_nbr++) {
+        zframe_t *frame = zframe_recv (input);
+        if (zframe_streq (frame, "END")) {
+            zframe_destroy (&frame);
+            break;
+        }
+        assert (zframe_more (frame));
+        zframe_set_more (frame, 0);
+        assert (zframe_more (frame) == 0);
+        zframe_destroy (&frame);
+    }
+    assert (frame_nbr == 10);
+    frame = zframe_recv_nowait (input);
+    assert (frame == NULL);
+
+    //  Test zero copy
+    char *buffer = (char *) malloc (1024);
+    memset (buffer, 'A', 1024);
+
+    frame = zframe_new_zero_copy (buffer, 1024, s_test_free_cb, NULL);
+    zframe_t *frame_copy = zframe_dup (frame);
+
+    assert (zframe_zero_copy (frame) == 1);
+    assert (zframe_zero_copy (frame_copy) == 0);
+
+    zframe_destroy (&frame);
+    zframe_destroy (&frame_copy);
+
+    frame = zframe_new ("callback", 8);
+    zframe_freefn (frame, s_test_free_frame_cb, NULL);
+    zframe_destroy (&frame);
+
+    zctx_destroy (&ctx);
+----
+
+SEE ALSO
+--------
+linkczmq:czmq[7]

data/ext/czmq/doc/zhash.txt

@@ -0,0 +1,225 @@
+zhash(3)
+========
+
+NAME
+----
+zhash - generic type-free hash container
+
+SYNOPSIS
+--------
+----
+//  Callback function for zhash_foreach method
+typedef int (zhash_foreach_fn) (const char *key, void *item, void *argument);
+//  Callback function for zhash_freefn method
+typedef void (zhash_free_fn) (void *data);
+
+//  Create a new, empty hash container
+CZMQ_EXPORT zhash_t *
+    zhash_new (void);
+
+//  Destroy a hash container and all items in it
+CZMQ_EXPORT void
+    zhash_destroy (zhash_t **self_p);
+
+//  Insert item into hash table with specified key and item.
+//  If key is already present returns -1 and leaves existing item unchanged
+//  Returns 0 on success.
+CZMQ_EXPORT int
+    zhash_insert (zhash_t *self, const char *key, void *item);
+
+//  Update item into hash table with specified key and item.
+//  If key is already present, destroys old item and inserts new one.
+//  Use free_fn method to ensure deallocator is properly called on item.
+CZMQ_EXPORT void
+    zhash_update (zhash_t *self, const char *key, void *item);
+
+//  Remove an item specified by key from the hash table. If there was no such
+//  item, this function does nothing.
+CZMQ_EXPORT void
+    zhash_delete (zhash_t *self, const char *key);
+
+//  Return the item at the specified key, or null
+CZMQ_EXPORT void *
+    zhash_lookup (zhash_t *self, const char *key);
+
+//  Reindexes an item from an old key to a new key. If there was no such
+//  item, does nothing. Returns 0 if successful, else -1.
+CZMQ_EXPORT int
+    zhash_rename (zhash_t *self, const char *old_key, const char *new_key);
+
+//  Set a free function for the specified hash table item. When the item is
+//  destroyed, the free function, if any, is called on that item.
+//  Use this when hash items 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 *
+    zhash_freefn (zhash_t *self, const char *key, zhash_free_fn *free_fn);
+
+//  Return the number of keys/items in the hash table
+CZMQ_EXPORT size_t
+    zhash_size (zhash_t *self);
+
+//  Make copy of hash table
+CZMQ_EXPORT zhash_t *
+    zhash_dup (zhash_t *self);
+
+//  Return keys for items in table
+CZMQ_EXPORT zlist_t *
+    zhash_keys (zhash_t *self);
+    
+//  Apply function to each item in the hash table. Items are iterated in no
+//  defined order. Stops if callback function returns non-zero and returns
+//  final return code from callback function (zero = success).
+CZMQ_EXPORT int
+    zhash_foreach (zhash_t *self, zhash_foreach_fn *callback, void *argument);
+
+//  Save hash table to a text file in name=value format. Hash values must be
+//  printable strings; keys may not contain '=' character. Returns 0 if OK,
+//  else -1 if a file error occurred.
+CZMQ_EXPORT int
+    zhash_save (zhash_t *self, char *filename);
+
+//  Load hash table from a text file in name=value format; hash table must
+//  already exist. Hash values must printable strings; keys may not contain
+//  '=' character. Returns 0 if OK, else -1 if a file was not readable.
+CZMQ_EXPORT int
+    zhash_load (zhash_t *self, char *filename);
+
+//  Set hash for automatic value destruction
+CZMQ_EXPORT void
+    zhash_autofree (zhash_t *self);
+    
+//  Self test of this class
+CZMQ_EXPORT void
+    zhash_test (int verbose);
+----
+
+DESCRIPTION
+-----------
+
+Expandable hash table container
+
+Note that it's relatively slow (~50k insertions/deletes per second), so
+don't do inserts/updates on the critical path for message I/O.  It can
+do ~2.5M lookups per second for 16-char keys.  Timed on a 1.6GHz CPU.
+
+EXAMPLE
+-------
+.From zhash_test method
+----
+    zhash_t *hash = zhash_new ();
+    assert (hash);
+    assert (zhash_size (hash) == 0);
+
+    //  Insert some items
+    int rc;
+    rc = zhash_insert (hash, "DEADBEEF", "dead beef");
+    assert (rc == 0);
+    rc = zhash_insert (hash, "ABADCAFE", "a bad cafe");
+    assert (rc == 0);
+    rc = zhash_insert (hash, "C0DEDBAD", "coded bad");
+    assert (rc == 0);
+    rc = zhash_insert (hash, "DEADF00D", "dead food");
+    assert (rc == 0);
+    assert (zhash_size (hash) == 4);
+
+    //  Look for existing items
+    char *item;
+    item = (char *) zhash_lookup (hash, "DEADBEEF");
+    assert (streq (item, "dead beef"));
+    item = (char *) zhash_lookup (hash, "ABADCAFE");
+    assert (streq (item, "a bad cafe"));
+    item = (char *) zhash_lookup (hash, "C0DEDBAD");
+    assert (streq (item, "coded bad"));
+    item = (char *) zhash_lookup (hash, "DEADF00D");
+    assert (streq (item, "dead food"));
+
+    //  Look for non-existent items
+    item = (char *) zhash_lookup (hash, "foo");
+    assert (item == NULL);
+
+    //  Try to insert duplicate items
+    rc = zhash_insert (hash, "DEADBEEF", "foo");
+    assert (rc == -1);
+    item = (char *) zhash_lookup (hash, "DEADBEEF");
+    assert (streq (item, "dead beef"));
+
+    //  Rename an item
+    rc = zhash_rename (hash, "DEADBEEF", "LIVEBEEF");
+    assert (rc == 0);
+    rc = zhash_rename (hash, "WHATBEEF", "LIVEBEEF");
+    assert (rc == -1);
+
+    //  Test keys method
+    zlist_t *keys = zhash_keys (hash);
+    assert (zlist_size (keys) == 4);
+    zlist_destroy (&keys);
+
+    //  Test dup method
+    zhash_t *copy = zhash_dup (hash);
+    assert (zhash_size (copy) == 4);
+    item = (char *) zhash_lookup (copy, "LIVEBEEF");
+    assert (item);
+    assert (streq (item, "dead beef"));
+    zhash_destroy (&copy);
+
+    // Test foreach
+    assert (0 == zhash_foreach (hash, test_foreach, hash));
+    assert (-1 == zhash_foreach (hash, test_foreach_error, hash));
+
+    //  Test save and load
+    zhash_save (hash, ".cache");
+    copy = zhash_new ();
+    zhash_load (copy, ".cache");
+    item = (char *) zhash_lookup (copy, "LIVEBEEF");
+    assert (item);
+    assert (streq (item, "dead beef"));
+    zhash_destroy (&copy);
+#if (defined (WIN32))
+    DeleteFile (".cache");
+#else
+    unlink (".cache");
+#endif
+        
+    //  Delete a item
+    zhash_delete (hash, "LIVEBEEF");
+    item = (char *) zhash_lookup (hash, "LIVEBEEF");
+    assert (item == NULL);
+    assert (zhash_size (hash) == 3);
+
+    //  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) {
+            item = (char *) zhash_lookup (hash, testset [testnbr].name);
+            assert (item);
+            zhash_delete (hash, testset [testnbr].name);
+            testset [testnbr].exists = false;
+        }
+        else {
+            sprintf (testset [testnbr].name, "%x-%x", rand (), rand ());
+            if (zhash_insert (hash, testset [testnbr].name, "") == 0)
+                testset [testnbr].exists = true;
+        }
+    }
+    //  Test 10K lookups
+    for (iteration = 0; iteration < 10000; iteration++)
+        item = (char *) zhash_lookup (hash, "DEADBEEFABADCAFE");
+
+    //  Destructor should be safe to call twice
+    zhash_destroy (&hash);
+    zhash_destroy (&hash);
+    assert (hash == NULL);
+----
+
+SEE ALSO
+--------
+linkczmq:czmq[7]

data/ext/czmq/doc/zlist.txt

@@ -0,0 +1,176 @@
+zlist(3)
+========
+
+NAME
+----
+zlist - generic type-free list container
+
+SYNOPSIS
+--------
+----
+//  Comparison function for zlist_sort method
+typedef bool (zlist_compare_fn) (void *item1, void *item2);
+
+//  Create a new list container
+CZMQ_EXPORT zlist_t *
+    zlist_new (void);
+
+//  Destroy a list container
+CZMQ_EXPORT void
+    zlist_destroy (zlist_t **self_p);
+
+//  Return first item in the list, or null
+CZMQ_EXPORT void *
+    zlist_first (zlist_t *self);
+
+//  Return last item in the list, or null
+CZMQ_EXPORT void *
+    zlist_last (zlist_t *self);
+
+//  Return first item in the list, or null, leaves the cursor
+CZMQ_EXPORT void *
+    zlist_head (zlist_t *self);
+
+//  Return last item in the list, or null, leaves the cursor
+CZMQ_EXPORT void *
+    zlist_tail (zlist_t *self);
+
+//  Return next item in the list, or null
+CZMQ_EXPORT void *
+    zlist_next (zlist_t *self);
+
+//  Append an item to the end of the list
+CZMQ_EXPORT int
+    zlist_append (zlist_t *self, void *item);
+
+//  Push an item to the start of the list
+CZMQ_EXPORT int
+    zlist_push (zlist_t *self, void *item);
+
+//  Pop the item off the start of the list, if any
+CZMQ_EXPORT void *
+    zlist_pop (zlist_t *self);
+
+//  Remove the specified item from the list if present
+CZMQ_EXPORT void
+    zlist_remove (zlist_t *self, void *item);
+
+//  Copy the entire list, return the copy
+CZMQ_EXPORT zlist_t *
+    zlist_dup (zlist_t *self);
+
+//  Copy the entire list, return the copy (deprecated)
+CZMQ_EXPORT zlist_t *
+    zlist_copy (zlist_t *self);
+
+//  Return number of items in the list
+CZMQ_EXPORT size_t
+    zlist_size (zlist_t *self);
+
+//  Sort list
+CZMQ_EXPORT void
+    zlist_sort (zlist_t *self, zlist_compare_fn *compare);
+
+//  Set list for automatic item destruction
+CZMQ_EXPORT void
+    zlist_autofree (zlist_t *self);
+
+//  Self test of this class
+CZMQ_EXPORT void
+    zlist_test (int verbose);
+----
+
+DESCRIPTION
+-----------
+
+Provides a generic container implementing a fast singly-linked list. You
+can use this to construct multi-dimensional lists, and other structures
+together with other generic containers like zhash.
+
+
+EXAMPLE
+-------
+.From zlist_test method
+----
+    zlist_t *list = zlist_new ();
+    assert (list);
+    assert (zlist_size (list) == 0);
+
+    //  Three items we'll use as test data
+    //  List items are void *, not particularly strings
+    char *cheese = "boursin";
+    char *bread = "baguette";
+    char *wine = "bordeaux";
+
+    zlist_append (list, cheese);
+    assert (zlist_size (list) == 1);
+    zlist_append (list, bread);
+    assert (zlist_size (list) == 2);
+    zlist_append (list, wine);
+    assert (zlist_size (list) == 3);
+
+    assert (zlist_head (list) == cheese);
+    assert (zlist_next (list) == cheese);
+
+    assert (zlist_first (list) == cheese);
+    assert (zlist_tail (list) == wine);
+    assert (zlist_next (list) == bread);
+
+    assert (zlist_first (list) == cheese);
+    assert (zlist_next (list) == bread);
+    assert (zlist_next (list) == wine);
+    assert (zlist_next (list) == NULL);
+    //  After we reach end of list, next wraps around
+    assert (zlist_next (list) == cheese);
+    assert (zlist_size (list) == 3);
+
+    zlist_remove (list, wine);
+    assert (zlist_size (list) == 2);
+
+    assert (zlist_first (list) == cheese);
+    zlist_remove (list, cheese);
+    assert (zlist_size (list) == 1);
+    assert (zlist_first (list) == bread);
+
+    zlist_remove (list, bread);
+    assert (zlist_size (list) == 0);
+
+    zlist_append (list, cheese);
+    zlist_append (list, bread);
+    assert (zlist_last (list) == bread);
+    zlist_remove (list, bread);
+    assert (zlist_last (list) == cheese);
+    zlist_remove (list, cheese);
+    assert (zlist_last (list) == NULL);
+
+    zlist_push (list, cheese);
+    assert (zlist_size (list) == 1);
+    assert (zlist_first (list) == cheese);
+
+    zlist_push (list, bread);
+    assert (zlist_size (list) == 2);
+    assert (zlist_first (list) == bread);
+
+    zlist_append (list, wine);
+    assert (zlist_size (list) == 3);
+    assert (zlist_first (list) == bread);
+
+    zlist_sort (list, s_compare);
+    char *item;
+    item = (char *) zlist_pop (list);
+    assert (item == bread);
+    item = (char *) zlist_pop (list);
+    assert (item == wine);
+    item = (char *) zlist_pop (list);
+    assert (item == cheese);
+    assert (zlist_size (list) == 0);
+
+    //  Destructor should be safe to call twice
+    zlist_destroy (&list);
+    zlist_destroy (&list);
+    assert (list == NULL);
+----
+
+SEE ALSO
+--------
+linkczmq:czmq[7]