rbczmq 1.6.2 → 1.6.4

data/ext/zeromq/doc/zmq_ctx_destroy.txt

@@ -0,0 +1,66 @@
+zmq_ctx_destroy(3)
+==================
+
+
+NAME
+----
+zmq_ctx_destroy - destroy a 0MQ context
+
+
+SYNOPSIS
+--------
+*int zmq_ctx_destroy (void '*context');*
+
+
+DESCRIPTION
+-----------
+The _zmq_ctx_destroy()_ function shall destroy the 0MQ context 'context'.
+
+Context termination is performed in the following steps:
+
+1. Any blocking operations currently in progress on sockets open within
+   'context' shall return immediately with an error code of ETERM.  With the
+   exception of _zmq_close()_, any further operations on sockets open within
+   'context' shall fail with an error code of ETERM.
+
+2. After interrupting all blocking calls, _zmq_ctx_destroy()_ shall _block_ until the
+   following conditions are satisfied:
+
+   * All sockets open within 'context' have been closed with _zmq_close()_.
+
+   * For each socket within 'context', all messages sent by the application
+     with _zmq_send()_ have either been physically transferred to a network
+     peer, or the socket's linger period set with the _ZMQ_LINGER_ socket
+     option has expired.
+
+For further details regarding socket linger behavior refer to the _ZMQ_LINGER_
+option in linkzmq:zmq_setsockopt[3].
+
+This function replaces the deprecated function linkzmq:zmq_term[3].
+
+
+RETURN VALUE
+------------
+The _zmq_ctx_destroy()_ function shall return zero if successful. Otherwise
+it shall return `-1` and set 'errno' to one of the values defined below.
+
+
+ERRORS
+------
+*EFAULT*::
+The provided 'context' was invalid.
+*EINTR*::
+Termination was interrupted by a signal. It can be restarted if needed.
+
+
+SEE ALSO
+--------
+linkzmq:zmq[7]
+linkzmq:zmq_init[3]
+linkzmq:zmq_close[3]
+linkzmq:zmq_setsockopt[3]
+
+
+AUTHORS
+-------
+This 0MQ manual page was written by Pieter Hintjens <ph@imatix.com>

data/ext/zeromq/doc/zmq_ctx_get.txt

@@ -0,0 +1,67 @@
+zmq_ctx_get(3)
+==============
+
+
+NAME
+----
+
+zmq_ctx_get - get context options
+
+
+SYNOPSIS
+--------
+*int zmq_ctx_get (void '*context', int 'option_name');*
+
+
+DESCRIPTION
+-----------
+The _zmq_ctx_get()_ function shall return the option specified by the
+'option_name' argument.
+
+The _zmq_ctx_get()_ function accepts the following option names:
+
+
+ZMQ_IO_THREADS: Get number of I/O threads
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The 'ZMQ_IO_THREADS' argument returns the size of the 0MQ thread pool
+for this context.
+
+ZMQ_MAX_SOCKETS: Set maximum number of sockets
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The 'ZMQ_MAX_SOCKETS' argument returns the maximum number of sockets
+allowed for this context.
+
+
+RETURN VALUE
+------------
+The _zmq_ctx_get()_ function returns a value of 0 or greater if successful.
+Otherwise it returns `-1` and sets 'errno' to one of the values defined
+below.
+
+
+ERRORS
+------
+*EINVAL*::
+The requested option _option_name_ is unknown.
+
+
+EXAMPLE
+-------
+.Setting a limit on the number of sockets
+----
+void *context = zmq_ctx_new ();
+zmq_ctx_get (context, ZMQ_MAX_SOCKETS, 256);
+int max_sockets = zmq_ctx_get (context, ZMQ_MAX_SOCKETS);
+assert (max_sockets == 256);
+----
+
+
+SEE ALSO
+--------
+linkzmq:zmq_ctx_set[3]
+linkzmq:zmq[7]
+
+
+AUTHORS
+-------
+This 0MQ manual page was written by Pieter Hintjens <ph@imatix.com>

data/ext/zeromq/doc/zmq_ctx_new.txt

@@ -0,0 +1,49 @@
+zmq_ctx_new(3)
+==============
+
+
+NAME
+----
+zmq_ctx_new - create new 0MQ context
+
+
+SYNOPSIS
+--------
+*void *zmq_ctx_new ();*
+
+
+DESCRIPTION
+-----------
+The _zmq_ctx_new()_ function creates a new 0MQ 'context'.
+
+This function replaces the deprecated function linkzmq:zmq_init[3].
+
+.Thread safety
+A 0MQ 'context' is thread safe and may be shared among as many application
+threads as necessary, without any additional locking required on the part of
+the caller.
+
+
+RETURN VALUE
+------------
+The _zmq_ctx_new()_ function shall return an opaque handle to the newly created
+'context' if successful. Otherwise it shall return NULL and set 'errno' to one
+of the values defined below.
+
+
+ERRORS
+------
+No error values are defined for this function.
+
+
+SEE ALSO
+--------
+linkzmq:zmq[7]
+linkzmq:zmq_ctx_set[3]
+linkzmq:zmq_ctx_get[3]
+linkzmq:zmq_ctx_destroy[3]
+
+
+AUTHORS
+-------
+This 0MQ manual page was written by Pieter Hintjens <ph@imatix.com>

data/ext/zeromq/doc/zmq_ctx_set.txt

@@ -0,0 +1,75 @@
+zmq_ctx_set(3)
+==============
+
+
+NAME
+----
+
+zmq_ctx_set - set context options
+
+
+SYNOPSIS
+--------
+*int zmq_ctx_set (void '*context', int 'option_name', int 'option_value');*
+
+
+DESCRIPTION
+-----------
+The _zmq_ctx_set()_ function shall set the option specified by the
+'option_name' argument to the value of the 'option_value' argument.
+
+The _zmq_ctx_set()_ function accepts the following options:
+
+
+ZMQ_IO_THREADS: Set number of I/O threads
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The 'ZMQ_IO_THREADS' argument specifies the size of the 0MQ thread pool to
+handle I/O operations. If your application is using only the 'inproc'
+transport for messaging you may set this to zero, otherwise set it to at
+least one. This option only applies before creating any sockets on the
+context.
+
+[horizontal]
+Default value:: 1
+
+ZMQ_MAX_SOCKETS: Set maximum number of sockets
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The 'ZMQ_MAX_SOCKETS' argument sets the maximum number of sockets allowed
+on the context.
+
+[horizontal]
+Default value:: 1024
+
+
+RETURN VALUE
+------------
+The _zmq_ctx_set()_ function returns zero if successful. Otherwise it
+returns `-1` and sets 'errno' to one of the values defined below.
+
+
+ERRORS
+------
+*EINVAL*::
+The requested option _option_name_ is unknown.
+
+
+EXAMPLE
+-------
+.Setting a limit on the number of sockets
+----
+void *context = zmq_ctx_new ();
+zmq_ctx_set (context, ZMQ_MAX_SOCKETS, 256);
+int max_sockets = zmq_ctx_get (context, ZMQ_MAX_SOCKETS);
+assert (max_sockets == 256);
+----
+
+
+SEE ALSO
+--------
+linkzmq:zmq_ctx_get[3]
+linkzmq:zmq[7]
+
+
+AUTHORS
+-------
+This 0MQ manual page was written by Pieter Hintjens <ph@imatix.com>

data/ext/zeromq/doc/zmq_disconnect.txt

@@ -0,0 +1,67 @@
+zmq_disconnect(3)
+=================
+
+
+NAME
+----
+zmq_disconnect - Disconnect a socket
+
+
+SYNOPSIS
+--------
+int zmq_disconnect (void '*socket', const char '*endpoint');
+
+
+DESCRIPTION
+-----------
+The _zmq_disconnect()_ function shall disconnect a socket specified
+by the 'socket' argument from the endpoint specified by the 'endpoint'
+argument. 
+
+The 'endpoint' argument is as described in linkzmq:zmq_connect[3]
+
+
+RETURN VALUE
+------------
+The _zmq_disconnect()_ function shall return zero if successful. Otherwise it
+shall return `-1` and set 'errno' to one of the values defined below.
+
+ERRORS
+------
+*EINVAL*::
+The endpoint supplied is invalid.
+*ETERM*::
+The 0MQ 'context' associated with the specified 'socket' was terminated.
+*ENOTSOCK*::
+The provided 'socket' was invalid.
+*ENOENT*::
+The provided endpoint is not connected.
+
+
+EXAMPLE
+-------
+.Connecting a subscriber socket to an in-process and a TCP transport
+----
+/* Create a ZMQ_SUB socket */
+void *socket = zmq_socket (context, ZMQ_SUB);
+assert (socket);
+/* Connect it to the host server001, port 5555 using a TCP transport */
+rc = zmq_connect (socket, "tcp://server001:5555");
+assert (rc == 0);
+/* Disconnect from the previously connected endpoint */
+rc = zmq_disconnect (socket, "tcp://server001:5555");
+assert (rc == 0);
+----
+
+
+SEE ALSO
+--------
+linkzmq:zmq_connect[3]
+linkzmq:zmq_socket[3]
+linkzmq:zmq[7]
+
+
+AUTHORS
+-------
+This 0MQ manual page was written by Martin Sustrik <sustrik@250bpm.com>,
+Martin Lucina <mato@kotelna.sk> and Ian Barber <ian.barber@gmail.com>

data/ext/zeromq/doc/zmq_epgm.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>.