rbczmq 1.6.2 → 1.6.4

data/ext/zeromq/doc/zmq_msg_send.txt

@@ -0,0 +1,122 @@
+zmq_msg_send(3)
+===============
+
+
+NAME
+----
+zmq_msg_send - send a message part on a socket
+
+
+SYNOPSIS
+--------
+*int zmq_msg_send (zmq_msg_t '*msg', void '*socket', int 'flags');*
+
+
+DESCRIPTION
+-----------
+The _zmq_msg_send()_ function is identical to linkzmq:zmq_sendmsg[3], which
+shall be deprecated in future versions. _zmq_msg_send()_ is more consistent
+with other message manipulation functions.
+
+The _zmq_msg_send()_ function shall queue the message referenced by the 'msg'
+argument to be sent to the socket referenced by the 'socket' argument.  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 the
+message cannot be queued on the 'socket', the _zmq_msg_send()_ function shall
+fail with 'errno' set to EAGAIN.
+
+*ZMQ_SNDMORE*::
+Specifies that the message being sent is a multi-part message, and that further
+message parts are to follow. Refer to the section regarding multi-part messages
+below for a detailed description.
+
+The _zmq_msg_t_ structure passed to _zmq_msg_send()_ is nullified during the
+call. If you want to send the same message to multiple sockets you have to copy
+it using (e.g. using _zmq_msg_copy()_).
+
+NOTE: A successful invocation of _zmq_msg_send()_ does not indicate that the
+message has been transmitted to the network, only that it has been queued on
+the 'socket' and 0MQ has assumed responsibility for the message.
+
+
+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 sends multi-part messages must use the _ZMQ_SNDMORE_ flag
+when sending each message part except the final one.
+
+RETURN VALUE
+------------
+The _zmq_msg_send()_ 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 the message cannot be sent at the moment.
+*ENOTSUP*::
+The _zmq_msg_send()_ operation is not supported by this socket type.
+*EFSM*::
+The _zmq_msg_send()_ 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 the message was
+sent.
+*EFAULT*::
+Invalid message.
+
+
+EXAMPLE
+-------
+.Filling in a message and sending it to a socket
+----
+/* Create a new message, allocating 6 bytes for message content */
+zmq_msg_t msg;
+int rc = zmq_msg_init_size (&msg, 6);
+assert (rc == 0);
+/* Fill in message content with 'AAAAAA' */
+memset (zmq_msg_data (&msg), 'A', 6);
+/* Send the message to the socket */
+rc = zmq_msg_send (&msg, socket, 0);
+assert (rc == 6);
+----
+
+.Sending a multi-part message
+----
+/* Send a multi-part message consisting of three parts to socket */
+rc = zmq_msg_send (&part1, socket, ZMQ_SNDMORE);
+rc = zmq_msg_send (&part2, socket, ZMQ_SNDMORE);
+/* Final part; no more parts to follow */
+rc = zmq_msg_send (&part3, socket, 0);
+----
+
+
+SEE ALSO
+--------
+linkzmq:zmq_recv[3]
+linkzmq:zmq_send[3]
+linkzmq:zmq_msg_recv[3]
+linkzmq:zmq_socket[7]
+linkzmq:zmq[7]
+
+
+AUTHORS
+-------
+This 0MQ manual page was written by Martin Sustrik <sustrik@250bpm.com> and
+Martin Lucina <mato@kotelna.sk>, and Pieter Hintjens <ph@imatix.com>.
+

data/ext/zeromq/doc/zmq_msg_set.txt

@@ -0,0 +1,45 @@
+zmq_msg_set(3)
+==============
+
+
+NAME
+----
+
+zmq_msg_set - set message property
+
+
+SYNOPSIS
+--------
+*int zmq_msg_set (zmq_msg_t '*message', int 'property', int 'value');*
+
+
+DESCRIPTION
+-----------
+The _zmq_msg_set()_ function shall set the property specified by the
+'property' argument to the value of the 'value' argument for the 0MQ
+message fragment pointed to by the 'message' argument.
+
+Currently the _zmq_msg_set()_ function does not support any property names.
+
+
+RETURN VALUE
+------------
+The _zmq_msg_set()_ function shall return zero if successful. Otherwise it
+shall return `-1` and set 'errno' to one of the values defined below.
+
+
+ERRORS
+------
+*EINVAL*::
+The requested property _property_ is unknown.
+
+
+SEE ALSO
+--------
+linkzmq:zmq_msg_get[3]
+linkzmq:zmq[7]
+
+
+AUTHORS
+-------
+This 0MQ manual page was written by Pieter Hintjens <ph@imatix.com>.

data/ext/zeromq/doc/zmq_msg_size.txt

@@ -0,0 +1,48 @@
+zmq_msg_size(3)
+===============
+
+
+NAME
+----
+zmq_msg_size - retrieve message content size in bytes
+
+
+SYNOPSIS
+--------
+*size_t zmq_msg_size (zmq_msg_t '*msg');*
+
+
+DESCRIPTION
+-----------
+The _zmq_msg_size()_ function shall return the size in bytes of the content of
+the message object referenced by 'msg'.
+
+CAUTION: Never access 'zmq_msg_t' members directly, instead always use the
+_zmq_msg_ family of functions.
+
+
+RETURN VALUE
+------------
+Upon successful completion, _zmq_msg_size()_ shall return the size of the
+message content in bytes.
+
+
+ERRORS
+------
+No errors are defined.
+
+
+SEE ALSO
+--------
+linkzmq:zmq_msg_data[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>,
+Martin Lucina <mato@kotelna.sk>, and Pieter Hintjens <ph@imatix.com>.

data/ext/zeromq/doc/zmq_pgm.txt

@@ -0,0 +1,162 @@
+zmq_pgm(7)
+==========
+
+
+NAME
+----
+zmq_pgm - 0MQ reliable multicast transport using PGM
+
+
+SYNOPSIS
+--------
+PGM (Pragmatic General Multicast) is a protocol for reliable multicast
+transport of data over IP networks.
+
+
+DESCRIPTION
+-----------
+0MQ implements two variants of PGM, the standard protocol where PGM datagrams
+are layered directly on top of IP datagrams as defined by RFC 3208 (the 'pgm'
+transport) and "Encapsulated PGM" or EPGM where PGM datagrams are encapsulated
+inside UDP datagrams (the 'epgm' transport).
+
+The 'pgm' and 'epgm' transports can only be used with the 'ZMQ_PUB' and
+'ZMQ_SUB' socket types.
+
+Further, PGM sockets are rate limited by default. For details, refer to the
+'ZMQ_RATE', and 'ZMQ_RECOVERY_IVL' options documented in
+linkzmq:zmq_setsockopt[3].
+
+CAUTION: The 'pgm' transport implementation requires access to raw IP sockets.
+Additional privileges may be required on some operating systems for this
+operation. Applications not requiring direct interoperability with other PGM
+implementations are encouraged to use the 'epgm' transport instead which does
+not require any special privileges.
+
+
+ADDRESSING
+----------
+A 0MQ endpoint is a string consisting of a 'transport'`://` followed by an
+'address'. The 'transport' specifies the underlying protocol to use. The
+'address' specifies the transport-specific address to connect to.
+
+For the PGM transport, the transport is `pgm`, and for the EPGM protocol the
+transport is `epgm`. The meaning of the 'address' part is defined below.
+
+
+Connecting a socket
+~~~~~~~~~~~~~~~~~~~
+When connecting a socket to a peer address using _zmq_connect()_ with the 'pgm'
+or 'epgm' transport, the 'endpoint' shall be interpreted as an 'interface'
+followed by a semicolon, followed by a 'multicast address', followed by a colon
+and a port number.
+
+An 'interface' may be specified by either of the following:
+
+* The interface name as defined by the operating system.
+* The primary IPv4 address assigned to the interface, in it's numeric
+  representation.
+
+NOTE: Interface names are not standardised in any way and should be assumed to
+be arbitrary and platform dependent. On Win32 platforms no short interface
+names exist, thus only the primary IPv4 address may be used to specify an
+'interface'. The 'interface' part can be omitted, in that case the default one
+will be selected.
+
+A 'multicast address' is specified by an IPv4 multicast address in it's numeric
+representation.
+
+
+WIRE FORMAT
+-----------
+Consecutive PGM datagrams are interpreted by 0MQ as a single continuous stream
+of data where 0MQ messages are not necessarily aligned with PGM datagram
+boundaries and a single 0MQ message may span several PGM datagrams. This stream
+of data consists of 0MQ messages encapsulated in 'frames' as described in
+linkzmq:zmq_tcp[7].
+
+
+PGM datagram payload
+~~~~~~~~~~~~~~~~~~~~
+The following ABNF grammar represents the payload of a single PGM datagram as
+used by 0MQ:
+
+....
+datagram               = (offset data)
+offset                 = 2OCTET
+data                   = *OCTET
+....
+
+In order for late joining consumers to be able to identify message boundaries,
+each PGM datagram payload starts with a 16-bit unsigned integer in network byte
+order specifying either the offset of the first message 'frame' in the datagram
+or containing the value `0xFFFF` if the datagram contains solely an
+intermediate part of a larger message.
+
+Note that offset specifies where the first message begins rather than the first
+message part. Thus, if there are trailing message parts at the beginning of
+the packet the offset ignores them and points to first initial message part
+in the packet.
+
+The following diagram illustrates the layout of a single PGM datagram payload:
+
+....
++------------------+----------------------+
+| offset (16 bits) |         data         |
++------------------+----------------------+
+....
+
+The following diagram further illustrates how three example 0MQ frames are laid
+out in consecutive PGM datagram payloads:
+
+....
+First datagram payload
++--------------+-------------+---------------------+
+| Frame offset |   Frame 1   |   Frame 2, part 1   |
+|    0x0000    | (Message 1) | (Message 2, part 1) |
++--------------+-------------+---------------------+
+
+Second datagram payload
++--------------+---------------------+
+| Frame offset |   Frame 2, part 2   |
+| 0xFFFF       | (Message 2, part 2) |
++--------------+---------------------+
+
+Third datagram payload
++--------------+----------------------------+-------------+
+| Frame offset |   Frame 2, final 8 bytes   |   Frame 3   |
+| 0x0008       | (Message 2, final 8 bytes) | (Message 3) |
++--------------+----------------------------+-------------+
+....
+
+
+EXAMPLE
+-------
+.Connecting a socket
+----
+//  Connecting to the multicast address 239.192.1.1, port 5555,
+//  using the first Ethernet network interface on Linux
+//  and the Encapsulated PGM protocol
+rc = zmq_connect(socket, "epgm://eth0;239.192.1.1:5555");
+assert (rc == 0);
+//  Connecting to the multicast address 239.192.1.1, port 5555,
+//  using the network interface with the address 192.168.1.1
+//  and the standard PGM protocol
+rc = zmq_connect(socket, "pgm://192.168.1.1;239.192.1.1:5555");
+assert (rc == 0);
+----
+
+
+SEE ALSO
+--------
+linkzmq:zmq_connect[3]
+linkzmq:zmq_setsockopt[3]
+linkzmq:zmq_tcp[7]
+linkzmq:zmq_ipc[7]
+linkzmq:zmq_inproc[7]
+linkzmq:zmq[7]
+
+AUTHORS
+-------
+This 0MQ manual page was written by Pieter Hintjens <ph@imatix.com>,
+Martin Sustrik <sustrik@250bpm.com> and Martin Lucina <mato@kotelna.sk>.

data/ext/zeromq/doc/zmq_poll.txt

@@ -0,0 +1,132 @@
+zmq_poll(3)
+===========
+
+
+NAME
+----
+zmq_poll - input/output multiplexing
+
+
+SYNOPSIS
+--------
+
+*int zmq_poll (zmq_pollitem_t '*items', int 'nitems', long 'timeout');*
+
+
+DESCRIPTION
+-----------
+The _zmq_poll()_ function provides a mechanism for applications to multiplex
+input/output events in a level-triggered fashion over a set of sockets. Each
+member of the array pointed to by the 'items' argument is a *zmq_pollitem_t*
+structure. The 'nitems' argument specifies the number of items in the 'items'
+array. The *zmq_pollitem_t* structure is defined as follows:
+
+["literal", subs="quotes"]
+typedef struct
+{
+    void '*socket';
+    int 'fd';
+    short 'events';
+    short 'revents';
+} zmq_pollitem_t;
+
+For each *zmq_pollitem_t* item, _zmq_poll()_ shall examine either the 0MQ
+socket referenced by 'socket' *or* the standard socket specified by the file
+descriptor 'fd', for the event(s) specified in 'events'. If both 'socket' and
+'fd' are set in a single *zmq_pollitem_t*, the 0MQ socket referenced by
+'socket' shall take precedence and the value of 'fd' shall be ignored.
+
+For each *zmq_pollitem_t* item, _zmq_poll()_ shall first clear the 'revents'
+member, and then indicate any requested events that have occurred by setting the
+bit corresponding to the event condition in the 'revents' member.
+
+If none of the requested events have occurred on any *zmq_pollitem_t* item,
+_zmq_poll()_ shall wait 'timeout' milliseconds for an event to occur on
+any of the requested items. If the value of 'timeout' is `0`, _zmq_poll()_
+shall return immediately. If the value of 'timeout' is `-1`, _zmq_poll()_ shall
+block indefinitely until a requested event has occurred on at least one
+*zmq_pollitem_t*.
+
+The 'events' and 'revents' members of *zmq_pollitem_t* are bit masks constructed
+by OR'ing a combination of the following event flags:
+
+*ZMQ_POLLIN*::
+For 0MQ sockets, at least one message may be received from the 'socket' without
+blocking. For standard sockets this is equivalent to the 'POLLIN' flag of the
+_poll()_ system call and generally means that at least one byte of data may be
+read from 'fd' without blocking.
+
+*ZMQ_POLLOUT*::
+For 0MQ sockets, at least one message may be sent to the 'socket' without
+blocking. For standard sockets this is equivalent to the 'POLLOUT' flag of the
+_poll()_ system call and generally means that at least one byte of data may be
+written to 'fd' without blocking.
+
+*ZMQ_POLLERR*::
+For standard sockets, this flag is passed through _zmq_poll()_ to the
+underlying _poll()_ system call and generally means that some sort of error
+condition is present on the socket specified by 'fd'. For 0MQ sockets this flag
+has no effect if set in 'events', and shall never be returned in 'revents' by
+_zmq_poll()_.
+
+NOTE: The _zmq_poll()_ function may be implemented or emulated using operating
+system interfaces other than _poll()_, and as such may be subject to the limits
+of those interfaces in ways not defined in this documentation.
+
+NOTE: The _zmq_send()_ function will clear all pending events on a socket. Thus,
+if you use _zmq_poll()_ to monitor input on a socket, use it before output as
+well, and process all events after each _zmq_poll()_ call.
+
+RETURN VALUE
+------------
+Upon successful completion, the _zmq_poll()_ function shall return the number
+of *zmq_pollitem_t* structures with events signaled in 'revents' or `0` if no
+events have been signaled. Upon failure, _zmq_poll()_ shall return `-1` and set
+'errno' to one of the values defined below.
+
+
+ERRORS
+------
+*ETERM*::
+At least one of the members of the 'items' array refers to a 'socket' whose
+associated 0MQ 'context' was terminated.
+*EFAULT*::
+The provided 'items' was not valid (NULL).
+*EINTR*::
+The operation was interrupted by delivery of a signal before any events were
+available.
+
+
+EXAMPLE
+-------
+.Polling indefinitely for input events on both a 0MQ socket and a standard socket.
+----
+zmq_pollitem_t items [2];
+/* First item refers to 0MQ socket 'socket' */
+items[0].socket = socket;
+items[0].events = ZMQ_POLLIN;
+/* Second item refers to standard socket 'fd' */
+items[1].socket = NULL;
+items[1].fd = fd;
+items[1].events = ZMQ_POLLIN;
+/* Poll for events indefinitely */
+int rc = zmq_poll (items, 2, -1);
+assert (rc >= 0);
+/* Returned events will be stored in items[].revents */
+----
+
+
+SEE ALSO
+--------
+linkzmq:zmq_socket[3]
+linkzmq:zmq_send[3]
+linkzmq:zmq_recv[3]
+linkzmq:zmq[7]
+
+Your operating system documentation for the _poll()_ system call.
+
+
+AUTHORS
+-------
+This 0MQ manual page was written by Martin Sustrik <sustrik@250bpm.com> and
+Martin Lucina <mato@kotelna.sk>.