rbczmq 1.6.2 → 1.6.4

data/ext/zeromq/doc/zmq_msg_init.txt

@@ -0,0 +1,65 @@
+zmq_msg_init(3)
+===============
+
+
+NAME
+----
+zmq_msg_init - initialise empty 0MQ message
+
+
+SYNOPSIS
+--------
+*int zmq_msg_init (zmq_msg_t '*msg');*
+
+
+DESCRIPTION
+-----------
+The _zmq_msg_init()_ function shall initialise the message object referenced by
+'msg' to represent an empty message.  This function is most useful when called
+before receiving a message with _zmq_recv()_.
+
+CAUTION: Never access 'zmq_msg_t' members directly, instead always use the
+_zmq_msg_ family of functions.
+
+CAUTION: The functions _zmq_msg_init()_, _zmq_msg_init_data()_ and
+_zmq_msg_init_size()_ are mutually exclusive. Never initialize the same
+'zmq_msg_t' twice.
+
+
+RETURN VALUE
+------------
+The _zmq_msg_init()_ function shall return zero if successful. Otherwise it
+shall return `-1` and set 'errno' to one of the values defined below.
+
+
+ERRORS
+------
+No errors are defined.
+
+
+EXAMPLE
+-------
+.Receiving a message from a socket
+----
+zmq_msg_t msg;
+rc = zmq_msg_init (&msg);
+assert (rc == 0);
+rc = zmq_recv (socket, &msg, 0);
+assert (rc == 0);
+----
+
+
+SEE ALSO
+--------
+linkzmq:zmq_msg_init_size[3]
+linkzmq:zmq_msg_init_data[3]
+linkzmq:zmq_msg_close[3]
+linkzmq:zmq_msg_data[3]
+linkzmq:zmq_msg_size[3]
+linkzmq:zmq[7]
+
+
+AUTHORS
+-------
+This 0MQ manual page was written by Martin Sustrik <sustrik@250bpm.com> and
+Martin Lucina <mato@kotelna.sk>.

data/ext/zeromq/doc/zmq_msg_init_data.txt

@@ -0,0 +1,85 @@
+zmq_msg_init_data(3)
+====================
+
+
+NAME
+----
+zmq_msg_init_data - initialise 0MQ message from a supplied buffer
+
+
+SYNOPSIS
+--------
+*typedef void (zmq_free_fn) (void '*data', void '*hint');*
+
+*int zmq_msg_init_data (zmq_msg_t '*msg', void '*data', size_t 'size', zmq_free_fn '*ffn', void '*hint');*
+
+
+DESCRIPTION
+-----------
+The _zmq_msg_init_data()_ function shall initialise the message object
+referenced by 'msg' to represent the content referenced by the buffer located
+at address 'data', 'size' bytes long. No copy of 'data' shall be performed and
+0MQ shall take ownership of the supplied buffer.
+
+If provided, the deallocation function 'ffn' shall be called once the data
+buffer is no longer required by 0MQ, with the 'data' and 'hint' arguments
+supplied to _zmq_msg_init_data()_.
+
+CAUTION: Never access 'zmq_msg_t' members directly, instead always use the
+_zmq_msg_ family of functions.
+
+CAUTION: The deallocation function 'ffn' needs to be thread-safe, since it
+will be called from an arbitrary thread.
+
+CAUTION: The functions _zmq_msg_init()_, _zmq_msg_init_data()_ and
+_zmq_msg_init_size()_ are mutually exclusive. Never initialize the same
+'zmq_msg_t' twice.
+
+
+RETURN VALUE
+------------
+The _zmq_msg_init_data()_ function shall return zero if successful. Otherwise
+it shall return `-1` and set 'errno' to one of the values defined below.
+
+
+ERRORS
+------
+*ENOMEM*::
+Insufficient storage space is available.
+
+
+
+EXAMPLE
+-------
+.Initialising a message from a supplied buffer
+----
+void my_free (void *data, void *hint) 
+{
+    free (data);
+}
+
+    /*  ...  */
+
+void *data = malloc (6);
+assert (data);
+memcpy (data, "ABCDEF", 6);
+zmq_msg_t msg;
+rc = zmq_msg_init_data (&msg, data, 6, my_free, NULL);
+assert (rc == 0);
+----
+
+
+SEE ALSO
+--------
+linkzmq:zmq_msg_init_size[3]
+linkzmq:zmq_msg_init[3]
+linkzmq:zmq_msg_close[3]
+linkzmq:zmq_msg_data[3]
+linkzmq:zmq_msg_size[3]
+linkzmq:zmq[7]
+
+
+AUTHORS
+-------
+This 0MQ manual page was written by Martin Sustrik <sustrik@250bpm.com> and
+Martin Lucina <mato@kotelna.sk>.

data/ext/zeromq/doc/zmq_msg_init_size.txt

@@ -0,0 +1,58 @@
+zmq_msg_init_size(3)
+====================
+
+
+NAME
+----
+zmq_msg_init_size - initialise 0MQ message of a specified size
+
+
+SYNOPSIS
+--------
+*int zmq_msg_init_size (zmq_msg_t '*msg', size_t 'size');*
+
+
+DESCRIPTION
+-----------
+The _zmq_msg_init_size()_ function shall allocate any resources required to
+store a message 'size' bytes long and initialise the message object referenced
+by 'msg' to represent the newly allocated message.
+
+The implementation shall choose whether to store message content on the stack
+(small messages) or on the heap (large messages). For performance reasons
+_zmq_msg_init_size()_ shall not clear the message data.
+
+CAUTION: Never access 'zmq_msg_t' members directly, instead always use the
+_zmq_msg_ family of functions.
+
+CAUTION: The functions _zmq_msg_init()_, _zmq_msg_init_data()_ and
+_zmq_msg_init_size()_ are mutually exclusive. Never initialize the same
+'zmq_msg_t' twice.
+
+
+RETURN VALUE
+------------
+The _zmq_msg_init_size()_ function shall return zero if successful. Otherwise
+it shall return `-1` and set 'errno' to one of the values defined below.
+
+
+ERRORS
+------
+*ENOMEM*::
+Insufficient storage space is available.
+
+
+SEE ALSO
+--------
+linkzmq:zmq_msg_init_data[3]
+linkzmq:zmq_msg_init[3]
+linkzmq:zmq_msg_close[3]
+linkzmq:zmq_msg_data[3]
+linkzmq:zmq_msg_size[3]
+linkzmq:zmq[7]
+
+
+AUTHORS
+-------
+This 0MQ manual page was written by Martin Sustrik <sustrik@250bpm.com> and
+Martin Lucina <mato@kotelna.sk>.

data/ext/zeromq/doc/zmq_msg_more.txt

@@ -0,0 +1,63 @@
+zmq_msg_more(3)
+===============
+
+
+NAME
+----
+zmq_msg_more - indicate if there are more message parts to receive
+
+
+SYNOPSIS
+--------
+*int zmq_msg_more (zmq_msg_t '*message');*
+
+
+DESCRIPTION
+-----------
+The _zmq_msg_more()_ function indicates whether this is part of a multi-part
+message, and there are further parts to receive.
+
+
+RETURN VALUE
+------------
+The _zmq_msg_more()_ function shall return zero if this is the final part of
+a multi-part message, or the only part of a single-part message. It shall
+return 1 if there are further parts to receive.
+
+
+EXAMPLE
+-------
+.Receiving a multi-part message
+----
+zmq_msg_t part;
+while (true) {
+    //  Create an empty 0MQ message to hold the message part
+    int rc = zmq_msg_init (&part);
+    assert (rc == 0);
+    //  Block until a message is available to be received from socket
+    rc = zmq_recvmsg (socket, &part, 0);
+    assert (rc != -1);
+    if (zmq_msg_more (&part))
+        fprintf (stderr, "more\n");
+    else {
+        fprintf (stderr, "end\n");
+        break;
+    }
+    zmq_msg_close (part);
+}
+----
+
+
+SEE ALSO
+--------
+linkzmq:zmq_msg_get[3]
+linkzmq:zmq_msg_set[3]
+linkzmq:zmq_msg_init[3]
+linkzmq:zmq_msg_close[3]
+linkzmq:zmq[7]
+
+
+AUTHORS
+-------
+This 0MQ manual page was written by Chuck Remes <cremes@mac.com> and Pieter
+Hintjens <ph@imatix.com>.

data/ext/zeromq/doc/zmq_msg_move.txt

@@ -0,0 +1,52 @@
+zmq_msg_move(3)
+===============
+
+
+NAME
+----
+zmq_msg_move - move content of a message to another message
+
+
+SYNOPSIS
+--------
+*int zmq_msg_move (zmq_msg_t '*dest', zmq_msg_t '*src');*
+
+
+DESCRIPTION
+-----------
+The _zmq_msg_move()_ function shall move the content of the message object
+referenced by 'src' to the message object referenced by 'dest'. No actual
+copying of message content is performed, 'dest' is simply updated to reference
+the new content. 'src' becomes an empty message after calling _zmq_msg_move()_.
+The original content of 'dest', if any, shall be released.
+
+CAUTION: Never access 'zmq_msg_t' members directly, instead always use the
+_zmq_msg_ family of functions.
+
+
+RETURN VALUE
+------------
+The _zmq_msg_move()_ function shall return zero if successful. Otherwise it
+shall return `-1` and set 'errno' to one of the values defined below.
+
+
+ERRORS
+------
+*EFAULT*::
+Invalid message.
+
+
+SEE ALSO
+--------
+linkzmq:zmq_msg_copy[3]
+linkzmq:zmq_msg_init[3]
+linkzmq:zmq_msg_init_size[3]
+linkzmq:zmq_msg_init_data[3]
+linkzmq:zmq_msg_close[3]
+linkzmq:zmq[7]
+
+
+AUTHORS
+-------
+This 0MQ manual page was written by Martin Sustrik <sustrik@250bpm.com> and
+Martin Lucina <mato@kotelna.sk>.

data/ext/zeromq/doc/zmq_msg_recv.txt

@@ -0,0 +1,125 @@
+zmq_msg_recv(3)
+===============
+
+
+NAME
+----
+zmq_msg_recv - receive a message part from a socket
+
+
+SYNOPSIS
+--------
+*int zmq_msg_recv (zmq_msg_t '*msg', void '*socket', int 'flags');*
+
+
+DESCRIPTION
+-----------
+The _zmq_msg_recv()_ function is identical to linkzmq:zmq_recvmsg[3], which
+shall be deprecated in future versions. _zmq_msg_recv()_ is more consistent
+with other message manipulation functions.
+
+The _zmq_msg_recv()_ function shall receive a message part from the socket
+referenced by the 'socket' argument and store it in the message referenced by
+the 'msg' argument. Any content previously stored in 'msg' shall be properly
+deallocated. If there are no message parts available on the specified 'socket'
+the _zmq_msg_recv()_ function shall block until the request can be satisfied.
+The 'flags' argument is a combination of the flags defined below:
+
+*ZMQ_DONTWAIT*::
+Specifies that the operation should be performed in non-blocking mode. If there
+are no messages available on the specified 'socket', the _zmq_msg_recv()_
+function shall fail with 'errno' set to EAGAIN.
+
+
+Multi-part messages
+~~~~~~~~~~~~~~~~~~~
+A 0MQ message is composed of 1 or more message parts. Each message
+part is an independent 'zmq_msg_t' in its own right. 0MQ ensures atomic
+delivery of messages: peers shall receive either all _message parts_ of a
+message or none at all. The total number of message parts is unlimited except
+by available memory.
+
+An application that processes multi-part messages must use the _ZMQ_RCVMORE_
+linkzmq:zmq_getsockopt[3] option after calling _zmq_msg_recv()_ to determine if
+there are further parts to receive.
+
+
+RETURN VALUE
+------------
+The _zmq_msg_recv()_ function shall return number of bytes in the message
+if successful. Otherwise it shall return `-1` and set 'errno' to one of the
+values defined below.
+
+
+ERRORS
+------
+*EAGAIN*::
+Non-blocking mode was requested and no messages are available at the moment.
+*ENOTSUP*::
+The _zmq_msg_recv()_ operation is not supported by this socket type.
+*EFSM*::
+The _zmq_msg_recv()_ operation cannot be performed on this socket at the moment
+due to the socket not being in the appropriate state.  This error may occur with
+socket types that switch between several states, such as ZMQ_REP.  See the
+_messaging patterns_ section of linkzmq:zmq_socket[3] for more information.
+*ETERM*::
+The 0MQ 'context' associated with the specified 'socket' was terminated.
+*ENOTSOCK*::
+The provided 'socket' was invalid.
+*EINTR*::
+The operation was interrupted by delivery of a signal before a message was
+available.
+*EFAULT*::
+The message passed to the function was invalid.
+
+
+EXAMPLE
+-------
+.Receiving a message from a socket
+----
+/* Create an empty 0MQ message */
+zmq_msg_t msg;
+int rc = zmq_msg_init (&msg);
+assert (rc == 0);
+/* Block until a message is available to be received from socket */
+rc = zmq_msg_recv (&msg, socket, 0);
+assert (rc != -1);
+/* Release message */
+zmq_msg_close (&msg);
+----
+
+.Receiving a multi-part message
+----
+int64_t more;
+size_t more_size = sizeof more;
+do {
+    /* Create an empty 0MQ message to hold the message part */
+    zmq_msg_t part;
+    int rc = zmq_msg_init (&part);
+    assert (rc == 0);
+    /* Block until a message is available to be received from socket */
+    rc = zmq_msg_recv (&part, socket, 0);
+    assert (rc != -1);
+    /* Determine if more message parts are to follow */
+    rc = zmq_getsockopt (socket, ZMQ_RCVMORE, &more, &more_size);
+    assert (rc == 0);
+    zmq_msg_close (&part);
+} while (more);
+----
+
+
+SEE ALSO
+--------
+linkzmq:zmq_recv[3]
+linkzmq:zmq_send[3]
+linkzmq:zmq_msg_send[3]
+linkzmq:zmq_getsockopt[3]
+linkzmq:zmq_socket[7]
+linkzmq:zmq[7]
+
+
+AUTHORS
+-------
+This man page was written by Martin Sustrik <sustrik@250bpm.com>, Martin
+Lucina <martin@lucina.net>, and Pieter Hintjens <ph@imatix.com>.
+