rbczmq 1.6.2 → 1.6.4

data/ext/czmq/doc/zbeacon.txt

@@ -0,0 +1,173 @@
+zbeacon(3)
+==========
+
+NAME
+----
+zbeacon - LAN service announcement and discovery
+
+SYNOPSIS
+--------
+----
+//  Create a new beacon on a certain UDP port
+CZMQ_EXPORT zbeacon_t *
+    zbeacon_new (int port_nbr);
+    
+//  Destroy a beacon
+CZMQ_EXPORT void
+    zbeacon_destroy (zbeacon_t **self_p);
+
+//  Return our own IP address as printable string
+CZMQ_EXPORT char *
+    zbeacon_hostname (zbeacon_t *self);
+
+//  Set broadcast interval in milliseconds (default is 1000 msec)
+CZMQ_EXPORT void
+    zbeacon_set_interval (zbeacon_t *self, int interval);
+
+//  Filter out any beacon that looks exactly like ours
+CZMQ_EXPORT void
+    zbeacon_noecho (zbeacon_t *self);
+
+//  Start broadcasting beacon to peers at the specified interval
+CZMQ_EXPORT void
+    zbeacon_publish (zbeacon_t *self, byte *transmit, size_t size);
+    
+//  Stop broadcasting beacons
+CZMQ_EXPORT void
+    zbeacon_silence (zbeacon_t *self);
+
+//  Start listening to other peers; zero-sized filter means get everything
+CZMQ_EXPORT void
+    zbeacon_subscribe (zbeacon_t *self, byte *filter, size_t size);
+
+//  Stop listening to other peers
+CZMQ_EXPORT void
+    zbeacon_unsubscribe (zbeacon_t *self);
+
+//  Get beacon ZeroMQ socket, for polling or receiving messages
+CZMQ_EXPORT void *
+    zbeacon_socket (zbeacon_t *self);
+
+//  Get beacon pipe, for polling or receiving messages
+//  DEPRECATED
+CZMQ_EXPORT void *
+    zbeacon_pipe (zbeacon_t *self);
+
+//  Self test of this class
+CZMQ_EXPORT void
+    zbeacon_test (bool verbose);
+----
+
+DESCRIPTION
+-----------
+
+The zbeacon class implements a peer-to-peer discovery service for local
+networks. A beacon can broadcast and/or capture service announcements
+using UDP messages on the local area network. This implementation uses
+IPv4 UDP broadcasts. You can define the format of your outgoing beacons,
+and set a filter that validates incoming beacons. Beacons are sent and
+received asynchronously in the background. The zbeacon API provides a
+incoming beacons on a ZeroMQ socket (the pipe) that you can configure,
+poll on, and receive messages on. Incoming beacons are always delivered
+as two frames: the ipaddress of the sender (a string), and the beacon
+data itself (binary, as published).
+
+
+EXAMPLE
+-------
+.From zbeacon_test method
+----
+    //  Basic test: create a service and announce it
+    zctx_t *ctx = zctx_new ();
+
+    //  Create a service socket and bind to an ephemeral port
+    void *service = zsocket_new (ctx, ZMQ_PUB);
+    int port_nbr = zsocket_bind (service, "tcp://*:*");
+    
+    //  Create beacon to broadcast our service
+    byte announcement [2] = { (port_nbr >> 8) & 0xFF, port_nbr & 0xFF };
+    zbeacon_t *service_beacon = zbeacon_new (9999);
+    zbeacon_set_interval (service_beacon, 100);
+    zbeacon_publish (service_beacon, announcement, 2);
+
+    //  Create beacon to lookup service
+    zbeacon_t *client_beacon = zbeacon_new (9999);
+    zbeacon_subscribe (client_beacon, NULL, 0);
+
+    //  Wait for at most 1/2 second if there's no broadcast networking
+    zsocket_set_rcvtimeo (zbeacon_socket (client_beacon), 500);
+
+    char *ipaddress = zstr_recv (zbeacon_socket (client_beacon));
+    if (ipaddress) {
+        zframe_t *content = zframe_recv (zbeacon_socket (client_beacon));
+        int received_port = (zframe_data (content) [0] << 8)
+                        +  zframe_data (content) [1];
+        assert (received_port == port_nbr);
+        zframe_destroy (&content);
+        free (ipaddress);
+    }
+    zbeacon_destroy (&client_beacon);
+    zbeacon_destroy (&service_beacon);
+    zctx_destroy (&ctx);
+    
+    zbeacon_t *node1 = zbeacon_new (5670);
+    zbeacon_t *node2 = zbeacon_new (5670);
+    zbeacon_t *node3 = zbeacon_new (5670);
+
+    assert (*zbeacon_hostname (node1));
+    assert (*zbeacon_hostname (node2));
+    assert (*zbeacon_hostname (node3));
+    
+    zbeacon_set_interval (node1, 250);
+    zbeacon_set_interval (node2, 250);
+    zbeacon_set_interval (node3, 250);
+    zbeacon_noecho (node1);
+    zbeacon_publish (node1, (byte *) "NODE/1", 6);
+    zbeacon_publish (node2, (byte *) "NODE/2", 6);
+    zbeacon_publish (node3, (byte *) "GARBAGE", 7);
+    zbeacon_subscribe (node1, (byte *) "NODE", 4);
+
+    //  Poll on API pipe and on UDP socket
+    zmq_pollitem_t pollitems [] = {
+        { zbeacon_socket (node1), 0, ZMQ_POLLIN, 0 },
+        { zbeacon_socket (node2), 0, ZMQ_POLLIN, 0 },
+        { zbeacon_socket (node3), 0, ZMQ_POLLIN, 0 }
+    };
+    uint64_t stop_at = zclock_time () + 1000;
+    while (zclock_time () < stop_at) {
+        long timeout = (long) (stop_at - zclock_time ());
+        if (timeout < 0)
+            timeout = 0;
+        if (zmq_poll (pollitems, 3, timeout * ZMQ_POLL_MSEC) == -1)
+            break;              //  Interrupted
+
+        //  We cannot get messages on nodes 2 and 3
+        assert ((pollitems [1].revents & ZMQ_POLLIN) == 0);
+        assert ((pollitems [2].revents & ZMQ_POLLIN) == 0);
+
+        //  If we get a message on node 1, it must be NODE/2
+        if (pollitems [0].revents & ZMQ_POLLIN) {
+            char *ipaddress = zstr_recv (zbeacon_socket (node1));
+            char *beacon = zstr_recv (zbeacon_socket (node1));
+            assert (streq (beacon, "NODE/2"));
+            free (ipaddress);
+            free (beacon);
+        }
+    }
+    //  Stop listening
+    zbeacon_unsubscribe (node1);
+    
+    //  Stop all node broadcasts
+    zbeacon_silence (node1);
+    zbeacon_silence (node2);
+    zbeacon_silence (node3);
+
+    //  Destroy the test nodes
+    zbeacon_destroy (&node1);
+    zbeacon_destroy (&node2);
+    zbeacon_destroy (&node3);
+----
+
+SEE ALSO
+--------
+linkczmq:czmq[7]

data/ext/czmq/doc/zclock.txt

@@ -0,0 +1,51 @@
+zclock(3)
+=========
+
+NAME
+----
+zclock - millisecond clocks and delays
+
+SYNOPSIS
+--------
+----
+//  Sleep for a number of milliseconds
+CZMQ_EXPORT void
+    zclock_sleep (int msecs);
+
+//  Return current system clock as milliseconds
+CZMQ_EXPORT int64_t
+    zclock_time (void);
+
+//  Print formatted string to stdout, prefixed by date/time and
+//  terminated with a newline.
+CZMQ_EXPORT void
+    zclock_log (const char *format, ...);
+
+//  Self test of this class
+CZMQ_EXPORT int
+    zclock_test (bool verbose);
+----
+
+DESCRIPTION
+-----------
+
+The zclock class provides essential sleep and system time functions, used
+to slow down threads for testing, and calculate timers for polling. Wraps
+the non-portable system calls in a simple portable API.
+
+The Win32 Sleep() call defaults to 16ms resolution unless the system timer
+resolution is increased with a call to timeBeginPeriod() permitting 1ms
+granularity.
+
+EXAMPLE
+-------
+.From zclock_test method
+----
+    int64_t start = zclock_time ();
+    zclock_sleep (10);
+    assert ((zclock_time () - start) >= 10);
+----
+
+SEE ALSO
+--------
+linkczmq:czmq[7]

data/ext/czmq/doc/zconfig.txt

@@ -0,0 +1,92 @@
+zconfig(3)
+==========
+
+NAME
+----
+zconfig - work with config files written in rfc.zeromq.org/spec:4/ZPL.
+
+SYNOPSIS
+--------
+----
+----
+
+DESCRIPTION
+-----------
+
+Lets applications load, work with, and save configuration files.
+This implements rfc.zeromq.org/spec:4/ZPL, which is a simple structured
+text format for configuration files. Note that comments are stripped out
+of configuration files when loading them, so loading and saving a config
+file will remove any comments it contains.
+
+
+EXAMPLE
+-------
+.From zconfig_test method
+----
+    //  We create a config of this structure:
+    //
+    //  root
+    //      type = zqueue
+    //      frontend
+    //          option
+    //              swap = 25000000     #  25MB
+    //              subscribe = #2
+    //              hwm = 1000
+    //          bind = tcp://*:5555
+    //      backend
+    //          bind = tcp://*:5556
+    //
+    zconfig_t
+        *root,
+        *type,
+        *frontend,
+        *option,
+        *hwm,
+        *swap,
+        *subscribe,
+        *bind,
+        *backend;
+
+    //  Left is first child, next is next sibling
+    root     = zconfig_new ("root", NULL);
+    type     = zconfig_new ("type", root);
+    zconfig_set_value (type, "zqueue");
+    frontend = zconfig_new ("frontend", root);
+    option   = zconfig_new ("option", frontend);
+    swap     = zconfig_new ("swap", option);
+    zconfig_set_value (swap, "25000000");
+    subscribe = zconfig_new ("subscribe", option);
+    zconfig_set_value (subscribe, "#%d", 2);
+    hwm      = zconfig_new ("hwm", option);
+    zconfig_set_value (hwm, "1000");
+    bind     = zconfig_new ("bind", frontend);
+    zconfig_set_value (bind, "tcp://*:5555");
+    backend  = zconfig_new ("backend", root);
+    bind     = zconfig_new ("bind", backend);
+    zconfig_set_value (bind, "tcp://*:5556");
+
+    assert (atoi (zconfig_resolve (root, "frontend/option/hwm", "0")) == 1000);
+    assert (streq (zconfig_resolve (root, "backend/bind", ""), "tcp://*:5556"));
+
+    zconfig_put (root, "frontend/option/hwm", "500");
+    assert (atoi (zconfig_resolve (root, "frontend/option/hwm", "0")) == 500);
+    zconfig_put (root, "frontend/option/lwm", "200");
+    assert (atoi (zconfig_resolve (root, "frontend/option/lwm", "0")) == 200);
+    
+    zconfig_destroy (&root);
+    assert (root == NULL);
+
+    //  Test loading from a ZPL file
+    zconfig_t *config = zconfig_load ("selftest.cfg");
+    assert (config);
+
+    //  Destructor should be safe to call twice
+    zconfig_destroy (&config);
+    zconfig_destroy (&config);
+    assert (config == NULL);
+----
+
+SEE ALSO
+--------
+linkczmq:czmq[7]

data/ext/czmq/doc/zctx.txt

@@ -0,0 +1,111 @@
+zctx(3)
+=======
+
+NAME
+----
+zctx - working with 0MQ contexts
+
+SYNOPSIS
+--------
+----
+//  Create new context, returns context object, replaces zmq_init
+CZMQ_EXPORT zctx_t *
+    zctx_new (void);
+
+//  Destroy context and all sockets in it, replaces zmq_term
+CZMQ_EXPORT void
+    zctx_destroy (zctx_t **self_p);
+
+//  Raise default I/O threads from 1, for crazy heavy applications
+CZMQ_EXPORT void
+    zctx_set_iothreads (zctx_t *self, int iothreads);
+
+//  Set msecs to flush sockets when closing them
+CZMQ_EXPORT void
+    zctx_set_linger (zctx_t *self, int linger);
+
+//  Set HWM value. This is used in zthread_fork
+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);
+
+//  Return low-level 0MQ context object, will be NULL before first socket
+//  is created. Use with care.
+CZMQ_EXPORT void *
+    zctx_underlying (zctx_t *self);
+
+//  Self test of this class
+CZMQ_EXPORT int
+    zctx_test (bool verbose);
+
+//  Global signal indicator, TRUE when user presses Ctrl-C or the process
+//  gets a SIGTERM signal.
+CZMQ_EXPORT extern volatile int zctx_interrupted;
+----
+
+DESCRIPTION
+-----------
+
+The zctx class wraps 0MQ contexts. It manages open sockets in the context
+and automatically closes these before terminating the context. It provides
+a simple way to set the linger timeout on sockets, and configure contexts
+for number of I/O threads. Sets-up signal (interrupt) handling for the
+process.
+
+The zctx class has these main features:
+
+* Tracks all open sockets and automatically closes them before calling
+zmq_term(). This avoids an infinite wait on open sockets.
+
+* Automatically configures sockets with a ZMQ_LINGER timeout you can
+define, and which defaults to zero. The default behavior of zctx is
+therefore like 0MQ/2.0, immediate termination with loss of any pending
+messages. You can set any linger timeout you like by calling the
+zctx_set_linger() method.
+
+* Moves the iothreads configuration to a separate method, so that default
+usage is 1 I/O thread. Lets you configure this value.
+
+* Sets up signal (SIGINT and SIGTERM) handling so that blocking calls
+such as zmq_recv() and zmq_poll() will return when the user presses
+Ctrl-C.
+
+
+
+EXAMPLE
+-------
+.From zctx_test method
+----
+    //  Create and destroy a context without using it
+    zctx_t *ctx = zctx_new ();
+    assert (ctx);
+    zctx_destroy (&ctx);
+    assert (ctx == NULL);
+
+    //  Create a context with many busy sockets, destroy it
+    ctx = zctx_new ();
+    assert (ctx);
+    zctx_set_iothreads (ctx, 1);
+    zctx_set_linger (ctx, 5);       //  5 msecs
+    void *s1 = zctx__socket_new (ctx, ZMQ_PAIR);
+    void *s2 = zctx__socket_new (ctx, ZMQ_XREQ);
+    void *s3 = zctx__socket_new (ctx, ZMQ_REQ);
+    void *s4 = zctx__socket_new (ctx, ZMQ_REP);
+    void *s5 = zctx__socket_new (ctx, ZMQ_PUB);
+    void *s6 = zctx__socket_new (ctx, ZMQ_SUB);
+    zsocket_connect (s1, "tcp://127.0.0.1:5555");
+    zsocket_connect (s2, "tcp://127.0.0.1:5555");
+    zsocket_connect (s3, "tcp://127.0.0.1:5555");
+    zsocket_connect (s4, "tcp://127.0.0.1:5555");
+    zsocket_connect (s5, "tcp://127.0.0.1:5555");
+    zsocket_connect (s6, "tcp://127.0.0.1:5555");
+    assert (zctx_underlying (ctx));
+    zctx_destroy (&ctx);
+----
+
+SEE ALSO
+--------
+linkczmq:czmq[7]

data/ext/czmq/doc/zfile.txt

@@ -0,0 +1,77 @@
+zfile(3)
+========
+
+NAME
+----
+zfile - helper functions for working with files.
+
+SYNOPSIS
+--------
+----
+//  Return 1 if file exists, else zero
+CZMQ_EXPORT bool
+    zfile_exists (const char *filename);
+
+//  Return size of file, or -1 if not found
+CZMQ_EXPORT ssize_t
+    zfile_size (const char *filename);
+
+//  Return file mode
+CZMQ_EXPORT mode_t
+    zfile_mode (const char *filename);
+
+//  Delete file. Does not complain if the file is absent
+CZMQ_EXPORT int
+    zfile_delete (const char *filename);
+
+//  Check if file is 'stable'
+CZMQ_EXPORT bool
+    zfile_stable (const char *filename);
+
+//  Create a file path if it doesn't exit
+CZMQ_EXPORT int
+    zfile_mkdir (const char *pathname);
+
+//  Remove a file path if empty
+CZMQ_EXPORT int
+    zfile_rmdir (const char *pathname);
+
+//  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.
+CZMQ_EXPORT void
+    zfile_mode_default (void);
+
+//  Self test of this class
+CZMQ_EXPORT int
+    zfile_test (bool verbose);
+----
+
+DESCRIPTION
+-----------
+
+The zfile class provides methods to work with files and directories.
+
+
+EXAMPLE
+-------
+.From zfile_test method
+----
+    int rc = zfile_delete ("nosuchfile");
+    assert (rc == -1);
+
+    bool rc_bool = zfile_exists ("nosuchfile");
+    assert (rc_bool != true);
+
+    rc = (int) zfile_size ("nosuchfile");
+    assert (rc == -1);
+
+----
+
+SEE ALSO
+--------
+linkczmq:czmq[7]