rbczmq 1.7.1 → 1.7.2

data/ext/czmq/doc/zctx.txt

@@ -17,20 +17,39 @@ CZMQ_EXPORT void
     zctx_destroy (zctx_t **self_p);
 
 //  Raise default I/O threads from 1, for crazy heavy applications
+//  The rule of thumb is one I/O thread per gigabyte of traffic in
+//  or out. Call this method before creating any sockets on the context
+//  or the setting will have no effect.
 CZMQ_EXPORT void
     zctx_set_iothreads (zctx_t *self, int iothreads);
 
-//  Set msecs to flush sockets when closing them
+//  Set msecs to flush sockets when closing them, see the ZMQ_LINGER
+//  man page section for more details. By default, set to zero, so
+//  any in-transit messages are discarded when you destroy a socket or
+//  a context.
 CZMQ_EXPORT void
     zctx_set_linger (zctx_t *self, int linger);
 
-//  Set HWM value. This is used in zthread_fork
+//  Set initial high-water mark for inter-thread pipe sockets. Note that
+//  this setting is separate from the default for normal sockets. You 
+//  should change the default for pipe sockets *with care*. Too low values
+//  will cause blocked threads, and an infinite setting can cause memory
+//  exhaustion. The default, no matter the underlying ZeroMQ version, is
+//  1,000.
 CZMQ_EXPORT void
-    zctx_set_hwm (zctx_t *self, int hwm);
-
-//  Get HWM value. This is used in zthread_fork
-int
-    zctx_hwm (zctx_t *self);
+    zctx_set_pipehwm (zctx_t *self, int pipehwm);
+    
+//  Set initial send HWM for all new normal sockets created in context.
+//  You can set this per-socket after the socket is created.
+//  The default, no matter the underlying ZeroMQ version, is 1,000.
+CZMQ_EXPORT void
+    zctx_set_sndhwm (zctx_t *self, int sndhwm);
+    
+//  Set initial receive HWM for all new normal sockets created in context.
+//  You can set this per-socket after the socket is created.
+//  The default, no matter the underlying ZeroMQ version, is 1,000.
+CZMQ_EXPORT void
+    zctx_set_rcvhwm (zctx_t *self, int rcvhwm);
 
 //  Return low-level 0MQ context object, will be NULL before first socket
 //  is created. Use with care.

data/ext/czmq/doc/zdir.txt

@@ -0,0 +1,83 @@
+zdir(3)
+=======
+
+NAME
+----
+zdir - work with file-system directories
+
+SYNOPSIS
+--------
+----
+//  Create a new directory item that loads in the full tree of the
+//  specified path, optionally located under some parent path.
+CZMQ_EXPORT zdir_t *
+    zdir_new (const char *path, const char *parent);
+
+//  Destroy a directory tree and all children it contains.
+CZMQ_EXPORT void
+    zdir_destroy (zdir_t **self_p);
+
+//  Return directory path
+CZMQ_EXPORT char *
+    zdir_path (zdir_t *self);
+
+//  Return last modification time for directory.
+CZMQ_EXPORT time_t
+    zdir_modified (zdir_t *self);
+
+//  Return total hierarchy size, in bytes of data contained in all files
+//  in the directory tree.
+CZMQ_EXPORT off_t
+    zdir_cursize (zdir_t *self);
+
+//  Returns a sorted array of zfile objects; returns a single block of memory,
+//  that you destroy by calling free(). Each entry in the array is a pointer
+//  to a zfile_t item already allocated in the zdir tree. The array ends with
+//  a null pointer. Do not destroy the original zdir tree until you are done
+//  with this array.
+CZMQ_EXPORT zfile_t **
+    zdir_flatten (zdir_t *self);
+
+//  Print contents of directory to stderr
+CZMQ_EXPORT void
+    zdir_dump (zdir_t *self, int indent);
+
+//  Remove directory, optionally including all files that it contains, at
+//  all levels. If force is false, will only remove the directory if empty.
+//  If force is true, will remove all files and all subdirectories.
+CZMQ_EXPORT void
+    zdir_remove (zdir_t *self, bool force);
+
+//  Self test of this class
+CZMQ_EXPORT int
+    zdir_test (bool verbose);
+----
+
+DESCRIPTION
+-----------
+
+The zdir class gives access to the file system index. It will load
+a directory tree (a directory plus all child directories) into a
+zdir structure and then let you navigate that structure. It exists
+mainly to wrap non-portable OS functions to do this.
+
+
+EXAMPLE
+-------
+.From zdir_test method
+----
+    zdir_t *older = zdir_new (".", NULL);
+    assert (older);
+    if (verbose) {
+        printf ("\n");
+        zdir_dump (older, 0);
+    }
+    zdir_destroy (&older);
+
+    zdir_t *nosuch = zdir_new ("does-not-exist", NULL);
+    assert (nosuch == NULL);
+----
+
+SEE ALSO
+--------
+linkczmq:czmq[7]

data/ext/czmq/doc/zfile.txt

@@ -3,73 +3,168 @@ zfile(3)
 
 NAME
 ----
-zfile - helper functions for working with files.
+zfile - provides methods to work with files in a portable fashion.
 
 SYNOPSIS
 --------
 ----
-//  Return 1 if file exists, else zero
+//  Create new file item
+CZMQ_EXPORT zfile_t *
+    zfile_new (const char *path, const char *name);
+
+//  Destroy a file item
+CZMQ_EXPORT void
+    zfile_destroy (zfile_t **self_p);
+
+//  Duplicate a file item, returns a newly constructed item
+CZMQ_EXPORT zfile_t *
+    zfile_dup (zfile_t *self);
+
+//  Return file name, remove path if provided
+CZMQ_EXPORT char *
+    zfile_filename (zfile_t *self, char *path);
+
+//  Return when the file was last modified.
+//  Updates the file statistics from disk at every call.
+CZMQ_EXPORT time_t
+    zfile_modified (zfile_t *self);
+
+//  Return the last-known size of the file.
+//  Updates the file statistics from disk at every call.
+CZMQ_EXPORT off_t
+    zfile_cursize (zfile_t *self);
+
+//  Return true if the file is a directory.
+//  Updates the file statistics from disk at every call.
 CZMQ_EXPORT bool
-    zfile_exists (const char *filename);
+    zfile_is_directory (zfile_t *self);
 
-//  Return size of file, or -1 if not found
-CZMQ_EXPORT ssize_t
-    zfile_size (const char *filename);
+//  Return true if the file is a regular file.
+//  Updates the file statistics from disk at every call.
+CZMQ_EXPORT bool
+    zfile_is_regular (zfile_t *self);
 
-//  Return file mode
-CZMQ_EXPORT mode_t
-    zfile_mode (const char *filename);
+//  Return true if the file is readable by this process
+//  Updates the file statistics from disk at every call.
+CZMQ_EXPORT bool
+    zfile_is_readable (zfile_t *self);
 
-//  Delete file. Does not complain if the file is absent
-CZMQ_EXPORT int
-    zfile_delete (const char *filename);
+//  Return true if the file is writeable by this process
+//  Updates the file statistics from disk at every call.
+CZMQ_EXPORT bool
+    zfile_is_writeable (zfile_t *self);
 
-//  Check if file is 'stable'
+//  Check if file has stopped changing and can be safely processed.
+//  Updates the file statistics from disk at every call.
 CZMQ_EXPORT bool
-    zfile_stable (const char *filename);
+    zfile_is_stable (zfile_t *self);
 
-//  Create a file path if it doesn't exit
+//  Remove the file from disk
+CZMQ_EXPORT void
+    zfile_remove (zfile_t *self);
+
+//  Open file for reading, returns 0 if OK, else -1.
 CZMQ_EXPORT int
-    zfile_mkdir (const char *pathname);
+    zfile_input (zfile_t *self);
 
-//  Remove a file path if empty
+//  Open file for writing, creating full directory path if needed
 CZMQ_EXPORT int
-    zfile_rmdir (const char *pathname);
+    zfile_output (zfile_t *self);
 
-//  Set private file creation mode; all files created from here will be
-//  readable/writable by the owner only.
-CZMQ_EXPORT void
-    zfile_mode_private (void);
-    
-//  Reset default file creation mode; all files created from here will use
-//  process file mode defaults.
+//  Read chunk from file at specified position
+CZMQ_EXPORT zchunk_t *
+    zfile_read (zfile_t *self, size_t bytes, off_t offset);
+
+//  Write chunk to file at specified position
+CZMQ_EXPORT int
+    zfile_write (zfile_t *self, zchunk_t *chunk, off_t offset);
+
+//  Close file, if open
 CZMQ_EXPORT void
-    zfile_mode_default (void);
+    zfile_close (zfile_t *self);
+
+//  Return file handle, if opened
+CZMQ_EXPORT FILE *
+    zfile_handle (zfile_t *self);
 
 //  Self test of this class
 CZMQ_EXPORT int
     zfile_test (bool verbose);
+//  These methods are deprecated, and now moved to zsys class.
+CZMQ_EXPORT bool
+    zfile_exists (const char *filename);
+CZMQ_EXPORT ssize_t
+    zfile_size   (const char *filename);
+CZMQ_EXPORT mode_t
+    zfile_mode   (const char *filename);
+CZMQ_EXPORT int
+    zfile_delete (const char *filename);
+CZMQ_EXPORT bool
+    zfile_stable (const char *filename);
+CZMQ_EXPORT int
+    zfile_mkdir  (const char *pathname);
+CZMQ_EXPORT int
+    zfile_rmdir  (const char *pathname);
+CZMQ_EXPORT void
+    zfile_mode_private (void);
+CZMQ_EXPORT void
+    zfile_mode_default (void);
 ----
 
 DESCRIPTION
 -----------
 
-The zfile class provides methods to work with files and directories.
+The zfile class provides methods to work with files. This class is a new
+API, deprecating the old zfile class (which still exists but is implemented
+in zsys now).
 
 
 EXAMPLE
 -------
 .From zfile_test method
 ----
-    int rc = zfile_delete ("nosuchfile");
+    zfile_t *file = zfile_new (".", "bilbo");
+    assert (streq (zfile_filename (file, "."), "bilbo"));
+    assert (zfile_is_readable (file) == false);
+    zfile_destroy (&file);
+
+    //  Create a test file in some random subdirectory
+    file = zfile_new ("./this/is/a/test", "bilbo");
+    int rc = zfile_output (file);
+    assert (rc == 0);
+    zchunk_t *chunk = zchunk_new (NULL, 100);
+    zchunk_fill (chunk, 0, 100);
+    //  Write 100 bytes at position 1,000,000 in the file
+    rc = zfile_write (file, chunk, 1000000);
+    assert (rc == 0);
+    zfile_close (file);
+    assert (zfile_is_readable (file));
+    assert (zfile_cursize (file) == 1000100);
+    assert (!zfile_is_stable (file));
+    zchunk_destroy (&chunk);
+    zclock_sleep (1001);
+    assert (zfile_is_stable (file));
+
+    //  Check we can read from file
+    rc = zfile_input (file);
+    assert (rc == 0);
+    chunk = zfile_read (file, 1000100, 0);
+    assert (chunk);
+    assert (zchunk_size (chunk) == 1000100);
+    zchunk_destroy (&chunk);
+
+    //  Remove file and directory
+    zdir_t *dir = zdir_new ("./this", NULL);
+    assert (zdir_cursize (dir) == 1000100);
+    zdir_remove (dir, true);
+    assert (zdir_cursize (dir) == 0);
+    zdir_destroy (&dir);
+
+    //  Check we can no longer read from file
+    assert (!zfile_is_readable (file));
+    rc = zfile_input (file);
     assert (rc == -1);
-
-    bool rc_bool = zfile_exists ("nosuchfile");
-    assert (rc_bool != true);
-
-    rc = (int) zfile_size ("nosuchfile");
-    assert (rc == -1);
-
+    zfile_destroy (&file);
 ----
 
 SEE ALSO

data/ext/czmq/doc/zframe.txt

@@ -79,6 +79,10 @@ CZMQ_EXPORT void
 CZMQ_EXPORT bool
     zframe_eq (zframe_t *self, zframe_t *other);
 
+//   Print contents of the frame to FILE stream.
+CZMQ_EXPORT void
+    zframe_fprint (zframe_t *self, const char *prefix, FILE *file);
+
 //  Print contents of frame to stderr
 CZMQ_EXPORT void
     zframe_print (zframe_t *self, const char *prefix);
@@ -87,26 +91,6 @@ CZMQ_EXPORT void
 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);
@@ -130,7 +114,7 @@ EXAMPLE
 ----
     zctx_t *ctx = zctx_new ();
     assert (ctx);
-    
+
     void *output = zsocket_new (ctx, ZMQ_PAIR);
     assert (output);
     zsocket_bind (output, "inproc://zframe.test");
@@ -160,7 +144,7 @@ EXAMPLE
     assert (zframe_size (copy) == 5);
     zframe_destroy (&copy);
     assert (!zframe_eq (frame, copy));
-	
+
     //  Test zframe_new_empty
     frame = zframe_new_empty ();
     assert (frame);
@@ -197,23 +181,6 @@ EXAMPLE
     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);
 ----
 

data/ext/czmq/doc/zhash.txt

@@ -73,6 +73,12 @@ CZMQ_EXPORT zlist_t *
 CZMQ_EXPORT int
     zhash_foreach (zhash_t *self, zhash_foreach_fn *callback, void *argument);
 
+//  Add comment to hash table before saving to disk. You can add as many
+//  comment lines as you like. These comment lines are discarded when loading
+//  the file. If you use a null format, all comments are deleted.
+CZMQ_EXPORT void
+    zhash_comment (zhash_t *self, char *format, ...);
+
 //  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.
@@ -85,6 +91,13 @@ CZMQ_EXPORT int
 CZMQ_EXPORT int
     zhash_load (zhash_t *self, char *filename);
 
+//  When a hash table was loaded from a file by zhash_load, this method will
+//  reload the file if it has been modified since, and is "stable", i.e. not
+//  still changing. Returns 0 if OK, -1 if there was an error reloading the 
+//  file.
+CZMQ_EXPORT int
+    zhash_refresh (zhash_t *self);
+
 //  Set hash for automatic value destruction
 CZMQ_EXPORT void
     zhash_autofree (zhash_t *self);
@@ -99,9 +112,9 @@ 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.
+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
 -------
@@ -144,11 +157,31 @@ EXAMPLE
     item = (char *) zhash_lookup (hash, "DEADBEEF");
     assert (streq (item, "dead beef"));
 
-    //  Rename an item
+    //  Some rename tests
+
+    //  Valid rename, key is now LIVEBEEF
     rc = zhash_rename (hash, "DEADBEEF", "LIVEBEEF");
     assert (rc == 0);
+    item = (char *) zhash_lookup (hash, "LIVEBEEF");
+    assert (streq (item, "dead beef"));
+
+    //  Trying to rename an unknown item to a non-existent key
+    rc = zhash_rename (hash, "WHATBEEF", "NONESUCH");
+    assert (rc == -1);
+
+    //  Trying to rename an unknown item to an existing key
     rc = zhash_rename (hash, "WHATBEEF", "LIVEBEEF");
     assert (rc == -1);
+    item = (char *) zhash_lookup (hash, "LIVEBEEF");
+    assert (streq (item, "dead beef"));
+
+    //  Trying to rename an existing item to another existing item
+    rc = zhash_rename (hash, "LIVEBEEF", "ABADCAFE");
+    assert (rc == -1);
+    item = (char *) zhash_lookup (hash, "LIVEBEEF");
+    assert (streq (item, "dead beef"));
+    item = (char *) zhash_lookup (hash, "ABADCAFE");
+    assert (streq (item, "a bad cafe"));
 
     //  Test keys method
     zlist_t *keys = zhash_keys (hash);
@@ -168,6 +201,8 @@ EXAMPLE
     assert (-1 == zhash_foreach (hash, test_foreach_error, hash));
 
     //  Test save and load
+    zhash_comment (hash, "This is a test file");
+    zhash_comment (hash, "Created by %s", "czmq_selftest");
     zhash_save (hash, ".cache");
     copy = zhash_new ();
     zhash_load (copy, ".cache");
@@ -175,12 +210,8 @@ EXAMPLE
     assert (item);
     assert (streq (item, "dead beef"));
     zhash_destroy (&copy);
-#if (defined (WIN32))
-    DeleteFile (".cache");
-#else
-    unlink (".cache");
-#endif
-        
+    zsys_file_delete (".cache");
+
     //  Delete a item
     zhash_delete (hash, "LIVEBEEF");
     item = (char *) zhash_lookup (hash, "LIVEBEEF");
@@ -218,6 +249,20 @@ EXAMPLE
     zhash_destroy (&hash);
     zhash_destroy (&hash);
     assert (hash == NULL);
+
+    // Test autofree; automatically copies and frees string values
+    hash = zhash_new ();
+    zhash_autofree (hash);
+    char value [255];
+    strcpy (value, "This is a string");
+    rc = zhash_insert (hash, "key1", value);
+    assert (rc == 0);
+    strcpy (value, "Ring a ding ding");
+    rc = zhash_insert (hash, "key2", value);
+    assert (rc == 0);
+    assert (streq (zhash_lookup (hash, "key1"), "This is a string"));
+    assert (streq (zhash_lookup (hash, "key2"), "Ring a ding ding"));
+    zhash_destroy (&hash);
 ----
 
 SEE ALSO