rbczmq 1.6.2 → 1.6.4

data/ext/zeromq/doc/asciidoc.conf

@@ -0,0 +1,56 @@
+[paradef-default]
+literal-style=template="literalparagraph"
+
+[macros]
+(?su)[\\]?(?P<name>linkzmq):(?P<target>\S*?)\[(?P<attrlist>.*?)\]=
+
+ifdef::backend-docbook[]
+[linkzmq-inlinemacro]
+{0%{target}}
+{0#<citerefentry>}
+{0#<refentrytitle>{target}</refentrytitle><manvolnum>{0}</manvolnum>}
+{0#</citerefentry>}
+endif::backend-docbook[]
+
+ifdef::backend-xhtml11[]
+[linkzmq-inlinemacro]
+<a href="{target}.html">{target}{0?({0})}</a>
+endif::backend-xhtml11[]
+
+ifdef::doctype-manpage[]
+ifdef::backend-docbook[]
+[header]
+template::[header-declarations]
+<refentry>
+<refmeta>
+<refentrytitle>{mantitle}</refentrytitle>
+<manvolnum>{manvolnum}</manvolnum>
+<refmiscinfo class="source">0MQ</refmiscinfo>
+<refmiscinfo class="version">{zmq_version}</refmiscinfo>
+<refmiscinfo class="manual">0MQ Manual</refmiscinfo>
+</refmeta>
+<refnamediv>
+  <refname>{manname}</refname>
+  <refpurpose>{manpurpose}</refpurpose>
+</refnamediv>
+endif::backend-docbook[]
+endif::doctype-manpage[]
+
+ifdef::backend-xhtml11[]
+[footer]
+</div>
+{disable-javascript%<div id="footnotes"><hr /></div>}
+<div id="footer">
+<div id="footer-text">
+ØMQ {zmq_version}<br />
+Last updated {docdate} {doctime}
+</div>
+</div>
+</body>
+</html>
+endif::backend-xhtml11[]
+
+[replacements]
+ifdef::backend-xhtml11[]
+0MQ=ØMQ
+endif::backend-xhtml11[]

data/ext/zeromq/doc/zmq.txt

@@ -0,0 +1,233 @@
+zmq(7)
+======
+
+
+NAME
+----
+zmq - 0MQ lightweight messaging kernel
+
+
+SYNOPSIS
+--------
+*#include <zmq.h>*
+
+*cc* ['flags'] 'files' *-lzmq* ['libraries']
+
+
+DESCRIPTION
+-----------
+The 0MQ lightweight messaging kernel is a library which extends the standard
+socket interfaces with features traditionally provided by specialised
+_messaging middleware_ products. 0MQ sockets provide an abstraction of
+asynchronous _message queues_, multiple _messaging patterns_, message
+filtering (_subscriptions_), seamless access to multiple _transport protocols_
+and more.
+
+This documentation presents an overview of 0MQ concepts, describes how 0MQ
+abstracts standard sockets and provides a reference manual for the functions
+provided by the 0MQ library.
+
+
+Context
+~~~~~~~
+Before using any 0MQ library functions you must create a 0MQ 'context'. When
+you exit your application you must destroy the 'context'. These functions let
+you work with 'contexts':
+
+Create a new 0MQ context::
+    linkzmq:zmq_ctx_new[3]
+
+Work with context properties::
+    linkzmq:zmq_ctx_set[3]
+    linkzmq:zmq_ctx_get[3]
+
+Destroy a 0MQ context::
+    linkzmq:zmq_ctx_destroy[3]
+
+Monitor a 0MQ context::
+    linkzmq:zmq_ctx_set_monitor[3]
+
+These deprecated functions let you create and destroy 'contexts':
+
+Initialise 0MQ context::
+    linkzmq:zmq_init[3]
+
+Terminate 0MQ context::
+    linkzmq:zmq_term[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.
+
+Individual 0MQ 'sockets' are _not_ thread safe except in the case where full
+memory barriers are issued when migrating a socket from one thread to another.
+In practice this means applications can create a socket in one thread with
+_zmq_socket()_ and then pass it to a _newly created_ thread as part of thread
+initialization, for example via a structure passed as an argument to
+_pthread_create()_.
+
+
+Multiple contexts
+^^^^^^^^^^^^^^^^^
+Multiple 'contexts' may coexist within a single application. Thus, an
+application can use 0MQ directly and at the same time make use of any number of
+additional libraries or components which themselves make use of 0MQ as long as
+the above guidelines regarding thread safety are adhered to.
+
+
+Messages
+~~~~~~~~
+A 0MQ message is a discrete unit of data passed between applications or
+components of the same application. 0MQ messages have no internal structure and
+from the point of view of 0MQ itself they are considered to be opaque binary
+data.
+
+The following functions are provided to work with messages:
+
+Initialise a message::
+    linkzmq:zmq_msg_init[3]
+    linkzmq:zmq_msg_init_size[3]
+    linkzmq:zmq_msg_init_data[3]
+
+Sending and receiving a message::
+    linkzmq:zmq_msg_send[3]
+    linkzmq:zmq_msg_recv[3]
+
+Release a message::
+    linkzmq:zmq_msg_close[3]
+
+Access message content::
+    linkzmq:zmq_msg_data[3]
+    linkzmq:zmq_msg_size[3]
+    linkzmq:zmq_msg_more[3]
+
+Work with message properties::
+    linkzmq:zmq_msg_get[3]
+    linkzmq:zmq_msg_set[3]
+
+Message manipulation::
+    linkzmq:zmq_msg_copy[3]
+    linkzmq:zmq_msg_move[3]
+
+
+Sockets
+~~~~~~~
+0MQ sockets present an abstraction of a asynchronous _message queue_, with the
+exact queueing semantics depending on the socket type in use. See
+linkzmq:zmq_socket[3] for the socket types provided.
+
+The following functions are provided to work with sockets:
+
+Creating a socket::
+    linkzmq:zmq_socket[3]
+
+Closing a socket::
+    linkzmq:zmq_close[3]
+
+Manipulating socket options::
+    linkzmq:zmq_getsockopt[3]
+    linkzmq:zmq_setsockopt[3]
+
+Establishing a message flow::
+    linkzmq:zmq_bind[3]
+    linkzmq:zmq_connect[3]
+
+Sending and receiving messages::
+    linkzmq:zmq_msg_send[3]
+    linkzmq:zmq_msg_recv[3]
+    linkzmq:zmq_send[3]
+    linkzmq:zmq_recv[3]
+
+.Input/output multiplexing
+0MQ provides a mechanism for applications to multiplex input/output events over
+a set containing both 0MQ sockets and standard sockets. This mechanism mirrors
+the standard _poll()_ system call, and is described in detail in
+linkzmq:zmq_poll[3].
+
+
+Transports
+~~~~~~~~~~
+A 0MQ socket can use multiple different underlying transport mechanisms.
+Each transport mechanism is suited to a particular purpose and has its own
+advantages and drawbacks.
+
+The following transport mechanisms are provided:
+
+Unicast transport using TCP::
+    linkzmq:zmq_tcp[7]
+
+Reliable multicast transport using PGM::
+    linkzmq:zmq_pgm[7]
+
+Local inter-process communication transport::
+    linkzmq:zmq_ipc[7]
+
+Local in-process (inter-thread) communication transport::
+    linkzmq:zmq_inproc[7]
+
+
+Proxies
+~~~~~~~
+0MQ provides 'proxies' to create fanout and fan-in topologies. A proxy connects
+a 'frontend' socket to a 'backend' socket and switches all messages between the
+two sockets, opaquely. A proxy may optionally capture all traffic to a third
+socket. To start a proxy in an application thread, use linkzmq:zmq_proxy[3].
+
+
+ERROR HANDLING
+--------------
+The 0MQ library functions handle errors using the standard conventions found on
+POSIX systems. Generally, this means that upon failure a 0MQ library function
+shall return either a NULL value (if returning a pointer) or a negative value
+(if returning an integer), and the actual error code shall be stored in the
+'errno' variable.
+
+On non-POSIX systems some users may experience issues with retrieving the
+correct value of the 'errno' variable. The _zmq_errno()_ function is provided
+to assist in these cases; for details refer to linkzmq:zmq_errno[3].
+
+The _zmq_strerror()_ function is provided to translate 0MQ-specific error codes
+into error message strings; for details refer to linkzmq:zmq_strerror[3].
+
+
+MISCELLANEOUS
+-------------
+The following miscellaneous functions are provided:
+
+Report 0MQ library version::
+    linkzmq:zmq_version[3]
+
+
+LANGUAGE BINDINGS
+-----------------
+The 0MQ library provides interfaces suitable for calling from programs in any
+language; this documentation documents those interfaces as they would be used
+by C programmers. The intent is that programmers using 0MQ from other languages
+shall refer to this documentation alongside any documentation provided by the
+vendor of their language binding.
+
+Language bindings ($$C++$$, Python, PHP, Ruby, Java and more) are provided by
+members of the 0MQ community and pointers can be found on the 0MQ website.
+
+
+AUTHORS
+-------
+This 0MQ manual page was written by Martin Sustrik <sustrik@250bpm.com>,
+Martin Lucina <martin@lucina.net>, and Pieter Hintjens <ph@imatix.com>.
+
+
+RESOURCES
+---------
+Main web site: <http://www.zeromq.org/>
+
+Report bugs to the 0MQ development mailing list: <zeromq-dev@lists.zeromq.org>
+
+
+COPYING
+-------
+Free use of this software is granted under the terms of the GNU Lesser General
+Public License (LGPL). For details see the files `COPYING` and `COPYING.LESSER`
+included with the 0MQ distribution.

data/ext/zeromq/doc/zmq_bind.txt

@@ -0,0 +1,102 @@
+zmq_bind(3)
+===========
+
+
+NAME
+----
+zmq_bind - accept incoming connections on a socket
+
+
+SYNOPSIS
+--------
+*int zmq_bind (void '*socket', const char '*endpoint');*
+
+
+DESCRIPTION
+-----------
+The _zmq_bind()_ function binds the 'socket' to a local 'endpoint' and then
+accepts incoming connections on that endpoint.
+
+The '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 bind to.
+
+0MQ provides the the following transports:
+
+'tcp':: unicast transport using TCP, see linkzmq:zmq_tcp[7]
+'ipc':: local inter-process communication transport, see linkzmq:zmq_ipc[7]
+'inproc':: local in-process (inter-thread) communication transport, see linkzmq:zmq_inproc[7]
+'pgm', 'epgm':: reliable multicast transport using PGM, see linkzmq:zmq_pgm[7]
+
+Every 0MQ socket type except 'ZMQ_PAIR' supports one-to-many and many-to-one
+semantics. The precise semantics depend on the socket type and are defined in
+linkzmq:zmq_socket[3].
+
+The 'ipc' and 'tcp' transports accept wildcard addresses: see linkzmq:zmq_ipc[7]
+and linkzmq:zmq_tcp[7] for details.
+
+NOTE: the address syntax may be different for _zmq_bind()_ and _zmq_connect()_
+especially for the 'tcp', 'pgm' and 'epgm' transports.
+
+NOTE: following a _zmq_bind()_, the socket enters a 'mute' state unless or
+until at least one incoming or outgoing connection is made, at which point
+the socket enters a 'ready' state. In the mute state, the socket blocks or
+drops messages according to the socket type, as defined in linkzmq:zmq_socket[3].
+By contrast, following a libzmq:zmq_connect[3], the socket enters the 'ready' state.
+
+
+RETURN VALUE
+------------
+The _zmq_bind()_ function returns zero if successful. Otherwise it returns
+`-1` and sets 'errno' to one of the values defined below.
+
+
+ERRORS
+------
+*EINVAL*::
+The endpoint supplied is invalid.
+*EPROTONOSUPPORT*::
+The requested 'transport' protocol is not supported.
+*ENOCOMPATPROTO*::
+The requested 'transport' protocol is not compatible with the socket type.
+*EADDRINUSE*::
+The requested 'address' is already in use.
+*EADDRNOTAVAIL*::
+The requested 'address' was not local.
+*ENODEV*::
+The requested 'address' specifies a nonexistent interface.
+*ETERM*::
+The 0MQ 'context' associated with the specified 'socket' was terminated.
+*ENOTSOCK*::
+The provided 'socket' was invalid.
+*EMTHREAD*::
+No I/O thread is available to accomplish the task.
+
+
+EXAMPLE
+-------
+.Binding a publisher socket to an in-process and a TCP transport
+----
+/* Create a ZMQ_PUB socket */
+void *socket = zmq_socket (context, ZMQ_PUB);
+assert (socket);
+/* Bind it to a in-process transport with the address 'my_publisher' */
+int rc = zmq_bind (socket, "inproc://my_publisher");
+assert (rc == 0);
+/* Bind it to a TCP transport on port 5555 of the 'eth0' interface */
+rc = zmq_bind (socket, "tcp://eth0: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 Pieter Hintjens <ph@imatix.com>,
+Martin Sustrik <sustrik@250bpm.com> and Martin Lucina <mato@kotelna.sk>.

data/ext/zeromq/doc/zmq_close.txt

@@ -0,0 +1,52 @@
+zmq_close(3)
+============
+
+
+NAME
+----
+zmq_close - close 0MQ socket
+
+
+SYNOPSIS
+--------
+*int zmq_close (void '*socket');*
+
+
+DESCRIPTION
+-----------
+The _zmq_close()_ function shall destroy the socket referenced by the 'socket'
+argument. Any outstanding messages physically received from the network but not
+yet received by the application with _zmq_recv()_ shall be discarded. The
+behaviour for discarding messages sent by the application with _zmq_send()_ but
+not yet physically transferred to the network depends on the value of the
+_ZMQ_LINGER_ socket option for the specified 'socket'.
+
+NOTE: The default setting of _ZMQ_LINGER_ does not discard unsent messages;
+this behaviour may cause the application to block when calling _zmq_term()_.
+For details refer to linkzmq:zmq_setsockopt[3] and linkzmq:zmq_term[3].
+
+
+RETURN VALUE
+------------
+The _zmq_close()_ function shall return zero if successful. Otherwise it shall
+return `-1` and set 'errno' to one of the values defined below.
+
+
+ERRORS
+------
+*ENOTSOCK*::
+The provided 'socket' was invalid.
+
+
+SEE ALSO
+--------
+linkzmq:zmq_socket[3]
+linkzmq:zmq_term[3]
+linkzmq:zmq_setsockopt[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_connect.txt

@@ -0,0 +1,98 @@
+zmq_connect(3)
+==============
+
+
+NAME
+----
+zmq_connect - create outgoing connection from socket
+
+
+SYNOPSIS
+--------
+*int zmq_connect (void '*socket', const char '*endpoint');*
+
+
+DESCRIPTION
+-----------
+The _zmq_connect()_ function connects the 'socket' to an 'endpoint' and then
+accepts incoming connections on that endpoint.
+
+The '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.
+
+0MQ provides the the following transports:
+
+'tcp':: unicast transport using TCP, see linkzmq:zmq_tcp[7]
+'ipc':: local inter-process communication transport, see linkzmq:zmq_ipc[7]
+'inproc':: local in-process (inter-thread) communication transport, see linkzmq:zmq_inproc[7]
+'pgm', 'epgm':: reliable multicast transport using PGM, see linkzmq:zmq_pgm[7]
+
+Every 0MQ socket type except 'ZMQ_PAIR' supports one-to-many and many-to-one
+semantics. The precise semantics depend on the socket type and are defined in
+linkzmq:zmq_socket[3].
+
+NOTE: for most transports and socket types the connection is not performed
+immediately but as needed by 0MQ. Thus a successful call to _zmq_connect()_
+does not mean that the connection was or could actually be established.
+Because of this, for most transports and socket types the order in which
+a 'server' socket is bound and a 'client' socket is connected to it does not
+matter. The first exception is when using the inproc:// transport: you must
+call _zmq_bind()_ before calling _zmq_connect()_. The second exception are
+_ZMQ_PAIR_ sockets, which do not automatically reconnect to endpoints.
+
+NOTE: following a _zmq_connect()_, the socket enters its normal 'ready' state.
+By contrast, following a _zmq_bind()_ alone, the socket enters a 'mute' state
+in which the socket blocks or drops messages according to the socket type, as
+defined in linkzmq:zmq_socket[3].
+
+
+RETURN VALUE
+------------
+The _zmq_connect()_ function returns zero if successful. Otherwise it returns
+`-1` and sets 'errno' to one of the values defined below.
+
+
+ERRORS
+------
+*EINVAL*::
+The endpoint supplied is invalid.
+*EPROTONOSUPPORT*::
+The requested 'transport' protocol is not supported.
+*ENOCOMPATPROTO*::
+The requested 'transport' protocol is not compatible with the socket type.
+*ETERM*::
+The 0MQ 'context' associated with the specified 'socket' was terminated.
+*ENOTSOCK*::
+The provided 'socket' was invalid.
+*EMTHREAD*::
+No I/O thread is available to accomplish the task.
+
+
+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 an in-process transport with the address 'my_publisher' */
+int rc = zmq_connect (socket, "inproc://my_publisher");
+assert (rc == 0);
+/* Connect it to the host server001, port 5555 using a TCP transport */
+rc = zmq_connect (socket, "tcp://server001:5555");
+assert (rc == 0);
+----
+
+
+SEE ALSO
+--------
+linkzmq:zmq_bind[3]
+linkzmq:zmq_socket[3]
+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>.