diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Makefile.am | 22 | ||||
| -rw-r--r-- | doc/asciidoc.conf | 18 | ||||
| -rw-r--r-- | doc/xs.txt | 187 | ||||
| -rw-r--r-- | doc/xs_bind.txt (renamed from doc/zmq_bind.txt) | 46 | ||||
| -rw-r--r-- | doc/xs_close.txt | 52 | ||||
| -rw-r--r-- | doc/xs_connect.txt (renamed from doc/zmq_connect.txt) | 50 | ||||
| l--------- | doc/xs_epgm.txt (renamed from doc/zmq_epgm.txt) | 0 | ||||
| -rw-r--r-- | doc/xs_errno.txt | 50 | ||||
| -rw-r--r-- | doc/xs_getmsgopt.txt (renamed from doc/zmq_getmsgopt.txt) | 44 | ||||
| -rw-r--r-- | doc/xs_getsockopt.txt (renamed from doc/zmq_getsockopt.txt) | 198 | ||||
| -rw-r--r-- | doc/xs_init.txt (renamed from doc/zmq_init.txt) | 24 | ||||
| -rw-r--r-- | doc/xs_inproc.txt (renamed from doc/zmq_inproc.txt) | 48 | ||||
| -rw-r--r-- | doc/xs_ipc.txt (renamed from doc/zmq_ipc.txt) | 34 | ||||
| -rw-r--r-- | doc/xs_msg_close.txt | 55 | ||||
| -rw-r--r-- | doc/xs_msg_copy.txt | 57 | ||||
| -rw-r--r-- | doc/xs_msg_data.txt | 48 | ||||
| -rw-r--r-- | doc/xs_msg_init.txt | 65 | ||||
| -rw-r--r-- | doc/xs_msg_init_data.txt | 85 | ||||
| -rw-r--r-- | doc/xs_msg_init_size.txt | 58 | ||||
| -rw-r--r-- | doc/xs_msg_move.txt | 52 | ||||
| -rw-r--r-- | doc/xs_msg_size.txt | 48 | ||||
| -rw-r--r-- | doc/xs_pgm.txt (renamed from doc/zmq_pgm.txt) | 62 | ||||
| -rw-r--r-- | doc/xs_poll.txt | 129 | ||||
| -rw-r--r-- | doc/xs_recv.txt (renamed from doc/zmq_recv.txt) | 50 | ||||
| -rw-r--r-- | doc/xs_recvmsg.txt (renamed from doc/zmq_recvmsg.txt) | 70 | ||||
| -rw-r--r-- | doc/xs_send.txt (renamed from doc/zmq_send.txt) | 56 | ||||
| -rw-r--r-- | doc/xs_sendmsg.txt (renamed from doc/zmq_sendmsg.txt) | 68 | ||||
| -rw-r--r-- | doc/xs_setsockopt.txt (renamed from doc/zmq_setsockopt.txt) | 201 | ||||
| -rw-r--r-- | doc/xs_socket.txt (renamed from doc/zmq_socket.txt) | 248 | ||||
| -rw-r--r-- | doc/xs_strerror.txt | 55 | ||||
| -rw-r--r-- | doc/xs_tcp.txt (renamed from doc/zmq_tcp.txt) | 44 | ||||
| -rw-r--r-- | doc/xs_term.txt | 65 | ||||
| -rw-r--r-- | doc/xs_version.txt | 53 | ||||
| -rw-r--r-- | doc/zmq.txt | 217 | ||||
| -rw-r--r-- | doc/zmq_close.txt | 52 | ||||
| -rw-r--r-- | doc/zmq_errno.txt | 50 | ||||
| -rw-r--r-- | doc/zmq_msg_close.txt | 55 | ||||
| -rw-r--r-- | doc/zmq_msg_copy.txt | 57 | ||||
| -rw-r--r-- | doc/zmq_msg_data.txt | 48 | ||||
| -rw-r--r-- | doc/zmq_msg_init.txt | 65 | ||||
| -rw-r--r-- | doc/zmq_msg_init_data.txt | 85 | ||||
| -rw-r--r-- | doc/zmq_msg_init_size.txt | 58 | ||||
| -rw-r--r-- | doc/zmq_msg_move.txt | 52 | ||||
| -rw-r--r-- | doc/zmq_msg_size.txt | 48 | ||||
| -rw-r--r-- | doc/zmq_poll.txt | 129 | ||||
| -rw-r--r-- | doc/zmq_strerror.txt | 55 | ||||
| -rw-r--r-- | doc/zmq_term.txt | 65 | ||||
| -rw-r--r-- | doc/zmq_version.txt | 53 |
48 files changed, 1696 insertions, 1735 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am index 103652f..af8d8f4 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,10 +1,10 @@ -MAN3 = zmq_bind.3 zmq_close.3 zmq_connect.3 zmq_init.3 \ - zmq_msg_close.3 zmq_msg_copy.3 zmq_msg_data.3 zmq_msg_init.3 \ - zmq_msg_init_data.3 zmq_msg_init_size.3 zmq_msg_move.3 zmq_msg_size.3 \ - zmq_poll.3 zmq_recv.3 zmq_send.3 zmq_setsockopt.3 zmq_socket.3 \ - zmq_strerror.3 zmq_term.3 zmq_version.3 zmq_getsockopt.3 zmq_errno.3 \ - zmq_sendmsg.3 zmq_recvmsg.3 zmq_getmsgopt.3 -MAN7 = zmq.7 zmq_tcp.7 zmq_pgm.7 zmq_epgm.7 zmq_inproc.7 zmq_ipc.7 +MAN3 = xs_bind.3 xs_close.3 xs_connect.3 xs_init.3 \ + xs_msg_close.3 xs_msg_copy.3 xs_msg_data.3 xs_msg_init.3 \ + xs_msg_init_data.3 xs_msg_init_size.3 xs_msg_move.3 xs_msg_size.3 \ + xs_poll.3 xs_recv.3 xs_send.3 xs_setsockopt.3 xs_socket.3 \ + xs_strerror.3 xs_term.3 xs_version.3 xs_getsockopt.3 xs_errno.3 \ + xs_sendmsg.3 xs_recvmsg.3 xs_getmsgopt.3 +MAN7 = xs.7 xs_tcp.7 xs_pgm.7 xs_epgm.7 xs_inproc.7 xs_ipc.7 MAN_DOC = $(MAN1) $(MAN3) $(MAN7) @@ -30,16 +30,16 @@ SUFFIXES=.html .txt .xml .3 .7 .txt.html: asciidoc -d manpage -b xhtml11 -f $(srcdir)/asciidoc.conf \ - -azmq_version=@PACKAGE_VERSION@ -o$@ $< + -axs_version=@PACKAGE_VERSION@ -o$@ $< .txt.xml: asciidoc -d manpage -b docbook -f $(srcdir)/asciidoc.conf \ - -azmq_version=@PACKAGE_VERSION@ -o$@ $< + -axs_version=@PACKAGE_VERSION@ -o$@ $< .xml.1: xmlto man $< .xml.3: xmlto man $< .xml.7: xmlto man $< -zmq_epgm.7: zmq_pgm.7 - cp zmq_pgm.7 $@ +xs_epgm.7: xs_pgm.7 + cp xs_pgm.7 $@ endif diff --git a/doc/asciidoc.conf b/doc/asciidoc.conf index d73d711..94cde95 100644 --- a/doc/asciidoc.conf +++ b/doc/asciidoc.conf @@ -2,10 +2,10 @@ literal-style=template="literalparagraph" [macros] -(?su)[\\]?(?P<name>linkzmq):(?P<target>\S*?)\[(?P<attrlist>.*?)\]= +(?su)[\\]?(?P<name>linkxs):(?P<target>\S*?)\[(?P<attrlist>.*?)\]= ifdef::backend-docbook[] -[linkzmq-inlinemacro] +[linkxs-inlinemacro] {0%{target}} {0#<citerefentry>} {0#<refentrytitle>{target}</refentrytitle><manvolnum>{0}</manvolnum>} @@ -13,7 +13,7 @@ ifdef::backend-docbook[] endif::backend-docbook[] ifdef::backend-xhtml11[] -[linkzmq-inlinemacro] +[linkxs-inlinemacro] <a href="{target}.html">{target}{0?({0})}</a> endif::backend-xhtml11[] @@ -25,9 +25,9 @@ template::[header-declarations] <refmeta> <refentrytitle>{mantitle}</refentrytitle> <manvolnum>{manvolnum}</manvolnum> -<refmiscinfo class="source">0MQ</refmiscinfo> -<refmiscinfo class="version">{zmq_version}</refmiscinfo> -<refmiscinfo class="manual">0MQ Manual</refmiscinfo> +<refmiscinfo class="source">Crossroads</refmiscinfo> +<refmiscinfo class="version">{xs_version}</refmiscinfo> +<refmiscinfo class="manual">Crossroads Manual</refmiscinfo> </refmeta> <refnamediv> <refname>{manname}</refname> @@ -42,7 +42,7 @@ ifdef::backend-xhtml11[] {disable-javascript%<div id="footnotes"><hr /></div>} <div id="footer"> <div id="footer-text"> -ØMQ {zmq_version}<br /> +Crossroads {xs_version}<br /> Last updated {docdate} {doctime} </div> </div> @@ -50,7 +50,3 @@ Last updated {docdate} {doctime} </html> endif::backend-xhtml11[] -[replacements] -ifdef::backend-xhtml11[] -0MQ=ØMQ -endif::backend-xhtml11[] diff --git a/doc/xs.txt b/doc/xs.txt new file mode 100644 index 0000000..635c7d5 --- /dev/null +++ b/doc/xs.txt @@ -0,0 +1,187 @@ +xs(7) +===== + + +NAME +---- +xs - Crossroads, a lightweight messaging layer + + +SYNOPSIS +-------- +*#include <xs.h>* + +*cc* ['flags'] 'files' *-lxs* ['libraries'] + + +DESCRIPTION +----------- +Crossroads is a library which extends the standard +socket interfaces with features traditionally provided by specialised +_messaging middleware_ products. Crossroads 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 Crossroads concepts, describes how +Crossroads abstract standard sockets and provides a reference manual for the +functions provided by the Crossroads library. + + +Context +~~~~~~~ +Before using any Crossroads library functions the caller must initialise a +'context' using _xs_init()_. The following functions are provided to handle +initialisation and termination of a 'context': + +Initialise Crossroads context:: + linkxs:xs_init[3] + +Terminate Crossroads context:: + linkxs:xs_term[3] + + +Thread safety +^^^^^^^^^^^^^ +A '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 Crossroads '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 _xs_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 Crossroads directly and at the same time make use of any +number of additional libraries or components which themselves make use of +Crossroads as long as the above guidelines regarding thread safety are adhered +to. + + +Messages +~~~~~~~~ +A Crossroads message is a discrete unit of data passed between applications or +components of the same application. Crossroads messages have no internal +structure and from the point of view of Crossroads themselves they are +considered to be opaque binary data. + +The following functions are provided to work with messages: + +Initialise a message:: + linkxs:xs_msg_init[3] + linkxs:xs_msg_init_size[3] + linkxs:xs_msg_init_data[3] + +Release a message:: + linkxs:xs_msg_close[3] + +Access message content:: + linkxs:xs_msg_data[3] + linkxs:xs_msg_size[3] + +Message manipulation:: + linkxs:xs_msg_copy[3] + linkxs:xs_msg_move[3] + + +Sockets +~~~~~~~ +Crossroads sockets present an abstraction of a asynchronous _message queue_, +with the exact queueing semantics depending on the socket type in use. See +linkxs:xs_socket[3] for the socket types provided. + +The following functions are provided to work with sockets: + +Creating a socket:: + linkxs:xs_socket[3] + +Closing a socket:: + linkxs:xs_close[3] + +Manipulating socket options:: + linkxs:xs_getsockopt[3] + linkxs:xs_setsockopt[3] + +Establishing a message flow:: + linkxs:xs_bind[3] + linkxs:xs_connect[3] + +Sending and receiving messages:: + linkxs:xs_send[3] + linkxs:xs_recv[3] + +.Input/output multiplexing +Crossroads provide a mechanism for applications to multiplex input/output events +over a set containing both Crossroads sockets and standard sockets. This +mechanism mirrors the standard _poll()_ system call, and is described in detail +in linkxs:xs_poll[3]. + + +Transports +~~~~~~~~~~ +A Crossroads 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:: + linkxs:xs_tcp[7] + +Reliable multicast transport using PGM:: + linkxs:xs_pgm[7] + +Local inter-process communication transport:: + linkxs:xs_ipc[7] + +Local in-process (inter-thread) communication transport:: + linkxs:xs_inproc[7] + +ERROR HANDLING +-------------- +The Crossroads library functions handle errors using the standard conventions +found on POSIX systems. Generally, this means that upon failure a Crossroads +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 _xs_errno()_ function is provided +to assist in these cases; for details refer to linkxs:xs_errno[3]. + +The _xs_strerror()_ function is provided to translate Crossroads-specific error +codes into error message strings; for details refer to linkxs:xs_strerror[3]. + + +MISCELLANEOUS +------------- +The following miscellaneous functions are provided: + +Report Crossroads library version:: + linkxs:xs_version[3] + + +LANGUAGE BINDINGS +----------------- +The Crossroads 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 Crossroads from +other languages shall refer to this documentation alongside any documentation +provided by the vendor of their language binding. + +AUTHORS +------- +The Crossroads documentation was written by Martin Sustrik <sustrik@250bpm.com> +and Martin Lucina <martin@lucina.net>. + +COPYING +------- +Free use of Crossroads library 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 Crossroads distribution. diff --git a/doc/zmq_bind.txt b/doc/xs_bind.txt index 58517ec..8cd49bc 100644 --- a/doc/zmq_bind.txt +++ b/doc/xs_bind.txt @@ -1,20 +1,20 @@ -zmq_bind(3) -=========== +xs_bind(3) +========== NAME ---- -zmq_bind - accept connections on a socket +xs_bind - accept connections on a socket SYNOPSIS -------- -*int zmq_bind (void '*socket', const char '*endpoint');* +*int xs_bind (void '*socket', const char '*endpoint');* DESCRIPTION ----------- -The _zmq_bind()_ function shall create an endpoint for accepting connections +The _xs_bind()_ function shall create an endpoint for accepting connections and bind it to the socket referenced by the 'socket' argument. The 'endpoint' argument is a string consisting of two parts as follows: @@ -24,21 +24,21 @@ the underlying transport protocol selected. The following transports are defined: -'inproc':: local in-process (inter-thread) communication transport, see linkzmq:zmq_inproc[7] -'ipc':: local inter-process communication transport, see linkzmq:zmq_ipc[7] -'tcp':: unicast transport using TCP, see linkzmq:zmq_tcp[7] -'pgm', 'epgm':: reliable multicast transport using PGM, see linkzmq:zmq_pgm[7] +'inproc':: local in-process (inter-thread) communication transport, see linkxs:xs_inproc[7] +'ipc':: local inter-process communication transport, see linkxs:xs_ipc[7] +'tcp':: unicast transport using TCP, see linkxs:xs_tcp[7] +'pgm', 'epgm':: reliable multicast transport using PGM, see linkxs:xs_pgm[7] -With the exception of 'ZMQ_PAIR' sockets, a single socket may be connected to -multiple endpoints using _zmq_connect()_, while simultaneously accepting +With the exception of 'XS_PAIR' sockets, a single socket may be connected to +multiple endpoints using _xs_connect()_, while simultaneously accepting incoming connections from multiple endpoints bound to the socket using -_zmq_bind()_. Refer to linkzmq:zmq_socket[3] for a description of the exact +_xs_bind()_. Refer to linkxs:xs_socket[3] for a description of the exact semantics involved when connecting or binding a socket to multiple endpoints. RETURN VALUE ------------ -The _zmq_bind()_ function shall return zero if successful. Otherwise it shall +The _xs_bind()_ function shall return zero if successful. Otherwise it shall return `-1` and set 'errno' to one of the values defined below. @@ -57,7 +57,7 @@ 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. +The 'context' associated with the specified 'socket' was terminated. *ENOTSOCK*:: The provided 'socket' was invalid. *EMTHREAD*:: @@ -68,26 +68,26 @@ 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); +/* Create a XS_PUB socket */ +void *socket = xs_socket (context, XS_PUB); assert (socket); /* Bind it to a in-process transport with the address 'my_publisher' */ -int rc = zmq_bind (socket, "inproc://my_publisher"); +int rc = xs_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"); +rc = xs_bind (socket, "tcp://eth0:5555"); assert (rc == 0); ---- SEE ALSO -------- -linkzmq:zmq_connect[3] -linkzmq:zmq_socket[3] -linkzmq:zmq[7] +linkxs:xs_connect[3] +linkxs:xs_socket[3] +linkxs:xs[7] AUTHORS ------- -The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and -Martin Lucina <martin@lucina.net>. +The Crossroads documentation was written by Martin Sustrik <sustrik@250bpm.com> +and Martin Lucina <martin@lucina.net>. diff --git a/doc/xs_close.txt b/doc/xs_close.txt new file mode 100644 index 0000000..99b1ed8 --- /dev/null +++ b/doc/xs_close.txt @@ -0,0 +1,52 @@ +xs_close(3) +=========== + + +NAME +---- +xs_close - close Crossroads socket + + +SYNOPSIS +-------- +*int xs_close (void '*socket');* + + +DESCRIPTION +----------- +The _xs_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 _xs_recv()_ shall be discarded. The +behaviour for discarding messages sent by the application with _xs_send()_ but +not yet physically transferred to the network depends on the value of the +_XS_LINGER_ socket option for the specified 'socket'. + +NOTE: The default setting of _XS_LINGER_ does not discard unsent messages; +this behaviour may cause the application to block when calling _xs_term()_. +For details refer to linkxs:xs_setsockopt[3] and linkxs:xs_term[3]. + + +RETURN VALUE +------------ +The _xs_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 +-------- +linkxs:xs_socket[3] +linkxs:xs_term[3] +linkxs:xs_setsockopt[3] +linkxs:xs[7] + + +AUTHORS +------- +The Crossroads documentation was written by Martin Sustrik <sustrik@250bpm.com> +and Martin Lucina <martin@lucina.net>. diff --git a/doc/zmq_connect.txt b/doc/xs_connect.txt index d0045c4..a0a6ae7 100644 --- a/doc/zmq_connect.txt +++ b/doc/xs_connect.txt @@ -1,20 +1,20 @@ -zmq_connect(3) -============== +xs_connect(3) +============= NAME ---- -zmq_connect - connect a socket +xs_connect - connect a socket SYNOPSIS -------- -*int zmq_connect (void '*socket', const char '*endpoint');* +*int xs_connect (void '*socket', const char '*endpoint');* DESCRIPTION ----------- -The _zmq_connect()_ function shall connect the socket referenced by the +The _xs_connect()_ function shall connect the socket referenced by the 'socket' argument to the endpoint specified by the 'endpoint' argument. The 'endpoint' argument is a string consisting of two parts as follows: @@ -24,25 +24,25 @@ the underlying transport protocol selected. The following transports are defined: -'inproc':: local in-process (inter-thread) communication transport, see linkzmq:zmq_inproc[7] -'ipc':: local inter-process communication transport, see linkzmq:zmq_ipc[7] -'tcp':: unicast transport using TCP, see linkzmq:zmq_tcp[7] -'pgm', 'epgm':: reliable multicast transport using PGM, see linkzmq:zmq_pgm[7] +'inproc':: local in-process (inter-thread) communication transport, see linkxs:xs_inproc[7] +'ipc':: local inter-process communication transport, see linkxs:xs_ipc[7] +'tcp':: unicast transport using TCP, see linkxs:xs_tcp[7] +'pgm', 'epgm':: reliable multicast transport using PGM, see linkxs:xs_pgm[7] -With the exception of 'ZMQ_PAIR' sockets, a single socket may be connected to -multiple endpoints using _zmq_connect()_, while simultaneously accepting +With the exception of 'XS_PAIR' sockets, a single socket may be connected to +multiple endpoints using _xs_connect()_, while simultaneously accepting incoming connections from multiple endpoints bound to the socket using -_zmq_bind()_. Refer to linkzmq:zmq_socket[3] for a description of the exact +_xs_bind()_. Refer to linkxs:xs_socket[3] for a description of the exact semantics involved when connecting or binding a socket to multiple endpoints. -NOTE: The connection will not be performed immediately but as needed by 0MQ. -Thus a successful invocation of _zmq_connect()_ does not indicate that a +NOTE: The connection will not be performed immediately but as needed by the +library. Thus a successful invocation of _xs_connect()_ does not indicate that a physical connection was or can actually be established. RETURN VALUE ------------ -The _zmq_connect()_ function shall return zero if successful. Otherwise it +The _xs_connect()_ function shall return zero if successful. Otherwise it shall return `-1` and set 'errno' to one of the values defined below. @@ -55,7 +55,7 @@ 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. +The 'context' associated with the specified 'socket' was terminated. *ENOTSOCK*:: The provided 'socket' was invalid. *EMTHREAD*:: @@ -66,26 +66,26 @@ 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); +/* Create a XS_SUB socket */ +void *socket = xs_socket (context, XS_SUB); assert (socket); /* Connect it to an in-process transport with the address 'my_publisher' */ -int rc = zmq_connect (socket, "inproc://my_publisher"); +int rc = xs_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"); +rc = xs_connect (socket, "tcp://server001:5555"); assert (rc == 0); ---- SEE ALSO -------- -linkzmq:zmq_bind[3] -linkzmq:zmq_socket[3] -linkzmq:zmq[7] +linkxs:xs_bind[3] +linkxs:xs_socket[3] +linkxs:xs[7] AUTHORS ------- -The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and -Martin Lucina <martin@lucina.net>. +The Crossroads documentation was written by Martin Sustrik <sustrik@250bpm.com> +and Martin Lucina <martin@lucina.net>. diff --git a/doc/zmq_epgm.txt b/doc/xs_epgm.txt index 4d58b1b..4d58b1b 120000 --- a/doc/zmq_epgm.txt +++ b/doc/xs_epgm.txt diff --git a/doc/xs_errno.txt b/doc/xs_errno.txt new file mode 100644 index 0000000..b0cac77 --- /dev/null +++ b/doc/xs_errno.txt @@ -0,0 +1,50 @@ +xs_errno(3) +=========== + + +NAME +---- +xs_errno - retrieve value of errno for the calling thread + + +SYNOPSIS +-------- +*int xs_errno (void);* + + +DESCRIPTION +----------- +The _xs_errno()_ function shall retrieve the value of the 'errno' variable for +the calling thread. + +The _xs_errno()_ function is provided to assist users on non-POSIX systems who +are experiencing issues with retrieving the correct value of 'errno' directly. +Specifically, users on Win32 systems whose application is using a different C +run-time library from the C run-time library in use by Crossroads will need to +use _xs_errno()_ for correct operation. + +IMPORTANT: Users not experiencing issues with retrieving the correct value of +'errno' should not use this function and should instead access the 'errno' +variable directly. + + +RETURN VALUE +------------ +The _xs_errno()_ function shall return the value of the 'errno' variable for +the calling thread. + + +ERRORS +------ +No errors are defined. + + +SEE ALSO +-------- +linkxs:xs[7] + + +AUTHORS +------- +The Crossroads documentation was written by Martin Sustrik <sustrik@250bpm.com> +and Martin Lucina <martin@lucina.net>. diff --git a/doc/zmq_getmsgopt.txt b/doc/xs_getmsgopt.txt index a82c30c..4b06322 100644 --- a/doc/zmq_getmsgopt.txt +++ b/doc/xs_getmsgopt.txt @@ -1,35 +1,35 @@ -zmq_getmsgopt(3) -================ +xs_getmsgopt(3) +=============== NAME ---- -zmq_getmsgopt - retrieve message option +xs_getmsgopt - retrieve message option SYNOPSIS -------- -*int zmq_getmsgopt (zmq_msg_t '*message', int 'option_name', void '*option_value', size_t '*option_len');* +*int xs_getmsgopt (xs_msg_t '*message', int 'option_name', void '*option_value', size_t '*option_len');* DESCRIPTION ----------- -The _zmq_getmsgopt()_ function shall retrieve the value for the option +The _xs_getmsgopt()_ function shall retrieve the value for the option specified by the 'option_name' argument for the message pointed to by the 'message' argument, and store it in the buffer pointed to by the 'option_value' argument. The 'option_len' argument is the size in bytes of the buffer pointed -to by 'option_value'; upon successful completion _zmq_getsockopt()_ shall +to by 'option_value'; upon successful completion _xs_getsockopt()_ shall modify the 'option_len' argument to indicate the actual size of the option value stored in the buffer. -The following options can be retrieved with the _zmq_getmsgopt()_ function: +The following options can be retrieved with the _xs_getmsgopt()_ function: -*ZMQ_MORE*:: +*XS_MORE*:: Indicates that there are more message parts to follow after the 'message'. RETURN VALUE ------------ -The _zmq_getmsgopt()_ function shall return zero if successful. Otherwise it +The _xs_getmsgopt()_ function shall return zero if successful. Otherwise it shall return `-1` and set 'errno' to one of the values defined below. @@ -46,17 +46,17 @@ EXAMPLE ------- .Receiving a multi-part message ---- -zmq_msg_t part; +xs_msg_t part; int more; size_t more_size = sizeof (more); while (true) { - /* Create an empty 0MQ message to hold the message part */ - int rc = zmq_msg_init (&part); + /* Create an empty message to hold the message part */ + int rc = xs_msg_init (&part); assert (rc == 0); /* Block until a message is available to be received from socket */ - rc = zmq_recvmsg (socket, &part, 0); + rc = xs_recvmsg (socket, &part, 0); assert (rc != -1); - rc = getmsgopt (&part, ZMQ_MORE, &more, &more_size); + rc = getmsgopt (&part, XS_MORE, &more, &more_size); assert (rc == 0); if (more) { fprintf (stderr, "more\n"); @@ -65,21 +65,21 @@ while (true) { fprintf (stderr, "end\n"); break; } - zmq_msg_close (part); + xs_msg_close (part); } ---- 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] +linkxs:xs_msg_data[3] +linkxs:xs_msg_init[3] +linkxs:xs_msg_init_size[3] +linkxs:xs_msg_init_data[3] +linkxs:xs_msg_close[3] +linkxs:xs[7] AUTHORS ------- -The 0MQ documentation was written by Chuck Remes <cremes@mac.com>. +This manual page was written by Chuck Remes <cremes@mac.com>. diff --git a/doc/zmq_getsockopt.txt b/doc/xs_getsockopt.txt index 50b80fd..e7ddb8e 100644 --- a/doc/zmq_getsockopt.txt +++ b/doc/xs_getsockopt.txt @@ -1,34 +1,34 @@ -zmq_getsockopt(3) -================= +xs_getsockopt(3) +================ NAME ---- -zmq_getsockopt - get 0MQ socket options +xs_getsockopt - get Crossroads socket option SYNOPSIS -------- -*int zmq_getsockopt (void '*socket', int 'option_name', void '*option_value', size_t '*option_len');* +*int xs_getsockopt (void '*socket', int 'option_name', void '*option_value', size_t '*option_len');* DESCRIPTION ----------- -The _zmq_getsockopt()_ function shall retrieve the value for the option -specified by the 'option_name' argument for the 0MQ socket pointed to by the -'socket' argument, and store it in the buffer pointed to by the 'option_value' -argument. The 'option_len' argument is the size in bytes of the buffer pointed -to by 'option_value'; upon successful completion _zmq_getsockopt()_ shall -modify the 'option_len' argument to indicate the actual size of the option -value stored in the buffer. +The _xs_getsockopt()_ function shall retrieve the value for the option +specified by the 'option_name' argument for the Crossroads socket pointed to by +the 'socket' argument, and store it in the buffer pointed to by the +'option_value' argument. The 'option_len' argument is the size in bytes of the +buffer pointed to by 'option_value'; upon successful completion +_xs_getsockopt()_ shall modify the 'option_len' argument to indicate the actual +size of the option value stored in the buffer. -The following options can be retrieved with the _zmq_getsockopt()_ function: +The following options can be retrieved with the _xs_getsockopt()_ function: -ZMQ_TYPE: Retrieve socket type +XS_TYPE: Retrieve socket type ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_TYPE' option shall retrieve the socket type for the specified +The 'XS_TYPE' option shall retrieve the socket type for the specified 'socket'. The socket type is specified at socket creation time and cannot be modified afterwards. @@ -39,13 +39,13 @@ Default value:: N/A Applicable socket types:: all -ZMQ_RCVMORE: More message data parts to follow +XS_RCVMORE: More message data parts to follow ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_RCVMORE' option shall return True (1) if the message part last +The 'XS_RCVMORE' option shall return True (1) if the message part last received from the 'socket' was a data part with more parts to follow. If there are no data parts to follow, this option shall return False (0). -Refer to linkzmq:zmq_send[3] and linkzmq:zmq_recv[3] for a detailed description +Refer to linkxs:xs_send[3] and linkxs:xs_recv[3] for a detailed description of multi-part messages. [horizontal] @@ -55,17 +55,17 @@ Default value:: N/A Applicable socket types:: all -ZMQ_SNDHWM: Retrieves high water mark for outbound messages +XS_SNDHWM: Retrieves high water mark for outbound messages ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_SNDHWM' option shall return the high water mark for outbound messages +The 'XS_SNDHWM' option shall return the high water mark for outbound messages on the specified 'socket'. The high water mark is a hard limit on the maximum -number of outstanding messages 0MQ shall queue in memory for any single peer -that the specified 'socket' is communicating with. +number of outstanding messages the library shall queue in memory for any single +peer that the specified 'socket' is communicating with. If this limit has been reached the socket shall enter an exceptional state and -depending on the socket type, 0MQ shall take appropriate action such as +depending on the socket type, the library shall take appropriate action such as blocking or dropping sent messages. Refer to the individual socket descriptions -in linkzmq:zmq_socket[3] for details on the exact action taken for each socket +in linkxs:xs_socket[3] for details on the exact action taken for each socket type. [horizontal] @@ -75,17 +75,17 @@ Default value:: 1000 Applicable socket types:: all -ZMQ_RCVHWM: Retrieve high water mark for inbound messages +XS_RCVHWM: Retrieve high water mark for inbound messages ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_RCVHWM' option shall return the high water mark for inbound messages on +The 'XS_RCVHWM' option shall return the high water mark for inbound messages on the specified 'socket'. The high water mark is a hard limit on the maximum -number of outstanding messages 0MQ shall queue in memory for any single peer -that the specified 'socket' is communicating with. +number of outstanding messages the library shall queue in memory for any single +peer that the specified 'socket' is communicating with. If this limit has been reached the socket shall enter an exceptional state and -depending on the socket type, 0MQ shall take appropriate action such as +depending on the socket type, the library shall take appropriate action such as blocking or dropping sent messages. Refer to the individual socket descriptions -in linkzmq:zmq_socket[3] for details on the exact action taken for each socket +in linkxs:xs_socket[3] for details on the exact action taken for each socket type. [horizontal] @@ -95,20 +95,20 @@ Default value:: 1000 Applicable socket types:: all -ZMQ_AFFINITY: Retrieve I/O thread affinity +XS_AFFINITY: Retrieve I/O thread affinity ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_AFFINITY' option shall retrieve the I/O thread affinity for newly +The 'XS_AFFINITY' option shall retrieve the I/O thread affinity for newly created connections on the specified 'socket'. -Affinity determines which threads from the 0MQ I/O thread pool associated with -the socket's _context_ shall handle newly created connections. A value of zero -specifies no affinity, meaning that work shall be distributed fairly among all -0MQ I/O threads in the thread pool. For non-zero values, the lowest bit +Affinity determines which threads from the Crossroads I/O thread pool associated +with the socket's _context_ shall handle newly created connections. A value of +zero specifies no affinity, meaning that work shall be distributed fairly among +all I/O threads in the thread pool. For non-zero values, the lowest bit corresponds to thread 1, second lowest bit to thread 2 and so on. For example, a value of 3 specifies that subsequent connections on 'socket' shall be handled exclusively by I/O threads 1 and 2. -See also linkzmq:zmq_init[3] for details on allocating the number of I/O +See also linkxs:xs_init[3] for details on allocating the number of I/O threads for a specific _context_. [horizontal] @@ -117,15 +117,15 @@ Option value unit:: N/A (bitmap) Default value:: 0 Applicable socket types:: N/A -ZMQ_IDENTITY: Set socket identity +XS_IDENTITY: Set socket identity ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_IDENTITY' option shall retrieve the identity of the specified 'socket'. +The 'XS_IDENTITY' option shall retrieve the identity of the specified 'socket'. Socket identity is used only by request/reply pattern. Namely, it can be used in tandem with ROUTER socket to route messages to the peer with specific identity. Identity should be at least one byte and at most 255 bytes long. Identities -starting with binary zero are reserved for use by 0MQ infrastructure. +starting with binary zero are reserved for use by Crossroads infrastructure. [horizontal] Option value type:: binary data @@ -134,9 +134,9 @@ Default value:: NULL Applicable socket types:: all -ZMQ_RATE: Retrieve multicast data rate +XS_RATE: Retrieve multicast data rate ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_RATE' option shall retrieve the maximum send or receive data rate for +The 'XS_RATE' option shall retrieve the maximum send or receive data rate for multicast transports using the specified 'socket'. [horizontal] @@ -146,9 +146,9 @@ Default value:: 100 Applicable socket types:: all, when using multicast transports -ZMQ_RECOVERY_IVL: Get multicast recovery interval +XS_RECOVERY_IVL: Get multicast recovery interval ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_RECOVERY_IVL' option shall retrieve the recovery interval for +The 'XS_RECOVERY_IVL' option shall retrieve the recovery interval for multicast transports using the specified 'socket'. The recovery interval determines the maximum time in milliseconds that a receiver can be absent from a multicast group before unrecoverable data loss will occur. @@ -160,9 +160,9 @@ Default value:: 10000 Applicable socket types:: all, when using multicast transports -ZMQ_SNDBUF: Retrieve kernel transmit buffer size +XS_SNDBUF: Retrieve kernel transmit buffer size ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_SNDBUF' option shall retrieve the underlying kernel transmit buffer +The 'XS_SNDBUF' option shall retrieve the underlying kernel transmit buffer size for the specified 'socket'. A value of zero means that the OS default is in effect. For details refer to your operating system documentation for the 'SO_SNDBUF' socket option. @@ -174,9 +174,9 @@ Default value:: 0 Applicable socket types:: all -ZMQ_RCVBUF: Retrieve kernel receive buffer size +XS_RCVBUF: Retrieve kernel receive buffer size ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_RCVBUF' option shall retrieve the underlying kernel receive buffer +The 'XS_RCVBUF' option shall retrieve the underlying kernel receive buffer size for the specified 'socket'. A value of zero means that the OS default is in effect. For details refer to your operating system documentation for the 'SO_RCVBUF' socket option. @@ -188,26 +188,26 @@ Default value:: 0 Applicable socket types:: all -ZMQ_LINGER: Retrieve linger period for socket shutdown +XS_LINGER: Retrieve linger period for socket shutdown ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_LINGER' option shall retrieve the linger period for the specified +The 'XS_LINGER' option shall retrieve the linger period for the specified 'socket'. The linger period determines how long pending messages which have yet to be sent to a peer shall linger in memory after a socket is closed with -linkzmq:zmq_close[3], and further affects the termination of the socket's -context with linkzmq:zmq_term[3]. The following outlines the different +linkxs:xs_close[3], and further affects the termination of the socket's +context with linkxs:xs_term[3]. The following outlines the different behaviours: * The default value of '-1' specifies an infinite linger period. Pending - messages shall not be discarded after a call to _zmq_close()_; attempting to - terminate the socket's context with _zmq_term()_ shall block until all + messages shall not be discarded after a call to _xs_close()_; attempting to + terminate the socket's context with _xs_term()_ shall block until all pending messages have been sent to a peer. * The value of '0' specifies no linger period. Pending messages shall be - discarded immediately when the socket is closed with _zmq_close()_. + discarded immediately when the socket is closed with _xs_close()_. * Positive values specify an upper bound for the linger period in milliseconds. - Pending messages shall not be discarded after a call to _zmq_close()_; - attempting to terminate the socket's context with _zmq_term()_ shall block + Pending messages shall not be discarded after a call to _xs_close()_; + attempting to terminate the socket's context with _xs_term()_ shall block until either all pending messages have been sent to a peer, or the linger period expires, after which any pending messages shall be discarded. @@ -218,14 +218,14 @@ Default value:: -1 (infinite) Applicable socket types:: all -ZMQ_RECONNECT_IVL: Retrieve reconnection interval +XS_RECONNECT_IVL: Retrieve reconnection interval ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_RECONNECT_IVL' option shall retrieve the initial reconnection interval -for the specified 'socket'. The reconnection interval is the period 0MQ shall -wait between attempts to reconnect disconnected peers when using +The 'XS_RECONNECT_IVL' option shall retrieve the initial reconnection interval +for the specified 'socket'. The reconnection interval is the period the library +shall wait between attempts to reconnect disconnected peers when using connection-oriented transports. -NOTE: The reconnection interval may be randomized by 0MQ to prevent +NOTE: The reconnection interval may be randomized by the library to prevent reconnection storms in topologies with a large number of peers per socket. [horizontal] @@ -235,28 +235,28 @@ Default value:: 100 Applicable socket types:: all, only for connection-oriented transports -ZMQ_RECONNECT_IVL_MAX: Retrieve maximum reconnection interval +XS_RECONNECT_IVL_MAX: Retrieve maximum reconnection interval ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_RECONNECT_IVL_MAX' option shall retrieve the maximum reconnection -interval for the specified 'socket'. This is the maximum period 0MQ shall wait -between attempts to reconnect. On each reconnect attempt, the previous interval -shall be doubled untill ZMQ_RECONNECT_IVL_MAX is reached. This allows for -exponential backoff strategy. Default value means no exponential backoff is -performed and reconnect interval calculations are only based on -ZMQ_RECONNECT_IVL. +The 'XS_RECONNECT_IVL_MAX' option shall retrieve the maximum reconnection +interval for the specified 'socket'. This is the maximum period the library +shall wait between attempts to reconnect. On each reconnect attempt, the +previous interval shall be doubled untill XS_RECONNECT_IVL_MAX is reached. This +allows for exponential backoff strategy. Default value means no exponential +backoff is performed and reconnect interval calculations are only based on +XS_RECONNECT_IVL. -NOTE: Values less than ZMQ_RECONNECT_IVL will be ignored. +NOTE: Values less than XS_RECONNECT_IVL will be ignored. [horizontal] Option value type:: int Option value unit:: milliseconds -Default value:: 0 (only use ZMQ_RECONNECT_IVL) +Default value:: 0 (only use XS_RECONNECT_IVL) Applicable socket types:: all, only for connection-oriented transport -ZMQ_BACKLOG: Retrieve maximum length of the queue of outstanding connections +XS_BACKLOG: Retrieve maximum length of the queue of outstanding connections ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_BACKLOG' option shall retrieve the maximum length of the queue of +The 'XS_BACKLOG' option shall retrieve the maximum length of the queue of outstanding peer connections for the specified 'socket'; this only applies to connection-oriented transports. For details refer to your operating system documentation for the 'listen' function. @@ -268,11 +268,11 @@ Default value:: 100 Applicable socket types:: all, only for connection-oriented transports -ZMQ_MAXMSGSIZE: Maximum acceptable inbound message size +XS_MAXMSGSIZE: Maximum acceptable inbound message size ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The option shall retrieve limit for the inbound messages. If a peer sends -a message larger than ZMQ_MAXMSGSIZE it is disconnected. Value of -1 means +a message larger than XS_MAXMSGSIZE it is disconnected. Value of -1 means 'no limit'. [horizontal] @@ -282,7 +282,7 @@ Default value:: -1 Applicable socket types:: all -ZMQ_MULTICAST_HOPS: Maximum network hops for multicast packets +XS_MULTICAST_HOPS: Maximum network hops for multicast packets ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The option shall retrieve time-to-live used for outbound multicast packets. @@ -295,11 +295,11 @@ Default value:: 1 Applicable socket types:: all, when using multicast transports -ZMQ_RCVTIMEO: Maximum time before a socket operation returns with EAGAIN +XS_RCVTIMEO: Maximum time before a socket operation returns with EAGAIN ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Retrieve the timeout for recv operation on the socket. If the value is `0`, -_zmq_recv(3)_ will return immediately, with a EAGAIN error if there is no +_xs_recv(3)_ will return immediately, with a EAGAIN error if there is no message to receive. If the value is `-1`, it will block until a message is available. For all other values, it will wait for a message for that amount of time before returning with an EAGAIN error. @@ -311,11 +311,11 @@ Default value:: -1 (infinite) Applicable socket types:: all -ZMQ_SNDTIMEO: Maximum time before a socket operation returns with EAGAIN +XS_SNDTIMEO: Maximum time before a socket operation returns with EAGAIN ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Retrieve the timeout for send operation on the socket. If the value is `0`, -_zmq_send(3)_ will return immediately, with a EAGAIN error if the message +_xs_send(3)_ will return immediately, with a EAGAIN error if the message cannot be sent. If the value is `-1`, it will block until the message is sent. For all other values, it will try to send the message for that amount of time before returning with an EAGAIN error. @@ -327,7 +327,7 @@ Default value:: -1 (infinite) Applicable socket types:: all -ZMQ_IPV4ONLY: Retrieve IPv4-only socket override status +XS_IPV4ONLY: Retrieve IPv4-only socket override status ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Retrieve the underlying native socket type. A value of `1` will use IPv4 @@ -342,18 +342,18 @@ Default value:: 1 (true) Applicable socket types:: all, when using TCP transports. -ZMQ_FD: Retrieve file descriptor associated with the socket +XS_FD: Retrieve file descriptor associated with the socket ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_FD' option shall retrieve the file descriptor associated with the +The 'XS_FD' option shall retrieve the file descriptor associated with the specified 'socket'. The returned file descriptor can be used to integrate the -socket into an existing event loop; the 0MQ library shall signal any pending +socket into an existing event loop; the library shall signal any pending events on the socket in an _edge-triggered_ fashion by making the file descriptor become ready for reading. NOTE: The ability to read from the returned file descriptor does not necessarily indicate that messages are available to be read from, or can be written to, the underlying socket; applications must retrieve the actual event -state with a subsequent retrieval of the 'ZMQ_EVENTS' option. +state with a subsequent retrieval of the 'XS_EVENTS' option. CAUTION: The returned file descriptor is intended for use with a 'poll' or similar system call only. Applications must never attempt to read or write data @@ -366,23 +366,23 @@ Default value:: N/A Applicable socket types:: all -ZMQ_EVENTS: Retrieve socket event state +XS_EVENTS: Retrieve socket event state ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_EVENTS' option shall retrieve the event state for the specified +The 'XS_EVENTS' option shall retrieve the event state for the specified 'socket'. The returned value is a bit mask constructed by OR'ing a combination of the following event flags: -*ZMQ_POLLIN*:: +*XS_POLLIN*:: Indicates that at least one message may be received from the specified socket without blocking. -*ZMQ_POLLOUT*:: +*XS_POLLOUT*:: Indicates that at least one message may be sent to the specified socket without blocking. -The combination of a file descriptor returned by the 'ZMQ_FD' option being +The combination of a file descriptor returned by the 'XS_FD' option being ready for reading but no actual events returned by a subsequent retrieval of -the 'ZMQ_EVENTS' option is valid; applications should simply ignore this case +the 'XS_EVENTS' option is valid; applications should simply ignore this case and restart their polling operation/event loop. [horizontal] @@ -394,7 +394,7 @@ Applicable socket types:: all RETURN VALUE ------------ -The _zmq_getsockopt()_ function shall return zero if successful. Otherwise it +The _xs_getsockopt()_ function shall return zero if successful. Otherwise it shall return `-1` and set 'errno' to one of the values defined below. @@ -406,7 +406,7 @@ _option_value_ is invalid, or the size of the buffer pointed to by _option_value_, as specified by _option_len_, is insufficient for storing the option value. *ETERM*:: -The 0MQ 'context' associated with the specified 'socket' was terminated. +The 'context' associated with the specified 'socket' was terminated. *ENOTSOCK*:: The provided 'socket' was invalid. *EINTR*:: @@ -420,19 +420,19 @@ EXAMPLE /* Retrieve high water mark into sndhwm */ int sndhwm; size_t sndhwm_size = sizeof (sndhwm); -rc = zmq_getsockopt (socket, ZMQ_SNDHWM, &sndhwm, &sndhwm_size); +rc = xs_getsockopt (socket, XS_SNDHWM, &sndhwm, &sndhwm_size); assert (rc == 0); ---- SEE ALSO -------- -linkzmq:zmq_setsockopt[3] -linkzmq:zmq_socket[3] -linkzmq:zmq[7] +linkxs:xs_setsockopt[3] +linkxs:xs_socket[3] +linkxs:xs[7] AUTHORS ------- -The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and -Martin Lucina <martin@lucina.net>. +The Crossroads documentation was written by Martin Sustrik <sustrik@250bpm.com> +and Martin Lucina <martin@lucina.net>. diff --git a/doc/zmq_init.txt b/doc/xs_init.txt index 74f4b3e..e642824 100644 --- a/doc/zmq_init.txt +++ b/doc/xs_init.txt @@ -1,34 +1,34 @@ -zmq_init(3) -=========== +xs_init(3) +========== NAME ---- -zmq_init - initialise 0MQ context +xs_init - initialise Crossroads context SYNOPSIS -------- -*void *zmq_init (int 'io_threads');* +*void *xs_init (int 'io_threads');* DESCRIPTION ----------- -The _zmq_init()_ function initialises a 0MQ 'context'. +The _xs_init()_ function initialises a Crossroads 'context'. -The 'io_threads' argument specifies the size of the 0MQ thread pool to handle +The 'io_threads' argument specifies the size of the 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. .Thread safety -A 0MQ 'context' is thread safe and may be shared among as many application +A '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_init()_ function shall return an opaque handle to the initialised +The _xs_init()_ function shall return an opaque handle to the initialised 'context' if successful. Otherwise it shall return NULL and set 'errno' to one of the values defined below. @@ -41,11 +41,11 @@ An invalid number of 'io_threads' was requested. SEE ALSO -------- -linkzmq:zmq[7] -linkzmq:zmq_term[3] +linkxs:xs[7] +linkxs:xs_term[3] AUTHORS ------- -The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and -Martin Lucina <martin@lucina.net>. +The Crossroads documentation was written by Martin Sustrik <sustrik@250bpm.com> +and Martin Lucina <martin@lucina.net>. diff --git a/doc/zmq_inproc.txt b/doc/xs_inproc.txt index a2ae6e3..9ec255f 100644 --- a/doc/zmq_inproc.txt +++ b/doc/xs_inproc.txt @@ -1,26 +1,20 @@ -zmq_inproc(7) -============= +xs_inproc(7) +============ NAME ---- -zmq_inproc - 0MQ local in-process (inter-thread) communication transport +xs_inproc - local in-process (inter-thread) transport SYNOPSIS -------- The in-process transport passes messages via memory directly between threads -sharing a single 0MQ 'context'. - -NOTE: No I/O threads are involved in passing messages using the 'inproc' -transport. Therefore, if you are using a 0MQ 'context' for in-process messaging -only you can initialise the 'context' with zero I/O threads. See -linkzmq:zmq_init[3] for details. - +sharing a single 'context'. ADDRESSING ---------- -A 0MQ address string consists of two parts as follows: +A Crossroads address string consists of two parts as follows: 'transport'`://`'endpoint'. The 'transport' part specifies the underlying transport protocol to use, and for the in-process transport shall be set to `inproc`. The meaning of the 'endpoint' part for the in-process transport is @@ -29,19 +23,19 @@ defined below. Assigning a local address to a socket ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -When assigning a local address to a 'socket' using _zmq_bind()_ with the +When assigning a local address to a 'socket' using _xs_bind()_ with the 'inproc' transport, the 'endpoint' shall be interpreted as an arbitrary string -identifying the 'name' to create. The 'name' must be unique within the 0MQ +identifying the 'name' to create. The 'name' must be unique within the 'context' associated with the 'socket' and may be up to 256 characters in length. No other restrictions are placed on the format of the 'name'. Connecting a socket ~~~~~~~~~~~~~~~~~~~ -When connecting a 'socket' to a peer address using _zmq_connect()_ with the +When connecting a 'socket' to a peer address using _xs_connect()_ with the 'inproc' transport, the 'endpoint' shall be interpreted as an arbitrary string identifying the 'name' to connect to. The 'name' must have been previously -created by assigning it to at least one 'socket' within the same 0MQ 'context' +created by assigning it to at least one 'socket' within the same 'context' as the 'socket' being connected. @@ -55,35 +49,35 @@ EXAMPLES .Assigning a local address to a socket ---- /* Assign the in-process name "#1" */ -rc = zmq_bind(socket, "inproc://#1"); +rc = xs_bind(socket, "inproc://#1"); assert (rc == 0); /* Assign the in-process name "my-endpoint" */ -rc = zmq_bind(socket, "inproc://my-endpoint"); +rc = xs_bind(socket, "inproc://my-endpoint"); assert (rc == 0); ---- .Connecting a socket ---- /* Connect to the in-process name "#1" */ -rc = zmq_connect(socket, "inproc://#1"); +rc = xs_connect(socket, "inproc://#1"); assert (rc == 0); /* Connect to the in-process name "my-endpoint" */ -rc = zmq_connect(socket, "inproc://my-endpoint"); +rc = xs_connect(socket, "inproc://my-endpoint"); assert (rc == 0); ---- SEE ALSO -------- -linkzmq:zmq_bind[3] -linkzmq:zmq_connect[3] -linkzmq:zmq_ipc[7] -linkzmq:zmq_tcp[7] -linkzmq:zmq_pgm[7] -linkzmq:zmq[7] +linkxs:xs_bind[3] +linkxs:xs_connect[3] +linkxs:xs_ipc[7] +linkxs:xs_tcp[7] +linkxs:xs_pgm[7] +linkxs:xs[7] AUTHORS ------- -The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and -Martin Lucina <martin@lucina.net>. +The Crossroads documentation was written by Martin Sustrik <sustrik@250bpm.com> +and Martin Lucina <martin@lucina.net>. diff --git a/doc/zmq_ipc.txt b/doc/xs_ipc.txt index 80109ee..f3c5147 100644 --- a/doc/zmq_ipc.txt +++ b/doc/xs_ipc.txt @@ -1,10 +1,10 @@ -zmq_ipc(7) -========== +xs_ipc(7) +========= NAME ---- -zmq_ipc - 0MQ local inter-process communication transport +xs_ipc - local inter-process transport SYNOPSIS @@ -18,7 +18,7 @@ systems that provide UNIX domain sockets. ADDRESSING ---------- -A 0MQ address string consists of two parts as follows: +A Crossroads address string consists of two parts as follows: 'transport'`://`'endpoint'. The 'transport' part specifies the underlying transport protocol to use, and for the inter-process transport shall be set to `ipc`. The meaning of the 'endpoint' part for the inter-process transport is @@ -27,7 +27,7 @@ defined below. Assigning a local address to a socket ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -When assigning a local address to a 'socket' using _zmq_bind()_ with the 'ipc' +When assigning a local address to a 'socket' using _xs_bind()_ with the 'ipc' transport, the 'endpoint' shall be interpreted as an arbitrary string identifying the 'pathname' to create. The 'pathname' must be unique within the operating system namespace used by the 'ipc' implementation, and must fulfill @@ -36,11 +36,11 @@ any restrictions placed by the operating system on the format and length of a Connecting a socket ~~~~~~~~~~~~~~~~~~~ -When connecting a 'socket' to a peer address using _zmq_connect()_ with the +When connecting a 'socket' to a peer address using _xs_connect()_ with the 'ipc' transport, the 'endpoint' shall be interpreted as an arbitrary string identifying the 'pathname' to connect to. The 'pathname' must have been previously created within the operating system namespace by assigning it to a -'socket' with _zmq_bind()_. +'socket' with _xs_bind()_. WIRE FORMAT @@ -53,28 +53,28 @@ EXAMPLES .Assigning a local address to a socket ---- /* Assign the pathname "/tmp/feeds/0" */ -rc = zmq_bind(socket, "ipc:///tmp/feeds/0"); +rc = xs_bind(socket, "ipc:///tmp/feeds/0"); assert (rc == 0); ---- .Connecting a socket ---- /* Connect to the pathname "/tmp/feeds/0" */ -rc = zmq_connect(socket, "ipc:///tmp/feeds/0"); +rc = xs_connect(socket, "ipc:///tmp/feeds/0"); assert (rc == 0); ---- SEE ALSO -------- -linkzmq:zmq_bind[3] -linkzmq:zmq_connect[3] -linkzmq:zmq_inproc[7] -linkzmq:zmq_tcp[7] -linkzmq:zmq_pgm[7] -linkzmq:zmq[7] +linkxs:xs_bind[3] +linkxs:xs_connect[3] +linkxs:xs_inproc[7] +linkxs:xs_tcp[7] +linkxs:xs_pgm[7] +linkxs:xs[7] AUTHORS ------- -The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and -Martin Lucina <martin@lucina.net>. +The Crossroads documentation was written by Martin Sustrik <sustrik@250bpm.com> +and Martin Lucina <martin@lucina.net>. diff --git a/doc/xs_msg_close.txt b/doc/xs_msg_close.txt new file mode 100644 index 0000000..df20617 --- /dev/null +++ b/doc/xs_msg_close.txt @@ -0,0 +1,55 @@ +xs_msg_close(3) +=============== + + +NAME +---- +xs_msg_close - release Crossroads message + + +SYNOPSIS +-------- +*int xs_msg_close (xs_msg_t '*msg');* + + +DESCRIPTION +----------- +The _xs_msg_close()_ function shall inform the Crossroads infrastructure that +any resources associated with the message object referenced by 'msg' are no +longer required and may be released. Actual release of resources associated with +the message object shall be postponed by the library until all users of the +message or underlying data buffer have indicated it is no longer required. + +Applications should ensure that _xs_msg_close()_ is called once a message is +no longer required, otherwise memory leaks may occur. + +CAUTION: Never access 'xs_msg_t' members directly, instead always use the +_xs_msg_ family of functions. + + +RETURN VALUE +------------ +The _xs_msg_close()_ 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 +-------- +linkxs:xs_msg_init[3] +linkxs:xs_msg_init_size[3] +linkxs:xs_msg_init_data[3] +linkxs:xs_msg_data[3] +linkxs:xs_msg_size[3] +linkxs:xs[7] + + +AUTHORS +------- +The Crossroads documentation was written by Martin Sustrik <sustrik@250bpm.com> +and Martin Lucina <martin@lucina.net>. diff --git a/doc/xs_msg_copy.txt b/doc/xs_msg_copy.txt new file mode 100644 index 0000000..13a4298 --- /dev/null +++ b/doc/xs_msg_copy.txt @@ -0,0 +1,57 @@ +xs_msg_copy(3) +============== + + +NAME +---- +xs_msg_copy - copy content of a message to another message + + +SYNOPSIS +-------- +*int xs_msg_copy (xs_msg_t '*dest', xs_msg_t '*src');* + + +DESCRIPTION +----------- +The _xs_msg_copy()_ function shall copy the message object referenced by 'src' +to the message object referenced by 'dest'. The original content of 'dest', if +any, shall be released. + +CAUTION: The implementation may choose not to physically copy the message +content, rather to share the underlying buffer between 'src' and 'dest'. Avoid +modifying message content after a message has been copied with +_xs_msg_copy()_, doing so can result in undefined behaviour. If what you need +is an actual hard copy, allocate a new message using _xs_msg_init_size()_ and +copy the message content using _memcpy()_. + +CAUTION: Never access 'xs_msg_t' members directly, instead always use the +_xs_msg_ family of functions. + + +RETURN VALUE +------------ +The _xs_msg_copy()_ 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 +-------- +linkxs:xs_msg_move[3] +linkxs:xs_msg_init[3] +linkxs:xs_msg_init_size[3] +linkxs:xs_msg_init_data[3] +linkxs:xs_msg_close[3] +linkxs:xs[7] + + +AUTHORS +------- +The Crossroads documentation was written by Martin Sustrik <sustrik@250bpm.com> +and Martin Lucina <martin@lucina.net>. diff --git a/doc/xs_msg_data.txt b/doc/xs_msg_data.txt new file mode 100644 index 0000000..64b5295 --- /dev/null +++ b/doc/xs_msg_data.txt @@ -0,0 +1,48 @@ +xs_msg_data(3) +============== + + +NAME +---- +xs_msg_data - retrieve pointer to message content + + +SYNOPSIS +-------- +*void *xs_msg_data (xs_msg_t '*msg');* + + +DESCRIPTION +----------- +The _xs_msg_data()_ function shall return a pointer to the message content of +the message object referenced by 'msg'. + +CAUTION: Never access 'xs_msg_t' members directly, instead always use the +_xs_msg_ family of functions. + + +RETURN VALUE +------------ +Upon successful completion, _xs_msg_data()_ shall return a pointer to the +message content. + + +ERRORS +------ +No errors are defined. + + +SEE ALSO +-------- +linkxs:xs_msg_size[3] +linkxs:xs_msg_init[3] +linkxs:xs_msg_init_size[3] +linkxs:xs_msg_init_data[3] +linkxs:xs_msg_close[3] +linkxs:xs[7] + + +AUTHORS +------- +The Crossroads documentation was written by Martin Sustrik <sustrik@250bpm.com> +and Martin Lucina <martin@lucina.net>. diff --git a/doc/xs_msg_init.txt b/doc/xs_msg_init.txt new file mode 100644 index 0000000..8b33c8a --- /dev/null +++ b/doc/xs_msg_init.txt @@ -0,0 +1,65 @@ +xs_msg_init(3) +============== + + +NAME +---- +xs_msg_init - initialise empty Crossroads message + + +SYNOPSIS +-------- +*int xs_msg_init (xs_msg_t '*msg');* + + +DESCRIPTION +----------- +The _xs_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 _xs_recv()_. + +CAUTION: Never access 'xs_msg_t' members directly, instead always use the +_xs_msg_ family of functions. + +CAUTION: The functions _xs_msg_init()_, _xs_msg_init_data()_ and +_xs_msg_init_size()_ are mutually exclusive. Never initialize the same +'xs_msg_t' twice. + + +RETURN VALUE +------------ +The _xs_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 +---- +xs_msg_t msg; +rc = xs_msg_init (&msg); +assert (rc == 0); +rc = xs_recv (socket, &msg, 0); +assert (rc == 0); +---- + + +SEE ALSO +-------- +linkxs:xs_msg_init_size[3] +linkxs:xs_msg_init_data[3] +linkxs:xs_msg_close[3] +linkxs:xs_msg_data[3] +linkxs:xs_msg_size[3] +linkxs:xs[7] + + +AUTHORS +------- +The Crossroads documentation was written by Martin Sustrik <sustrik@250bpm.com> +and Martin Lucina <martin@lucina.net>. diff --git a/doc/xs_msg_init_data.txt b/doc/xs_msg_init_data.txt new file mode 100644 index 0000000..dbde0ea --- /dev/null +++ b/doc/xs_msg_init_data.txt @@ -0,0 +1,85 @@ +xs_msg_init_data(3) +=================== + + +NAME +---- +xs_msg_init_data - initialise Crossroads message from a supplied buffer + + +SYNOPSIS +-------- +*typedef void (xs_free_fn) (void '*data', void '*hint');* + +*int xs_msg_init_data (xs_msg_t '*msg', void '*data', size_t 'size', xs_free_fn '*ffn', void '*hint');* + + +DESCRIPTION +----------- +The _xs_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 +the library 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 the library, with the 'data' and 'hint' +arguments supplied to _xs_msg_init_data()_. + +CAUTION: Never access 'xs_msg_t' members directly, instead always use the +_xs_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 _xs_msg_init()_, _xs_msg_init_data()_ and +_xs_msg_init_size()_ are mutually exclusive. Never initialize the same +'xs_msg_t' twice. + + +RETURN VALUE +------------ +The _xs_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); +xs_msg_t msg; +rc = xs_msg_init_data (&msg, data, 6, my_free, NULL); +assert (rc == 0); +---- + + +SEE ALSO +-------- +linkxs:xs_msg_init_size[3] +linkxs:xs_msg_init[3] +linkxs:xs_msg_close[3] +linkxs:xs_msg_data[3] +linkxs:xs_msg_size[3] +linkxs:xs[7] + + +AUTHORS +------- +The Crossroads documentation was written by Martin Sustrik <sustrik@250bpm.com> +and Martin Lucina <martin@lucina.net>. diff --git a/doc/xs_msg_init_size.txt b/doc/xs_msg_init_size.txt new file mode 100644 index 0000000..1e07c3c --- /dev/null +++ b/doc/xs_msg_init_size.txt @@ -0,0 +1,58 @@ +xs_msg_init_size(3) +=================== + + +NAME +---- +xs_msg_init_size - initialise Crossroads message of a specified size + + +SYNOPSIS +-------- +*int xs_msg_init_size (xs_msg_t '*msg', size_t 'size');* + + +DESCRIPTION +----------- +The _xs_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 +_xs_msg_init_size()_ shall not clear the message data. + +CAUTION: Never access 'xs_msg_t' members directly, instead always use the +_xs_msg_ family of functions. + +CAUTION: The functions _xs_msg_init()_, _xs_msg_init_data()_ and +_xs_msg_init_size()_ are mutually exclusive. Never initialize the same +'xs_msg_t' twice. + + +RETURN VALUE +------------ +The _xs_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 +-------- +linkxs:xs_msg_init_data[3] +linkxs:xs_msg_init[3] +linkxs:xs_msg_close[3] +linkxs:xs_msg_data[3] +linkxs:xs_msg_size[3] +linkxs:xs[7] + + +AUTHORS +------- +The Crossroads documentation was written by Martin Sustrik <sustrik@250bpm.com> +and Martin Lucina <martin@lucina.net>. diff --git a/doc/xs_msg_move.txt b/doc/xs_msg_move.txt new file mode 100644 index 0000000..d7930cf --- /dev/null +++ b/doc/xs_msg_move.txt @@ -0,0 +1,52 @@ +xs_msg_move(3) +============== + + +NAME +---- +xs_msg_move - move content of a message to another message + + +SYNOPSIS +-------- +*int xs_msg_move (xs_msg_t '*dest', xs_msg_t '*src');* + + +DESCRIPTION +----------- +The _xs_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 _xs_msg_move()_. +The original content of 'dest', if any, shall be released. + +CAUTION: Never access 'xs_msg_t' members directly, instead always use the +_xs_msg_ family of functions. + + +RETURN VALUE +------------ +The _xs_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 +-------- +linkxs:xs_msg_copy[3] +linkxs:xs_msg_init[3] +linkxs:xs_msg_init_size[3] +linkxs:xs_msg_init_data[3] +linkxs:xs_msg_close[3] +linkxs:xs[7] + + +AUTHORS +------- +The Crossroads documentation was written by Martin Sustrik <sustrik@250bpm.com> +and Martin Lucina <martin@lucina.net>. diff --git a/doc/xs_msg_size.txt b/doc/xs_msg_size.txt new file mode 100644 index 0000000..433d36e --- /dev/null +++ b/doc/xs_msg_size.txt @@ -0,0 +1,48 @@ +xs_msg_size(3) +============== + + +NAME +---- +xs_msg_size - retrieve message content size in bytes + + +SYNOPSIS +-------- +*size_t xs_msg_size (xs_msg_t '*msg');* + + +DESCRIPTION +----------- +The _xs_msg_size()_ function shall return the size in bytes of the content of +the message object referenced by 'msg'. + +CAUTION: Never access 'xs_msg_t' members directly, instead always use the +_xs_msg_ family of functions. + + +RETURN VALUE +------------ +Upon successful completion, _xs_msg_size()_ shall return the size of the +message content in bytes. + + +ERRORS +------ +No errors are defined. + + +SEE ALSO +-------- +linkxs:xs_msg_data[3] +linkxs:xs_msg_init[3] +linkxs:xs_msg_init_size[3] +linkxs:xs_msg_init_data[3] +linkxs:xs_msg_close[3] +linkxs:xs[7] + + +AUTHORS +------- +The Crossroads documentation was written by Martin Sustrik <sustrik@250bpm.com> +and Martin Lucina <martin@lucina.net>. diff --git a/doc/zmq_pgm.txt b/doc/xs_pgm.txt index d96d3ba..fcce19a 100644 --- a/doc/zmq_pgm.txt +++ b/doc/xs_pgm.txt @@ -1,10 +1,10 @@ -zmq_pgm(7) -========== +xs_pgm(7) +========= NAME ---- -zmq_pgm - 0MQ reliable multicast transport using PGM +xs_pgm - reliable multicast transport via PGM protocol SYNOPSIS @@ -15,17 +15,17 @@ 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" where PGM datagrams are encapsulated inside -UDP datagrams (the 'epgm' transport). +Crossroads implement 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" 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. +The 'pgm' and 'epgm' transports can only be used with the 'XS_PUB' and +'XS_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]. +'XS_RATE', and 'XS_RECOVERY_IVL' options documented in +linkxs:xs_setsockopt[3]. CAUTION: The 'pgm' transport implementation requires access to raw IP sockets. Additional privileges may be required on some operating systems for this @@ -36,7 +36,7 @@ not require any special privileges. ADDRESSING ---------- -A 0MQ address string consists of two parts as follows: +A Crossroads address string consists of two parts as follows: 'transport'`://`'endpoint'. The 'transport' part specifies the underlying transport protocol to use. For the standard PGM protocol, 'transport' shall be set to `pgm`. For the "Encapsulated PGM" protocol 'transport' shall be set to @@ -46,7 +46,7 @@ transport is defined below. Connecting a socket ~~~~~~~~~~~~~~~~~~~ -When connecting a socket to a peer address using _zmq_connect()_ with the 'pgm' +When connecting a socket to a peer address using _xs_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. @@ -68,17 +68,17 @@ 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]. +Consecutive PGM datagrams are interpreted by the library as a single continuous +stream of data where messages are not necessarily aligned with PGM datagram +boundaries and a single message may span several PGM datagrams. This stream +of data consists of Crossroads messages encapsulated in 'frames' as described in +linkxs:xs_tcp[7]. PGM datagram payload ~~~~~~~~~~~~~~~~~~~~ The following ABNF grammar represents the payload of a single PGM datagram as -used by 0MQ: +used by Crossroads: .... datagram = (offset data) @@ -105,8 +105,8 @@ The following diagram illustrates the layout of a single PGM datagram payload: +------------------+----------------------+ .... -The following diagram further illustrates how three example 0MQ frames are laid -out in consecutive PGM datagram payloads: +The following diagram further illustrates how three example Crossroads frames +are laid out in consecutive PGM datagram payloads: .... First datagram payload @@ -136,26 +136,26 @@ EXAMPLE /* 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"); +rc = xs_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"); +rc = xs_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] +linkxs:xs_connect[3] +linkxs:xs_setsockopt[3] +linkxs:xs_tcp[7] +linkxs:xs_ipc[7] +linkxs:xs_inproc[7] +linkxs:xs[7] AUTHORS ------- -The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and -Martin Lucina <martin@lucina.net>. +The Crossroads documentation was written by Martin Sustrik <sustrik@250bpm.com> +and Martin Lucina <martin@lucina.net>. diff --git a/doc/xs_poll.txt b/doc/xs_poll.txt new file mode 100644 index 0000000..37f7dc5 --- /dev/null +++ b/doc/xs_poll.txt @@ -0,0 +1,129 @@ +xs_poll(3) +========== + + +NAME +---- +xs_poll - input/output multiplexing + + +SYNOPSIS +-------- + +*int xs_poll (xs_pollitem_t '*items', int 'nitems', long 'timeout');* + + +DESCRIPTION +----------- +The _xs_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 *xs_pollitem_t* +structure. The 'nitems' argument specifies the number of items in the 'items' +array. The *xs_pollitem_t* structure is defined as follows: + +["literal", subs="quotes"] +typedef struct +{ + void '*socket'; + int 'fd'; + short 'events'; + short 'revents'; +} xs_pollitem_t; + +For each *xs_pollitem_t* item, _xs_poll()_ shall examine either the Crossroads +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 *xs_pollitem_t*, the Crossroads socket referenced by +'socket' shall take precedence and the value of 'fd' shall be ignored. + +For each *xs_pollitem_t* item, _xs_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 *xs_pollitem_t* item, +_xs_poll()_ shall wait 'timeout' milliseconds for an event to occur on +any of the requested items. If the value of 'timeout' is `0`, _xs_poll()_ +shall return immediately. If the value of 'timeout' is `-1`, _xs_poll()_ shall +block indefinitely until a requested event has occurred on at least one +*xs_pollitem_t*. + +The 'events' and 'revents' members of *xs_pollitem_t* are bit masks constructed +by OR'ing a combination of the following event flags: + +*XS_POLLIN*:: +For Crossroads 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. + +*XS_POLLOUT*:: +For Crossroads 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. + +*XS_POLLERR*:: +For standard sockets, this flag is passed through _xs_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 Crossroads sockets +this flag has no effect if set in 'events', and shall never be returned in +'revents' by _xs_poll()_. + +NOTE: The _xs_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. + + +RETURN VALUE +------------ +Upon successful completion, the _xs_poll()_ function shall return the number +of *xs_pollitem_t* structures with events signaled in 'revents' or `0` if no +events have been signaled. Upon failure, _xs_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 '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 Crossroads socket and a standard socket. +---- +xs_pollitem_t items [2]; +/* First item refers to Crossroads socket 'socket' */ +items[0].socket = socket; +items[0].events = XS_POLLIN; +/* Second item refers to standard socket 'fd' */ +items[1].socket = NULL; +items[1].fd = fd; +items[1].events = XS_POLLIN; +/* Poll for events indefinitely */ +int rc = xs_poll (items, 2, -1); +assert (rc >= 0); +/* Returned events will be stored in items[].revents */ +---- + + +SEE ALSO +-------- +linkxs:xs_socket[3] +linkxs:xs_send[3] +linkxs:xs_recv[3] +linkxs:xs[7] + +Your operating system documentation for the _poll()_ system call. + + +AUTHORS +------- +The Crossroads documentation was written by Martin Sustrik <sustrik@250bpm.com> +and Martin Lucina <martin@lucina.net>. diff --git a/doc/zmq_recv.txt b/doc/xs_recv.txt index 3a5be9c..26a6c54 100644 --- a/doc/zmq_recv.txt +++ b/doc/xs_recv.txt @@ -1,47 +1,47 @@ -zmq_recv(3) -=========== +xs_recv(3) +========== NAME ---- -zmq_recv - receive a message part from a socket +xs_recv - receive a message part from a socket SYNOPSIS -------- -*int zmq_recv (void '*socket', void '*buf', size_t 'len', int 'flags');* +*int xs_recv (void '*socket', void '*buf', size_t 'len', int 'flags');* DESCRIPTION ----------- -The _zmq_recv()_ function shall receive a message from the socket referenced +The _xs_recv()_ function shall receive a message from the socket referenced by the 'socket' argument and store it in the buffer referenced by the 'buf' argument. Any bytes exceeding the length specified by the 'len' argument shall be truncated. If there are no messages available on the specified 'socket' -the _zmq_recv()_ function shall block until the request can be satisfied. +the _xs_recv()_ function shall block until the request can be satisfied. The 'flags' argument is a combination of the flags defined below: -*ZMQ_DONTWAIT*:: +*XS_DONTWAIT*:: Specifies that the operation should be performed in non-blocking mode. If there -are no messages available on the specified 'socket', the _zmq_recv()_ +are no messages available on the specified 'socket', the _xs_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 +A Crossroads message is composed of 1 or more message parts. Each message +part is an independent 'xs_msg_t' in its own right. Crossroads ensure 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 multipart messages must use the _ZMQ_RCVMORE_ -linkzmq:zmq_getsockopt[3] option after calling _zmq_recv()_ to determine if +An application that processes multipart messages must use the _XS_RCVMORE_ +linkxs:xs_getsockopt[3] option after calling _xs_recv()_ to determine if there are further parts to receive. RETURN VALUE ------------ -The _zmq_recv()_ function shall return number of bytes in the message +The _xs_recv()_ function shall return number of bytes in the message if successful. Note that the value can exceed the value of the 'len' parameter in case the message was truncated. If not successful the function shall return `-1` and set 'errno' to one of the values defined below. @@ -52,14 +52,14 @@ ERRORS *EAGAIN*:: Non-blocking mode was requested and no messages are available at the moment. *ENOTSUP*:: -The _zmq_recv()_ operation is not supported by this socket type. +The _xs_recv()_ operation is not supported by this socket type. *EFSM*:: -The _zmq_recv()_ operation cannot be performed on this socket at the moment +The _xs_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. +socket types that switch between several states, such as XS_REP. See the +_messaging patterns_ section of linkxs:xs_socket[3] for more information. *ETERM*:: -The 0MQ 'context' associated with the specified 'socket' was terminated. +The 'context' associated with the specified 'socket' was terminated. *ENOTSOCK*:: The provided 'socket' was invalid. *EINTR*:: @@ -72,19 +72,19 @@ EXAMPLE .Receiving a message from a socket ---- char buf [256]; -nbytes = zmq_recv (socket, buf, 256, 0); +nbytes = xs_recv (socket, buf, 256, 0); assert (nbytes != -1); ---- SEE ALSO -------- -linkzmq:zmq_recvmsg[3] -linkzmq:zmq_send[3] -linkzmq:zmq_sendmsg[3] -linkzmq:zmq_getsockopt[3] -linkzmq:zmq_socket[7] -linkzmq:zmq[7] +linkxs:xs_recvmsg[3] +linkxs:xs_send[3] +linkxs:xs_sendmsg[3] +linkxs:xs_getsockopt[3] +linkxs:xs_socket[7] +linkxs:xs[7] AUTHORS diff --git a/doc/zmq_recvmsg.txt b/doc/xs_recvmsg.txt index b7575a0..735fed0 100644 --- a/doc/zmq_recvmsg.txt +++ b/doc/xs_recvmsg.txt @@ -1,48 +1,48 @@ -zmq_recvmsg(3) -============== +xs_recvmsg(3) +============= NAME ---- -zmq_recvmsg - receive a message part from a socket +xs_recvmsg - receive a message part from a socket SYNOPSIS -------- -*int zmq_recvmsg (void '*socket', zmq_msg_t '*msg', int 'flags');* +*int xs_recvmsg (void '*socket', xs_msg_t '*msg', int 'flags');* DESCRIPTION ----------- -The _zmq_recvmsg()_ function shall receive a message part from the socket +The _xs_recvmsg()_ 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_recvmsg()_ function shall block until the request can be satisfied. +the _xs_recvmsg()_ function shall block until the request can be satisfied. The 'flags' argument is a combination of the flags defined below: -*ZMQ_DONTWAIT*:: +*XS_DONTWAIT*:: Specifies that the operation should be performed in non-blocking mode. If there -are no messages available on the specified 'socket', the _zmq_recvmsg()_ +are no messages available on the specified 'socket', the _xs_recvmsg()_ 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 +A Crossroads message is composed of 1 or more message parts. Each message +part is an independent 'xs_msg_t' in its own right. Crossroads ensure 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 multipart messages must use the _ZMQ_RCVMORE_ -linkzmq:zmq_getsockopt[3] option after calling _zmq_recvmsg()_ to determine if +An application that processes multipart messages must use the _XS_RCVMORE_ +linkxs:xs_getsockopt[3] option after calling _xs_recvmsg()_ to determine if there are further parts to receive. RETURN VALUE ------------ -The _zmq_recvmsg()_ function shall return number of bytes in the message +The _xs_recvmsg()_ 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. @@ -52,14 +52,14 @@ ERRORS *EAGAIN*:: Non-blocking mode was requested and no messages are available at the moment. *ENOTSUP*:: -The _zmq_recvmsg()_ operation is not supported by this socket type. +The _xs_recvmsg()_ operation is not supported by this socket type. *EFSM*:: -The _zmq_recvmsg()_ operation cannot be performed on this socket at the moment +The _xs_recvmsg()_ 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. +socket types that switch between several states, such as XS_REP. See the +_messaging patterns_ section of linkxs:xs_socket[3] for more information. *ETERM*:: -The 0MQ 'context' associated with the specified 'socket' was terminated. +The 'context' associated with the specified 'socket' was terminated. *ENOTSOCK*:: The provided 'socket' was invalid. *EINTR*:: @@ -73,15 +73,15 @@ EXAMPLE ------- .Receiving a message from a socket ---- -/* Create an empty 0MQ message */ -zmq_msg_t msg; -int rc = zmq_msg_init (&msg); +/* Create an empty message */ +xs_msg_t msg; +int rc = xs_msg_init (&msg); assert (rc == 0); /* Block until a message is available to be received from socket */ -rc = zmq_recvmsg (socket, &msg, 0); +rc = xs_recvmsg (socket, &msg, 0); assert (rc != -1); /* Release message */ -zmq_msg_close (&msg); +xs_msg_close (&msg); ---- .Receiving a multi-part message @@ -89,29 +89,29 @@ zmq_msg_close (&msg); 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); + /* Create an empty message to hold the message part */ + xs_msg_t part; + int rc = xs_msg_init (&part); assert (rc == 0); /* Block until a message is available to be received from socket */ - rc = zmq_recvmsg (socket, &part, 0); + rc = xs_recvmsg (socket, &part, 0); assert (rc != -1); /* Determine if more message parts are to follow */ - rc = zmq_getsockopt (socket, ZMQ_RCVMORE, &more, &more_size); + rc = xs_getsockopt (socket, XS_RCVMORE, &more, &more_size); assert (rc == 0); - zmq_msg_close (&part); + xs_msg_close (&part); } while (more); ---- SEE ALSO -------- -linkzmq:zmq_recv[3] -linkzmq:zmq_send[3] -linkzmq:zmq_sendmsg[3] -linkzmq:zmq_getsockopt[3] -linkzmq:zmq_socket[7] -linkzmq:zmq[7] +linkxs:xs_recv[3] +linkxs:xs_send[3] +linkxs:xs_sendmsg[3] +linkxs:xs_getsockopt[3] +linkxs:xs_socket[7] +linkxs:xs[7] AUTHORS diff --git a/doc/zmq_send.txt b/doc/xs_send.txt index 58c761f..c5b7d74 100644 --- a/doc/zmq_send.txt +++ b/doc/xs_send.txt @@ -1,53 +1,53 @@ -zmq_send(3) -=========== +xs_send(3) +========== NAME ---- -zmq_send - send a message part on a socket +xs_send - send a message part on a socket SYNOPSIS -------- -*int zmq_send (void '*socket', void '*buf', size_t 'len', int 'flags');* +*int xs_send (void '*socket', void '*buf', size_t 'len', int 'flags');* DESCRIPTION ----------- -The _zmq_send()_ function shall queue a message created from the buffer +The _xs_send()_ function shall queue a message created from the buffer referenced by the 'buf' and 'len' arguments. The 'flags' argument is a combination of the flags defined below: -*ZMQ_DONTWAIT*:: +*XS_DONTWAIT*:: Specifies that the operation should be performed in non-blocking mode. If the -message cannot be queued on the 'socket', the _zmq_send()_ function shall +message cannot be queued on the 'socket', the _xs_send()_ function shall fail with 'errno' set to EAGAIN. -*ZMQ_SNDMORE*:: +*XS_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. -NOTE: A successful invocation of _zmq_send()_ does not indicate that the +NOTE: A successful invocation of _xs_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. +the 'socket' and Crossroads have 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 +A Crossroads message is composed of 1 or more message parts. Each message +part is an independent 'xs_msg_t' in its own right. Crossroads ensure 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 multipart messages must use the _ZMQ_SNDMORE_ flag +An application that sends multipart messages must use the _XS_SNDMORE_ flag when sending each data part except the final one. RETURN VALUE ------------ -The _zmq_send()_ function shall return number of bytes in the message +The _xs_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. @@ -57,14 +57,14 @@ ERRORS *EAGAIN*:: Non-blocking mode was requested and the message cannot be sent at the moment. *ENOTSUP*:: -The _zmq_send()_ operation is not supported by this socket type. +The _xs_send()_ operation is not supported by this socket type. *EFSM*:: -The _zmq_send()_ operation cannot be performed on this socket at the moment +The _xs_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. +socket types that switch between several states, such as XS_REP. See the +_messaging patterns_ section of linkxs:xs_socket[3] for more information. *ETERM*:: -The 0MQ 'context' associated with the specified 'socket' was terminated. +The 'context' associated with the specified 'socket' was terminated. *ENOTSOCK*:: The provided 'socket' was invalid. *EINTR*:: @@ -72,7 +72,7 @@ The operation was interrupted by delivery of a signal before the message was sent. *ECANTROUTE*:: Message cannot be routed to the destination specified as the peer is either -dead or disconnected. This error makes sense only with ZMQ_ROUTER socket. +dead or disconnected. This error makes sense only with XS_ROUTER socket. EXAMPLE @@ -80,22 +80,22 @@ EXAMPLE .Sending a multi-part message ---- /* Send a multi-part message consisting of three parts to socket */ -rc = zmq_send (socket, "ABC", 3, ZMQ_SNDMORE); +rc = xs_send (socket, "ABC", 3, XS_SNDMORE); assert (rc == 3); -rc = zmq_send (socket, "DEFGH", 5, ZMQ_SNDMORE); +rc = xs_send (socket, "DEFGH", 5, XS_SNDMORE); assert (rc == 5); /* Final part; no more parts to follow */ -rc = zmq_send (socket, "JK", 2, 0); +rc = xs_send (socket, "JK", 2, 0); assert (rc == 2); ---- SEE ALSO -------- -linkzmq:zmq_sendmsg[3] -linkzmq:zmq_recv[3] -linkzmq:zmq_recvmsg[3] -linkzmq:zmq_socket[7] -linkzmq:zmq[7] +linkxs:xs_sendmsg[3] +linkxs:xs_recv[3] +linkxs:xs_recvmsg[3] +linkxs:xs_socket[7] +linkxs:xs[7] AUTHORS diff --git a/doc/zmq_sendmsg.txt b/doc/xs_sendmsg.txt index 3c09bec..bf94ecd 100644 --- a/doc/zmq_sendmsg.txt +++ b/doc/xs_sendmsg.txt @@ -1,56 +1,56 @@ -zmq_sendmsg(3) -============== +xs_sendmsg(3) +============= NAME ---- -zmq_sendmsg - send a message part on a socket +xs_sendmsg - send a message part on a socket SYNOPSIS -------- -*int zmq_sendmsg (void '*socket', zmq_msg_t '*msg', int 'flags');* +*int xs_sendmsg (void '*socket', xs_msg_t '*msg', int 'flags');* DESCRIPTION ----------- -The _zmq_sendmsg()_ function shall queue the message referenced by the 'msg' +The _xs_sendmsg()_ 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*:: +*XS_DONTWAIT*:: Specifies that the operation should be performed in non-blocking mode. If the -message cannot be queued on the 'socket', the _zmq_sendmsg()_ function shall +message cannot be queued on the 'socket', the _xs_sendmsg()_ function shall fail with 'errno' set to EAGAIN. -*ZMQ_SNDMORE*:: +*XS_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_sendmsg()_ is nullified during the +The _xs_msg_t_ structure passed to _xs_sendmsg()_ 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()_). +it using (e.g. using _xs_msg_copy()_). -NOTE: A successful invocation of _zmq_sendmsg()_ does not indicate that the +NOTE: A successful invocation of _xs_sendmsg()_ 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. +the 'socket' and Crossroads have 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 +A Crossroads message is composed of 1 or more message parts. Each message +part is an independent 'xs_msg_t' in its own right. Crossroads ensure 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 multipart messages must use the _ZMQ_SNDMORE_ flag +An application that sends multipart messages must use the _XS_SNDMORE_ flag when sending each data part except the final one. RETURN VALUE ------------ -The _zmq_sendmsg()_ function shall return number of bytes in the message +The _xs_sendmsg()_ 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. @@ -60,14 +60,14 @@ ERRORS *EAGAIN*:: Non-blocking mode was requested and the message cannot be sent at the moment. *ENOTSUP*:: -The _zmq_sendmsg()_ operation is not supported by this socket type. +The _xs_sendmsg()_ operation is not supported by this socket type. *EFSM*:: -The _zmq_sendmsg()_ operation cannot be performed on this socket at the moment +The _xs_sendmsg()_ 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. +socket types that switch between several states, such as XS_REP. See the +_messaging patterns_ section of linkxs:xs_socket[3] for more information. *ETERM*:: -The 0MQ 'context' associated with the specified 'socket' was terminated. +The 'context' associated with the specified 'socket' was terminated. *ENOTSOCK*:: The provided 'socket' was invalid. *EINTR*:: @@ -77,7 +77,7 @@ sent. Invalid message. *ECANTROUTE*:: Message cannot be routed to the destination specified as the peer is either -dead or disconnected. This error makes sense only with ZMQ_ROUTER socket. +dead or disconnected. This error makes sense only with XS_ROUTER socket. EXAMPLE @@ -85,33 +85,33 @@ 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); +xs_msg_t msg; +int rc = xs_msg_init_size (&msg, 6); assert (rc == 0); /* Fill in message content with 'AAAAAA' */ -memset (zmq_msg_data (&msg), 'A', 6); +memset (xs_msg_data (&msg), 'A', 6); /* Send the message to the socket */ -rc = zmq_sendmsg (socket, &msg, 0); +rc = xs_sendmsg (socket, &msg, 0); assert (rc == 6); ---- .Sending a multi-part message ---- /* Send a multi-part message consisting of three parts to socket */ -rc = zmq_sendmsg (socket, &part1, ZMQ_SNDMORE); -rc = zmq_sendmsg (socket, &part2, ZMQ_SNDMORE); +rc = xs_sendmsg (socket, &part1, XS_SNDMORE); +rc = xs_sendmsg (socket, &part2, XS_SNDMORE); /* Final part; no more parts to follow */ -rc = zmq_sendmsg (socket, &part3, 0); +rc = xs_sendmsg (socket, &part3, 0); ---- SEE ALSO -------- -linkzmq:zmq_recv[3] -linkzmq:zmq_recv[3] -linkzmq:zmq_recvmsg[3] -linkzmq:zmq_socket[7] -linkzmq:zmq[7] +linkxs:xs_recv[3] +linkxs:xs_recv[3] +linkxs:xs_recvmsg[3] +linkxs:xs_socket[7] +linkxs:xs[7] AUTHORS diff --git a/doc/zmq_setsockopt.txt b/doc/xs_setsockopt.txt index ca8ced0..7cb91d2 100644 --- a/doc/zmq_setsockopt.txt +++ b/doc/xs_setsockopt.txt @@ -1,41 +1,41 @@ -zmq_setsockopt(3) -================= +xs_setsockopt(3) +================ NAME ---- -zmq_setsockopt - set 0MQ socket options +xs_setsockopt - set Crossroads socket options SYNOPSIS -------- -*int zmq_setsockopt (void '*socket', int 'option_name', const void '*option_value', size_t 'option_len');* +*int xs_setsockopt (void '*socket', int 'option_name', const void '*option_value', size_t 'option_len');* -Caution: All options, with the exception of ZMQ_SUBSCRIBE, ZMQ_UNSUBSCRIBE and -ZMQ_LINGER, only take effect for subsequent socket bind/connects. +Caution: All options, with the exception of XS_SUBSCRIBE, XS_UNSUBSCRIBE and +XS_LINGER, only take effect for subsequent socket bind/connects. DESCRIPTION ----------- -The _zmq_setsockopt()_ function shall set the option specified by the +The _xs_setsockopt()_ function shall set the option specified by the 'option_name' argument to the value pointed to by the 'option_value' argument -for the 0MQ socket pointed to by the 'socket' argument. The 'option_len' +for the Crossroads socket pointed to by the 'socket' argument. The 'option_len' argument is the size of the option value in bytes. -The following socket options can be set with the _zmq_setsockopt()_ function: +The following socket options can be set with the _xs_setsockopt()_ function: -ZMQ_SNDHWM: Set high water mark for outbound messages +XS_SNDHWM: Set high water mark for outbound messages ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_SNDHWM' option shall set the high water mark for outbound messages on +The 'XS_SNDHWM' option shall set the high water mark for outbound messages on the specified 'socket'. The high water mark is a hard limit on the maximum -number of outstanding messages 0MQ shall queue in memory for any single peer -that the specified 'socket' is communicating with. +number of outstanding messages the library shall queue in memory for any single +peer that the specified 'socket' is communicating with. If this limit has been reached the socket shall enter an exceptional state and -depending on the socket type, 0MQ shall take appropriate action such as +depending on the socket type, the library shall take appropriate action such as blocking or dropping sent messages. Refer to the individual socket descriptions -in linkzmq:zmq_socket[3] for details on the exact action taken for each socket +in linkxs:xs_socket[3] for details on the exact action taken for each socket type. [horizontal] @@ -45,17 +45,17 @@ Default value:: 1000 Applicable socket types:: all -ZMQ_RCVHWM: Set high water mark for inbound messages +XS_RCVHWM: Set high water mark for inbound messages ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_RCVHWM' option shall set the high water mark for inbound messages on +The 'XS_RCVHWM' option shall set the high water mark for inbound messages on the specified 'socket'. The high water mark is a hard limit on the maximum -number of outstanding messages 0MQ shall queue in memory for any single peer -that the specified 'socket' is communicating with. +number of outstanding messages the libray shall queue in memory for any single +peer that the specified 'socket' is communicating with. If this limit has been reached the socket shall enter an exceptional state and -depending on the socket type, 0MQ shall take appropriate action such as +depending on the socket type, the library shall take appropriate action such as blocking or dropping sent messages. Refer to the individual socket descriptions -in linkzmq:zmq_socket[3] for details on the exact action taken for each socket +in linkxs:xs_socket[3] for details on the exact action taken for each socket type. [horizontal] @@ -65,20 +65,20 @@ Default value:: 1000 Applicable socket types:: all -ZMQ_AFFINITY: Set I/O thread affinity +XS_AFFINITY: Set I/O thread affinity ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_AFFINITY' option shall set the I/O thread affinity for newly created +The 'XS_AFFINITY' option shall set the I/O thread affinity for newly created connections on the specified 'socket'. -Affinity determines which threads from the 0MQ I/O thread pool associated with -the socket's _context_ shall handle newly created connections. A value of zero -specifies no affinity, meaning that work shall be distributed fairly among all -0MQ I/O threads in the thread pool. For non-zero values, the lowest bit -corresponds to thread 1, second lowest bit to thread 2 and so on. For example, -a value of 3 specifies that subsequent connections on 'socket' shall be handled -exclusively by I/O threads 1 and 2. +Affinity determines which threads from the Crossroads I/O thread pool associated +with the socket's _context_ shall handle newly created connections. A value of +zero specifies no affinity, meaning that work shall be distributed fairly among +all Crossroads I/O threads in the thread pool. For non-zero values, the lowest +bit corresponds to thread 1, second lowest bit to thread 2 and so on. For +example, a value of 3 specifies that subsequent connections on 'socket' shall be +handled exclusively by I/O threads 1 and 2. -See also linkzmq:zmq_init[3] for details on allocating the number of I/O +See also linkxs:xs_init[3] for details on allocating the number of I/O threads for a specific _context_. [horizontal] @@ -88,49 +88,49 @@ Default value:: 0 Applicable socket types:: N/A -ZMQ_SUBSCRIBE: Establish message filter +XS_SUBSCRIBE: Establish message filter ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_SUBSCRIBE' option shall establish a new message filter on a 'ZMQ_SUB' -socket. Newly created 'ZMQ_SUB' sockets shall filter out all incoming messages, +The 'XS_SUBSCRIBE' option shall establish a new message filter on a 'XS_SUB' +socket. Newly created 'XS_SUB' sockets shall filter out all incoming messages, therefore you should call this option to establish an initial message filter. An empty 'option_value' of length zero shall subscribe to all incoming messages. A non-empty 'option_value' shall subscribe to all messages beginning with the specified prefix. Multiple filters may be attached to a single -'ZMQ_SUB' socket, in which case a message shall be accepted if it matches at +'XS_SUB' socket, in which case a message shall be accepted if it matches at least one filter. [horizontal] Option value type:: binary data Option value unit:: N/A Default value:: N/A -Applicable socket types:: ZMQ_SUB +Applicable socket types:: XS_SUB -ZMQ_UNSUBSCRIBE: Remove message filter +XS_UNSUBSCRIBE: Remove message filter ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_UNSUBSCRIBE' option shall remove an existing message filter on a -'ZMQ_SUB' socket. The filter specified must match an existing filter previously -established with the 'ZMQ_SUBSCRIBE' option. If the socket has several -instances of the same filter attached the 'ZMQ_UNSUBSCRIBE' option shall remove +The 'XS_UNSUBSCRIBE' option shall remove an existing message filter on a +'XS_SUB' socket. The filter specified must match an existing filter previously +established with the 'XS_SUBSCRIBE' option. If the socket has several +instances of the same filter attached the 'XS_UNSUBSCRIBE' option shall remove only one instance, leaving the rest in place and functional. [horizontal] Option value type:: binary data Option value unit:: N/A Default value:: N/A -Applicable socket types:: ZMQ_SUB +Applicable socket types:: XS_SUB -ZMQ_IDENTITY: Set socket identity +XS_IDENTITY: Set socket identity ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_IDENTITY' option shall set the identity of the specified 'socket'. +The 'XS_IDENTITY' option shall set the identity of the specified 'socket'. Socket identity is used only by request/reply pattern. Namely, it can be used in tandem with ROUTER socket to route messages to the peer with specific identity. Identity should be at least one byte and at most 255 bytes long. Identities -starting with binary zero are reserved for use by 0MQ infrastructure. +starting with binary zero are reserved for use by Crossroads infrastructure. [horizontal] Option value type:: binary data @@ -139,10 +139,10 @@ Default value:: NULL Applicable socket types:: all -ZMQ_RATE: Set multicast data rate +XS_RATE: Set multicast data rate ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_RATE' option shall set the maximum send or receive data rate for -multicast transports such as linkzmq:zmq_pgm[7] using the specified 'socket'. +The 'XS_RATE' option shall set the maximum send or receive data rate for +multicast transports such as linkxs:xs_pgm[7] using the specified 'socket'. [horizontal] Option value type:: int @@ -151,9 +151,9 @@ Default value:: 100 Applicable socket types:: all, when using multicast transports -ZMQ_RECOVERY_IVL: Set multicast recovery interval +XS_RECOVERY_IVL: Set multicast recovery interval ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_RECOVERY_IVL' option shall set the recovery interval for multicast +The 'XS_RECOVERY_IVL' option shall set the recovery interval for multicast transports using the specified 'socket'. The recovery interval determines the maximum time in milliseconds that a receiver can be absent from a multicast group before unrecoverable data loss will occur. @@ -168,9 +168,9 @@ Option value unit:: milliseconds Default value:: 10000 Applicable socket types:: all, when using multicast transports -ZMQ_SNDBUF: Set kernel transmit buffer size +XS_SNDBUF: Set kernel transmit buffer size ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_SNDBUF' option shall set the underlying kernel transmit buffer size +The 'XS_SNDBUF' option shall set the underlying kernel transmit buffer size for the 'socket' to the specified size in bytes. A value of zero means leave the OS default unchanged. For details please refer to your operating system documentation for the 'SO_SNDBUF' socket option. @@ -182,9 +182,9 @@ Default value:: 0 Applicable socket types:: all -ZMQ_RCVBUF: Set kernel receive buffer size +XS_RCVBUF: Set kernel receive buffer size ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_RCVBUF' option shall set the underlying kernel receive buffer size for +The 'XS_RCVBUF' option shall set the underlying kernel receive buffer size for the 'socket' to the specified size in bytes. A value of zero means leave the OS default unchanged. For details refer to your operating system documentation for the 'SO_RCVBUF' socket option. @@ -196,26 +196,26 @@ Default value:: 0 Applicable socket types:: all -ZMQ_LINGER: Set linger period for socket shutdown +XS_LINGER: Set linger period for socket shutdown ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_LINGER' option shall set the linger period for the specified 'socket'. +The 'XS_LINGER' option shall set the linger period for the specified 'socket'. The linger period determines how long pending messages which have yet to be sent to a peer shall linger in memory after a socket is closed with -linkzmq:zmq_close[3], and further affects the termination of the socket's -context with linkzmq:zmq_term[3]. The following outlines the different +linkxs:xs_close[3], and further affects the termination of the socket's +context with linkxs:xs_term[3]. The following outlines the different behaviours: * The default value of '-1' specifies an infinite linger period. Pending - messages shall not be discarded after a call to _zmq_close()_; attempting to - terminate the socket's context with _zmq_term()_ shall block until all + messages shall not be discarded after a call to _xs_close()_; attempting to + terminate the socket's context with _xs_term()_ shall block until all pending messages have been sent to a peer. * The value of '0' specifies no linger period. Pending messages shall be - discarded immediately when the socket is closed with _zmq_close()_. + discarded immediately when the socket is closed with _xs_close()_. * Positive values specify an upper bound for the linger period in milliseconds. - Pending messages shall not be discarded after a call to _zmq_close()_; - attempting to terminate the socket's context with _zmq_term()_ shall block + Pending messages shall not be discarded after a call to _xs_close()_; + attempting to terminate the socket's context with _xs_term()_ shall block until either all pending messages have been sent to a peer, or the linger period expires, after which any pending messages shall be discarded. @@ -226,14 +226,14 @@ Default value:: -1 (infinite) Applicable socket types:: all -ZMQ_RECONNECT_IVL: Set reconnection interval +XS_RECONNECT_IVL: Set reconnection interval ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_RECONNECT_IVL' option shall set the initial reconnection interval for -the specified 'socket'. The reconnection interval is the period 0MQ +The 'XS_RECONNECT_IVL' option shall set the initial reconnection interval for +the specified 'socket'. The reconnection interval is the period the library shall wait between attempts to reconnect disconnected peers when using connection-oriented transports. -NOTE: The reconnection interval may be randomized by 0MQ to prevent +NOTE: The reconnection interval may be randomized by the library to prevent reconnection storms in topologies with a large number of peers per socket. [horizontal] @@ -243,27 +243,28 @@ Default value:: 100 Applicable socket types:: all, only for connection-oriented transports -ZMQ_RECONNECT_IVL_MAX: Set maximum reconnection interval +XS_RECONNECT_IVL_MAX: Set maximum reconnection interval ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_RECONNECT_IVL_MAX' option shall set the maximum reconnection interval -for the specified 'socket'. This is the maximum period 0MQ shall wait between -attempts to reconnect. On each reconnect attempt, the previous interval shall be -doubled untill ZMQ_RECONNECT_IVL_MAX is reached. This allows for exponential -backoff strategy. Default value means no exponential backoff is performed and -reconnect interval calculations are only based on ZMQ_RECONNECT_IVL. +The 'XS_RECONNECT_IVL_MAX' option shall set the maximum reconnection interval +for the specified 'socket'. This is the maximum period the library shall wait +between attempts to reconnect. On each reconnect attempt, the previous interval +shall be doubled untill XS_RECONNECT_IVL_MAX is reached. This allows for +exponential backoff strategy. Default value means no exponential backoff is +performed and reconnect interval calculations are only based on +XS_RECONNECT_IVL. -NOTE: Values less than ZMQ_RECONNECT_IVL will be ignored. +NOTE: Values less than XS_RECONNECT_IVL will be ignored. [horizontal] Option value type:: int Option value unit:: milliseconds -Default value:: 0 (only use ZMQ_RECONNECT_IVL) +Default value:: 0 (only use XS_RECONNECT_IVL) Applicable socket types:: all, only for connection-oriented transports -ZMQ_BACKLOG: Set maximum length of the queue of outstanding connections +XS_BACKLOG: Set maximum length of the queue of outstanding connections ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_BACKLOG' option shall set the maximum length of the queue of +The 'XS_BACKLOG' option shall set the maximum length of the queue of outstanding peer connections for the specified 'socket'; this only applies to connection-oriented transports. For details refer to your operating system documentation for the 'listen' function. @@ -275,11 +276,11 @@ Default value:: 100 Applicable socket types:: all, only for connection-oriented transports. -ZMQ_MAXMSGSIZE: Maximum acceptable inbound message size +XS_MAXMSGSIZE: Maximum acceptable inbound message size ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Limits the size of the inbound message. If a peer sends a message larger than -ZMQ_MAXMSGSIZE it is disconnected. Value of -1 means 'no limit'. +XS_MAXMSGSIZE it is disconnected. Value of -1 means 'no limit'. [horizontal] Option value type:: int64_t @@ -288,7 +289,7 @@ Default value:: -1 Applicable socket types:: all -ZMQ_MULTICAST_HOPS: Maximum network hops for multicast packets +XS_MULTICAST_HOPS: Maximum network hops for multicast packets ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Sets the time-to-live field in every multicast packet sent from this socket. @@ -302,11 +303,11 @@ Default value:: 1 Applicable socket types:: all, when using multicast transports -ZMQ_RCVTIMEO: Maximum time before a recv operation returns with EAGAIN +XS_RCVTIMEO: Maximum time before a recv operation returns with EAGAIN ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Sets the timeout for receive operation on the socket. If the value is `0`, -_zmq_recv(3)_ will return immediately, with a EAGAIN error if there is no +_xs_recv(3)_ will return immediately, with a EAGAIN error if there is no message to receive. If the value is `-1`, it will block until a message is available. For all other values, it will wait for a message for that amount of time before returning with an EAGAIN error. @@ -318,11 +319,11 @@ Default value:: -1 (infinite) Applicable socket types:: all -ZMQ_SNDTIMEO: Maximum time before a send operation returns with EAGAIN +XS_SNDTIMEO: Maximum time before a send operation returns with EAGAIN ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Sets the timeout for send operation on the socket. If the value is `0`, -_zmq_send(3)_ will return immediately, with a EAGAIN error if the message +_xs_send(3)_ will return immediately, with a EAGAIN error if the message cannot be sent. If the value is `-1`, it will block until the message is sent. For all other values, it will try to send the message for that amount of time before returning with an EAGAIN error. @@ -334,7 +335,7 @@ Default value:: -1 (infinite) Applicable socket types:: all -ZMQ_IPV4ONLY: Use IPv4-only sockets +XS_IPV4ONLY: Use IPv4-only sockets ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Sets the underlying native socket type. A value of `1` will use IPv4 sockets, @@ -350,7 +351,7 @@ Applicable socket types:: all, when using TCP transports. RETURN VALUE ------------ -The _zmq_setsockopt()_ function shall return zero if successful. Otherwise it +The _xs_setsockopt()_ function shall return zero if successful. Otherwise it shall return `-1` and set 'errno' to one of the values defined below. @@ -360,7 +361,7 @@ ERRORS The requested option _option_name_ is unknown, or the requested _option_len_ or _option_value_ is invalid. *ETERM*:: -The 0MQ 'context' associated with the specified 'socket' was terminated. +The 'context' associated with the specified 'socket' was terminated. *ENOTSOCK*:: The provided 'socket' was invalid. *EINTR*:: @@ -369,13 +370,13 @@ The operation was interrupted by delivery of a signal. EXAMPLE ------- -.Subscribing to messages on a 'ZMQ_SUB' socket +.Subscribing to messages on a 'XS_SUB' socket ---- /* Subscribe to all messages */ -rc = zmq_setsockopt (socket, ZMQ_SUBSCRIBE, "", 0); +rc = xs_setsockopt (socket, XS_SUBSCRIBE, "", 0); assert (rc == 0); /* Subscribe to messages prefixed with "ANIMALS.CATS" */ -rc = zmq_setsockopt (socket, ZMQ_SUBSCRIBE, "ANIMALS.CATS", 12); +rc = xs_setsockopt (socket, XS_SUBSCRIBE, "ANIMALS.CATS", 12); ---- .Setting I/O thread affinity @@ -383,27 +384,27 @@ rc = zmq_setsockopt (socket, ZMQ_SUBSCRIBE, "ANIMALS.CATS", 12); int64_t affinity; /* Incoming connections on TCP port 5555 shall be handled by I/O thread 1 */ affinity = 1; -rc = zmq_setsockopt (socket, ZMQ_AFFINITY, &affinity, sizeof affinity); +rc = xs_setsockopt (socket, XS_AFFINITY, &affinity, sizeof affinity); assert (rc); -rc = zmq_bind (socket, "tcp://lo:5555"); +rc = xs_bind (socket, "tcp://lo:5555"); assert (rc); /* Incoming connections on TCP port 5556 shall be handled by I/O thread 2 */ affinity = 2; -rc = zmq_setsockopt (socket, ZMQ_AFFINITY, &affinity, sizeof affinity); +rc = xs_setsockopt (socket, XS_AFFINITY, &affinity, sizeof affinity); assert (rc); -rc = zmq_bind (socket, "tcp://lo:5556"); +rc = xs_bind (socket, "tcp://lo:5556"); assert (rc); ---- SEE ALSO -------- -linkzmq:zmq_getsockopt[3] -linkzmq:zmq_socket[3] -linkzmq:zmq[7] +linkxs:xs_getsockopt[3] +linkxs:xs_socket[3] +linkxs:xs[7] AUTHORS ------- -The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and -Martin Lucina <martin@lucina.net>. +The Crossroads documentation was written by Martin Sustrik <sustrik@250bpm.com> +and Martin Lucina <martin@lucina.net>. diff --git a/doc/zmq_socket.txt b/doc/xs_socket.txt index 39ddebf..217850f 100644 --- a/doc/zmq_socket.txt +++ b/doc/xs_socket.txt @@ -1,63 +1,63 @@ -zmq_socket(3) -============= +xs_socket(3) +============ NAME ---- -zmq_socket - create 0MQ socket +xs_socket - create Crossroads socket SYNOPSIS -------- -*void *zmq_socket (void '*context', int 'type');* +*void *xs_socket (void '*context', int 'type');* DESCRIPTION ----------- -The 'zmq_socket()' function shall create a 0MQ socket within the specified +The 'xs_socket()' function shall create a Crossroads socket within the specified 'context' and return an opaque handle to the newly created socket. The 'type' argument specifies the socket type, which determines the semantics of communication over the socket. The newly created socket is initially unbound, and not associated with any endpoints. In order to establish a message flow a socket must first be -connected to at least one endpoint with linkzmq:zmq_connect[3], or at least one +connected to at least one endpoint with linkxs:xs_connect[3], or at least one endpoint must be created for accepting incoming connections with -linkzmq:zmq_bind[3]. +linkxs:xs_bind[3]. .Key differences to conventional sockets Generally speaking, conventional sockets present a _synchronous_ interface to either connection-oriented reliable byte streams (SOCK_STREAM), or -connection-less unreliable datagrams (SOCK_DGRAM). In comparison, 0MQ sockets -present an abstraction of an asynchronous _message queue_, with the exact -queueing semantics depending on the socket type in use. Where conventional -sockets transfer streams of bytes or discrete datagrams, 0MQ sockets transfer -discrete _messages_. +connection-less unreliable datagrams (SOCK_DGRAM). In comparison, Crossroads +sockets present an abstraction of an asynchronous _message queue_, with the +exact queueing semantics depending on the socket type in use. Where conventional +sockets transfer streams of bytes or discrete datagrams, Crossroads sockets +transfer discrete _messages_. -0MQ sockets being _asynchronous_ means that the timings of the physical +Crossroads sockets being _asynchronous_ means that the timings of the physical connection setup and tear down, reconnect and effective delivery are transparent -to the user and organized by 0MQ itself. Further, messages may be _queued_ in -the event that a peer is unavailable to receive them. +to the user and organized by Crossroads library itself. Further, messages may +be _queued_ in the event that a peer is unavailable to receive them. Conventional sockets allow only strict one-to-one (two peers), many-to-one (many clients, one server), or in some cases one-to-many (multicast) -relationships. With the exception of 'ZMQ_PAIR', 0MQ sockets may be connected -*to multiple endpoints* using _zmq_connect()_, while simultaneously accepting -incoming connections *from multiple endpoints* bound to the socket using -_zmq_bind()_, thus allowing many-to-many relationships. +relationships. With the exception of 'XS_PAIR', Crossroads sockets may be +connected *to multiple endpoints* using _xs_connect()_, while simultaneously +accepting incoming connections *from multiple endpoints* bound to the socket +using _xs_bind()_, thus allowing many-to-many relationships. .Thread safety -0MQ 'sockets' are _not_ thread safe. Applications MUST NOT use a socket +Crossroads 'sockets' are _not_ thread safe. Applications MUST NOT use a socket from multiple threads except after migrating a socket from one thread to another with a "full fence" memory barrier. .Socket types -0MQ defines several messaging patterns which encapsulate exact semantics of -a particular topology. For example, publush-subscribe pattern defines data +Crossroads defines several messaging patterns which encapsulate exact semantics +of a particular topology. For example, publush-subscribe pattern defines data distribution trees while request-reply defines networks of shared stateless services. Each pattern defines several socket types (roles in the pattern). -The following sections present the socket types defined by 0MQ: +The following sections present the socket types defined by Crossroads library: Request-reply pattern @@ -67,97 +67,97 @@ or more instances of a stateless _service_, and receiving subsequent replies to each request sent. -ZMQ_REQ -^^^^^^^ -A socket of type 'ZMQ_REQ' is used by a _client_ to send requests to and +XS_REQ +^^^^^^ +A socket of type 'XS_REQ' is used by a _client_ to send requests to and receive replies from a _service_. This socket type allows only an alternating -sequence of _zmq_send(request)_ and subsequent _zmq_recv(reply)_ calls. Each +sequence of _xs_send(request)_ and subsequent _xs_recv(reply)_ calls. Each request sent is load-balanced among all _services_, and each reply received is matched with the last issued request. -When a 'ZMQ_REQ' socket enters an exceptional state due to having reached the +When a 'XS_REQ' socket enters an exceptional state due to having reached the high water mark for all _services_, or if there are no _services_ at all, then -any linkzmq:zmq_send[3] operations on the socket shall block until the +any linkxs:xs_send[3] operations on the socket shall block until the exceptional state ends or at least one _service_ becomes available for sending; messages are not discarded. [horizontal] -.Summary of ZMQ_REQ characteristics -Compatible peer sockets:: 'ZMQ_REP' +.Summary of XS_REQ characteristics +Compatible peer sockets:: 'XS_REP' Send/receive pattern:: Send, Receive, Send, Receive, ... Outgoing routing strategy:: Load-balanced Incoming routing strategy:: Last peer -ZMQ_HWM option action:: Block +XS_HWM option action:: Block -ZMQ_REP -^^^^^^^ -A socket of type 'ZMQ_REP' is used by a _service_ to receive requests from and +XS_REP +^^^^^^ +A socket of type 'XS_REP' is used by a _service_ to receive requests from and send replies to a _client_. This socket type allows only an alternating -sequence of _zmq_recv(request)_ and subsequent _zmq_send(reply)_ calls. Each +sequence of _xs_recv(request)_ and subsequent _xs_send(reply)_ calls. Each request received is fair-queued from among all _clients_, and each reply sent is routed to the _client_ that issued the last request. If the original requester doesn't exist any more the reply is silently discarded. -When a 'ZMQ_REP' socket enters an exceptional state due to having reached the +When a 'XS_REP' socket enters an exceptional state due to having reached the high water mark for a _client_, then any replies sent to the _client_ in question shall be dropped until the exceptional state ends. [horizontal] -.Summary of ZMQ_REP characteristics -Compatible peer sockets:: 'ZMQ_REQ' +.Summary of XS_REP characteristics +Compatible peer sockets:: 'XS_REQ' Send/receive pattern:: Receive, Send, Receive, Send, ... Incoming routing strategy:: Fair-queued Outgoing routing strategy:: Last peer -ZMQ_HWM option action:: Drop +XS_HWM option action:: Drop -ZMQ_XREQ -^^^^^^^^ -A socket of type 'ZMQ_XREQ' is a socket type underlying 'ZMQ_REQ'. It doesn't -impose the strict order of sends and recvs as 'ZMQ_REQ' does and it is +XS_XREQ +^^^^^^^ +A socket of type 'XS_XREQ' is a socket type underlying 'XS_REQ'. It doesn't +impose the strict order of sends and recvs as 'XS_REQ' does and it is intended for use in intermediate devices in request-reply topologies. Each message sent is load-balanced among all connected peers, and each message received is fair-queued from all connected peers. -When a 'ZMQ_XREQ' socket enters an exceptional state due to having reached the +When a 'XS_XREQ' socket enters an exceptional state due to having reached the high water mark for all peers, or if there are no peers at all, then any -linkzmq:zmq_send[3] operations on the socket shall block until the exceptional +linkxs:xs_send[3] operations on the socket shall block until the exceptional state ends or at least one peer becomes available for sending; messages are not discarded. [horizontal] -.Summary of ZMQ_XREQ characteristics -Compatible peer sockets:: 'ZMQ_XREP', 'ZMQ_REP' +.Summary of XS_XREQ characteristics +Compatible peer sockets:: 'XS_XREP', 'XS_REP' Send/receive pattern:: Unrestricted Outgoing routing strategy:: Load-balanced Incoming routing strategy:: Fair-queued -ZMQ_HWM option action:: Block +XS_HWM option action:: Block -ZMQ_XREP -^^^^^^^^ -A socket of type 'ZMQ_XREP' is a socket type underlying 'ZMQ_REP'. It doesn't -impose the strict order of sends and recvs as 'ZMQ_REQ' does and it is +XS_XREP +^^^^^^^ +A socket of type 'XS_XREP' is a socket type underlying 'XS_REP'. It doesn't +impose the strict order of sends and recvs as 'XS_REQ' does and it is intended for use in intermediate devices in request-reply topologies. Messages received are fair-queued from among all connected peers. The outbound messages are routed to a specific peer, as explained below. -When a 'ZMQ_XREP' socket enters an exceptional state due to having reached the +When a 'XS_XREP' socket enters an exceptional state due to having reached the high water mark for all peers, or if there are no peers at all, then any messages sent to the socket shall be dropped until the exceptional state ends. Likewise, any messages to be routed to a non-existent peer or a peer for which the individual high water mark has been reached shall also be dropped. [horizontal] -.Summary of ZMQ_XREP characteristics -Compatible peer sockets:: 'ZMQ_XREQ', 'ZMQ_REQ' +.Summary of XS_XREP characteristics +Compatible peer sockets:: 'XS_XREQ', 'XS_REQ' Send/receive pattern:: Unrestricted Outgoing routing strategy:: See text Incoming routing strategy:: Fair-queued -ZMQ_HWM option action:: Drop +XS_HWM option action:: Drop Publish-subscribe pattern @@ -166,72 +166,72 @@ The publish-subscribe pattern is used for one-to-many distribution of data from a single _publisher_ to multiple _subscribers_ in a fan out fashion. -ZMQ_PUB -^^^^^^^ -A socket of type 'ZMQ_PUB' is used by a _publisher_ to distribute data. +XS_PUB +^^^^^^ +A socket of type 'XS_PUB' is used by a _publisher_ to distribute data. Messages sent are distributed in a fan out fashion to all connected peers. -The linkzmq:zmq_recv[3] function is not implemented for this socket type. +The linkxs:xs_recv[3] function is not implemented for this socket type. -When a 'ZMQ_PUB' socket enters an exceptional state due to having reached the +When a 'XS_PUB' socket enters an exceptional state due to having reached the high water mark for a _subscriber_, then any messages that would be sent to the _subscriber_ in question shall instead be dropped until the exceptional state -ends. The _zmq_send()_ function shall never block for this socket type. +ends. The _xs_send()_ function shall never block for this socket type. [horizontal] -.Summary of ZMQ_PUB characteristics -Compatible peer sockets:: 'ZMQ_SUB', 'ZMQ_XSUB' +.Summary of XS_PUB characteristics +Compatible peer sockets:: 'XS_SUB', 'XS_XSUB' Send/receive pattern:: Send only Incoming routing strategy:: N/A Outgoing routing strategy:: Fan out -ZMQ_HWM option action:: Drop +XS_HWM option action:: Drop -ZMQ_SUB -^^^^^^^ -A socket of type 'ZMQ_SUB' is used by a _subscriber_ to subscribe to data -distributed by a _publisher_. Initially a 'ZMQ_SUB' socket is not subscribed to -any messages, use the 'ZMQ_SUBSCRIBE' option of linkzmq:zmq_setsockopt[3] to -specify which messages to subscribe to. The _zmq_send()_ function is not +XS_SUB +^^^^^^ +A socket of type 'XS_SUB' is used by a _subscriber_ to subscribe to data +distributed by a _publisher_. Initially a 'XS_SUB' socket is not subscribed to +any messages, use the 'XS_SUBSCRIBE' option of linkxs:xs_setsockopt[3] to +specify which messages to subscribe to. The _xs_send()_ function is not implemented for this socket type. [horizontal] -.Summary of ZMQ_SUB characteristics -Compatible peer sockets:: 'ZMQ_PUB', 'ZMQ_XPUB' +.Summary of XS_SUB characteristics +Compatible peer sockets:: 'XS_PUB', 'XS_XPUB' Send/receive pattern:: Receive only Incoming routing strategy:: Fair-queued Outgoing routing strategy:: N/A -ZMQ_HWM option action:: Drop +XS_HWM option action:: Drop -ZMQ_XPUB -^^^^^^^^ -Same as ZMQ_PUB except that you can receive subscriptions from the peers +XS_XPUB +^^^^^^^ +Same as XS_PUB except that you can receive subscriptions from the peers in form of incoming messages. Subscription message is a byte 1 (for subscriptions) or byte 0 (for unsubscriptions) followed by the subscription body. [horizontal] -.Summary of ZMQ_XPUB characteristics -Compatible peer sockets:: 'ZMQ_SUB', 'ZMQ_XSUB' +.Summary of XS_XPUB characteristics +Compatible peer sockets:: 'XS_SUB', 'XS_XSUB' Send/receive pattern:: Send messages, receive subscriptions Incoming routing strategy:: N/A Outgoing routing strategy:: Fan out -ZMQ_HWM option action:: Drop +XS_HWM option action:: Drop -ZMQ_XSUB -^^^^^^^^ -Same as ZMQ_SUB except that you subscribe by sending subscription messages to +XS_XSUB +^^^^^^^ +Same as XS_SUB except that you subscribe by sending subscription messages to the socket. Subscription message is a byte 1 (for subscriptions) or byte 0 (for unsubscriptions) followed by the subscription body. [horizontal] -.Summary of ZMQ_XSUB characteristics -Compatible peer sockets:: 'ZMQ_PUB', 'ZMQ_XPUB' +.Summary of XS_XSUB characteristics +Compatible peer sockets:: 'XS_PUB', 'XS_XPUB' Send/receive pattern:: Receive messages, send subscriptions Incoming routing strategy:: Fair-queued Outgoing routing strategy:: N/A -ZMQ_HWM option action:: Drop +XS_HWM option action:: Drop Pipeline pattern @@ -242,44 +242,44 @@ is connected to at least one _node_. When a pipeline stage is connected to multiple _nodes_ data is load-balanced among all connected _nodes_. -ZMQ_PUSH -^^^^^^^^ -A socket of type 'ZMQ_PUSH' is used by a pipeline _node_ to send messages +XS_PUSH +^^^^^^^ +A socket of type 'XS_PUSH' is used by a pipeline _node_ to send messages to downstream pipeline _nodes_. Messages are load-balanced to all connected -downstream _nodes_. The _zmq_recv()_ function is not implemented for this +downstream _nodes_. The _xs_recv()_ function is not implemented for this socket type. -When a 'ZMQ_PUSH' socket enters an exceptional state due to having reached the +When a 'XS_PUSH' socket enters an exceptional state due to having reached the high water mark for all downstream _nodes_, or if there are no downstream -_nodes_ at all, then any linkzmq:zmq_send[3] operations on the socket shall +_nodes_ at all, then any linkxs:xs_send[3] operations on the socket shall block until the exceptional state ends or at least one downstream _node_ becomes available for sending; messages are not discarded. [horizontal] -.Summary of ZMQ_PUSH characteristics -Compatible peer sockets:: 'ZMQ_PULL' +.Summary of XS_PUSH characteristics +Compatible peer sockets:: 'XS_PULL' Direction:: Unidirectional Send/receive pattern:: Send only Incoming routing strategy:: N/A Outgoing routing strategy:: Load-balanced -ZMQ_HWM option action:: Block +XS_HWM option action:: Block -ZMQ_PULL -^^^^^^^^ -A socket of type 'ZMQ_PULL' is used by a pipeline _node_ to receive messages +XS_PULL +^^^^^^^ +A socket of type 'XS_PULL' is used by a pipeline _node_ to receive messages from upstream pipeline _nodes_. Messages are fair-queued from among all -connected upstream _nodes_. The _zmq_send()_ function is not implemented for +connected upstream _nodes_. The _xs_send()_ function is not implemented for this socket type. [horizontal] -.Summary of ZMQ_PULL characteristics -Compatible peer sockets:: 'ZMQ_PUSH' +.Summary of XS_PULL characteristics +Compatible peer sockets:: 'XS_PUSH' Direction:: Unidirectional Send/receive pattern:: Receive only Incoming routing strategy:: Fair-queued Outgoing routing strategy:: N/A -ZMQ_HWM option action:: N/A +XS_HWM option action:: N/A Exclusive pair pattern @@ -288,33 +288,33 @@ The exclusive pair is an advanced pattern used for communicating exclusively between two peers. -ZMQ_PAIR -^^^^^^^^ -A socket of type 'ZMQ_PAIR' can only be connected to a single peer at any one +XS_PAIR +^^^^^^^ +A socket of type 'XS_PAIR' can only be connected to a single peer at any one time. No message routing or filtering is performed on messages sent over a -'ZMQ_PAIR' socket. +'XS_PAIR' socket. -When a 'ZMQ_PAIR' socket enters an exceptional state due to having reached the +When a 'XS_PAIR' socket enters an exceptional state due to having reached the high water mark for the connected peer, or if no peer is connected, then -any linkzmq:zmq_send[3] operations on the socket shall block until the peer +any linkxs:xs_send[3] operations on the socket shall block until the peer becomes available for sending; messages are not discarded. -NOTE: 'ZMQ_PAIR' sockets are experimental, and are currently missing several +NOTE: 'XS_PAIR' sockets are experimental, and are currently missing several features such as auto-reconnection. [horizontal] -.Summary of ZMQ_PAIR characteristics -Compatible peer sockets:: 'ZMQ_PAIR' +.Summary of XS_PAIR characteristics +Compatible peer sockets:: 'XS_PAIR' Direction:: Bidirectional Send/receive pattern:: Unrestricted Incoming routing strategy:: N/A Outgoing routing strategy:: N/A -ZMQ_HWM option action:: Block +XS_HWM option action:: Block RETURN VALUE ------------ -The _zmq_socket()_ function shall return an opaque handle to the newly created +The _xs_socket()_ function shall return an opaque handle to the newly created socket if successful. Otherwise, it shall return NULL and set 'errno' to one of the values defined below. @@ -326,22 +326,22 @@ The requested socket 'type' is invalid. *EFAULT*:: The provided 'context' is invalid. *EMFILE*:: -The limit on the total number of open 0MQ sockets has been reached. +The limit on the total number of open Crossroads sockets has been reached. *ETERM*:: The context specified was terminated. SEE ALSO -------- -linkzmq:zmq_init[3] -linkzmq:zmq_setsockopt[3] -linkzmq:zmq_bind[3] -linkzmq:zmq_connect[3] -linkzmq:zmq_send[3] -linkzmq:zmq_recv[3] -linkzmq:zmq[7] +linkxs:xs_init[3] +linkxs:xs_setsockopt[3] +linkxs:xs_bind[3] +linkxs:xs_connect[3] +linkxs:xs_send[3] +linkxs:xs_recv[3] +linkxs:xs[7] AUTHORS ------- -The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and -Martin Lucina <martin@lucina.net>. +The Crossroads documentation was written by Martin Sustrik <sustrik@250bpm.com> +and Martin Lucina <martin@lucina.net>. diff --git a/doc/xs_strerror.txt b/doc/xs_strerror.txt new file mode 100644 index 0000000..4fd517e --- /dev/null +++ b/doc/xs_strerror.txt @@ -0,0 +1,55 @@ +xs_strerror(3) +============== + + +NAME +---- +xs_strerror - get error message string + + +SYNOPSIS +-------- +*const char *xs_strerror (int 'errnum');* + + +DESCRIPTION +----------- +The _xs_strerror()_ function shall return a pointer to an error message string +corresponding to the error number specified by the 'errnum' argument. +As Crossroads define additional error numbers over and above those defined +by the operating system, applications should use _xs_strerror()_ in preference +to the standard _strerror()_ function. + + +RETURN VALUE +------------ +The _xs_strerror()_ function shall return a pointer to an error message +string. + + +ERRORS +------ +No errors are defined. + + +EXAMPLE +------- +.Displaying an error message when the context cannot be initialised +---- +void *ctx = xs_init (1, 1, 0); +if (!ctx) { + printf ("Error occurred during xs_init(): %s\n", xs_strerror (errno)); + abort (); +} +---- + + +SEE ALSO +-------- +linkxs:xs[7] + + +AUTHORS +------- +The Crossroads documentation was written by Martin Sustrik <sustrik@250bpm.com> +and Martin Lucina <martin@lucina.net>. diff --git a/doc/zmq_tcp.txt b/doc/xs_tcp.txt index f5499d3..5d5cbca 100644 --- a/doc/zmq_tcp.txt +++ b/doc/xs_tcp.txt @@ -1,22 +1,22 @@ -zmq_tcp(7) -========== +xs_tcp(7) +========= NAME ---- -zmq_tcp - 0MQ unicast transport using TCP +xs_tcp - Crossroads unicast transport using TCP SYNOPSIS -------- TCP is an ubiquitous, reliable, unicast transport. When connecting distributed -applications over a network with 0MQ, using the TCP transport will likely be -your first choice. +applications over a network with Crossroads, using the TCP transport will likely +be your first choice. ADDRESSING ---------- -A 0MQ address string consists of two parts as follows: +A Crossroads address string consists of two parts as follows: 'transport'`://`'endpoint'. The 'transport' part specifies the underlying transport protocol to use, and for the TCP transport shall be set to `tcp`. The meaning of the 'endpoint' part for the TCP transport is defined below. @@ -24,7 +24,7 @@ The meaning of the 'endpoint' part for the TCP transport is defined below. Assigning a local address to a socket ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -When assigning a local address to a socket using _zmq_bind()_ with the 'tcp' +When assigning a local address to a socket using _xs_bind()_ with the 'tcp' transport, the 'endpoint' shall be interpreted as an 'interface' followed by a colon and the TCP port number to use. @@ -42,7 +42,7 @@ names exist, thus only the primary IP address may be used to specify an Connecting a socket ~~~~~~~~~~~~~~~~~~~ -When connecting a socket to a peer address using _zmq_connect()_ with the 'tcp' +When connecting a socket to a peer address using _xs_connect()_ with the 'tcp' transport, the 'endpoint' shall be interpreted as a 'peer address' followed by a colon and the TCP port number to use. @@ -54,7 +54,7 @@ A 'peer address' may be specified by either of the following: WIRE FORMAT ----------- -0MQ messages are transmitted over TCP in frames consisting of an encoded +Crossroads messages are transmitted over TCP in frames consisting of an encoded 'payload length', followed by a 'flags' field and the message body. The 'payload length' is defined as the combined length in octets of the message body and the 'flags' field. @@ -125,38 +125,38 @@ EXAMPLES .Assigning a local address to a socket ---- /* TCP port 5555 on all available interfaces */ -rc = zmq_bind(socket, "tcp://*:5555"); +rc = xs_bind(socket, "tcp://*:5555"); assert (rc == 0); /* TCP port 5555 on the local loop-back interface on all platforms */ -rc = zmq_bind(socket, "tcp://127.0.0.1:5555"); +rc = xs_bind(socket, "tcp://127.0.0.1:5555"); assert (rc == 0); /* TCP port 5555 on the first Ethernet network interface on Linux */ -rc = zmq_bind(socket, "tcp://eth0:5555"); +rc = xs_bind(socket, "tcp://eth0:5555"); assert (rc == 0); ---- .Connecting a socket ---- /* Connecting using an IP address */ -rc = zmq_connect(socket, "tcp://192.168.1.1:5555"); +rc = xs_connect(socket, "tcp://192.168.1.1:5555"); assert (rc == 0); /* Connecting using a DNS name */ -rc = zmq_connect(socket, "tcp://server1:5555"); +rc = xs_connect(socket, "tcp://server1:5555"); assert (rc == 0); ---- SEE ALSO -------- -linkzmq:zmq_bind[3] -linkzmq:zmq_connect[3] -linkzmq:zmq_pgm[7] -linkzmq:zmq_ipc[7] -linkzmq:zmq_inproc[7] -linkzmq:zmq[7] +linkxs:xs_bind[3] +linkxs:xs_connect[3] +linkxs:xs_pgm[7] +linkxs:xs_ipc[7] +linkxs:xs_inproc[7] +linkxs:xs[7] AUTHORS ------- -The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and -Martin Lucina <martin@lucina.net>. +The Crossroads documentation was written by Martin Sustrik <sustrik@250bpm.com> +and Martin Lucina <martin@lucina.net>. diff --git a/doc/xs_term.txt b/doc/xs_term.txt new file mode 100644 index 0000000..a9b75bb --- /dev/null +++ b/doc/xs_term.txt @@ -0,0 +1,65 @@ +xs_term(3) +========== + + +NAME +---- +xs_term - terminate the context + + +SYNOPSIS +-------- +*int xs_term (void '*context');* + + +DESCRIPTION +----------- +The _xs_term()_ function shall terminate the Crossroads 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 _xs_close()_, any further operations on sockets open within + 'context' shall fail with an error code of ETERM. + +2. After interrupting all blocking calls, _xs_term()_ shall _block_ until the + following conditions are satisfied: ++ + * All sockets open within 'context' have been closed with _xs_close()_. + + * For each socket within 'context', all messages sent by the application + with _xs_send()_ have either been physically transferred to a network + peer, or the socket's linger period set with the _XS_LINGER_ socket + option has expired. + +For further details regarding socket linger behaviour refer to the _XS_LINGER_ +option in linkxs:xs_setsockopt[3]. + + +RETURN VALUE +------------ +The _xs_term()_ 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 +-------- +linkxs:xs[7] +linkxs:xs_init[3] +linkxs:xs_close[3] +linkxs:xs_setsockopt[3] + + +AUTHORS +------- +The Crossroads documentation was written by Martin Sustrik <sustrik@250bpm.com> +and Martin Lucina <martin@lucina.net>. diff --git a/doc/xs_version.txt b/doc/xs_version.txt new file mode 100644 index 0000000..c13a080 --- /dev/null +++ b/doc/xs_version.txt @@ -0,0 +1,53 @@ +xs_version(3) +============= + + +NAME +---- +xs_version - report Crossroads library version + + +SYNOPSIS +-------- +*void xs_version (int '*major', int '*minor', int '*patch');* + + +DESCRIPTION +----------- +The _xs_version()_ function shall fill in the integer variables pointed to by +the 'major', 'minor' and 'patch' arguments with the major, minor and patch level +components of the Crossroads library version. + +This functionality is intended for applications or language bindings +dynamically linking to the Crossroads library that wish to determine the actual +version of the Crossroads library they are using. + + +RETURN VALUE +------------ +There is no return value. + + +ERRORS +------ +No errors are defined. + + +EXAMPLE +------- +.Printing out the version of the Crossroads library +---- +int major, minor, patch; +xs_version (&major, &minor, &patch); +printf ("Current Crossroads version is %d.%d.%d\n", major, minor, patch); +---- + + +SEE ALSO +-------- +linkxs:xs[7] + +AUTHORS +------- +The Crossroads documentation was written by Martin Sustrik <sustrik@250bpm.com> +and Martin Lucina <martin@lucina.net>. diff --git a/doc/zmq.txt b/doc/zmq.txt deleted file mode 100644 index 7493ffd..0000000 --- a/doc/zmq.txt +++ /dev/null @@ -1,217 +0,0 @@ -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 the caller must initialise a 0MQ -'context' using _zmq_init()_. The following functions are provided to handle -initialisation and termination of a 'context': - -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] - -Release a message:: - linkzmq:zmq_msg_close[3] - -Access message content:: - linkzmq:zmq_msg_data[3] - linkzmq:zmq_msg_size[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_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] - - -Devices -~~~~~~~ -Apart from the 0MQ library the 0MQ distribution includes 'devices' which are -building blocks intended to serve as intermediate nodes in complex messaging -topologies. - -The following devices are provided: - -Forwarder device for request-response messaging:: - linkzmq:zmq_queue[1] - -Forwarder device for publish-subscribe messaging:: - linkzmq:zmq_forwarder[1] - -Streamer device for parallelized pipeline messaging:: - linkzmq:zmq_streamer[1] - - -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 (Python, Ruby, Java and more) are provided by members -of the 0MQ community and pointers can be found on the 0MQ website. - - -AUTHORS -------- -The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and -Martin Lucina <martin@lucina.net>. - - -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. diff --git a/doc/zmq_close.txt b/doc/zmq_close.txt deleted file mode 100644 index b6dcf0c..0000000 --- a/doc/zmq_close.txt +++ /dev/null @@ -1,52 +0,0 @@ -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 -------- -The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and -Martin Lucina <martin@lucina.net>. diff --git a/doc/zmq_errno.txt b/doc/zmq_errno.txt deleted file mode 100644 index d40dfb4..0000000 --- a/doc/zmq_errno.txt +++ /dev/null @@ -1,50 +0,0 @@ -zmq_errno(3) -============ - - -NAME ----- -zmq_errno - retrieve value of errno for the calling thread - - -SYNOPSIS --------- -*int zmq_errno (void);* - - -DESCRIPTION ------------ -The _zmq_errno()_ function shall retrieve the value of the 'errno' variable for -the calling thread. - -The _zmq_errno()_ function is provided to assist users on non-POSIX systems who -are experiencing issues with retrieving the correct value of 'errno' directly. -Specifically, users on Win32 systems whose application is using a different C -run-time library from the C run-time library in use by 0MQ will need to use -_zmq_errno()_ for correct operation. - -IMPORTANT: Users not experiencing issues with retrieving the correct value of -'errno' should not use this function and should instead access the 'errno' -variable directly. - - -RETURN VALUE ------------- -The _zmq_errno()_ function shall return the value of the 'errno' variable for -the calling thread. - - -ERRORS ------- -No errors are defined. - - -SEE ALSO --------- -linkzmq:zmq[7] - - -AUTHORS -------- -The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and -Martin Lucina <martin@lucina.net>. diff --git a/doc/zmq_msg_close.txt b/doc/zmq_msg_close.txt deleted file mode 100644 index 1754500..0000000 --- a/doc/zmq_msg_close.txt +++ /dev/null @@ -1,55 +0,0 @@ -zmq_msg_close(3) -================ - - -NAME ----- -zmq_msg_close - release 0MQ message - - -SYNOPSIS --------- -*int zmq_msg_close (zmq_msg_t '*msg');* - - -DESCRIPTION ------------ -The _zmq_msg_close()_ function shall inform the 0MQ infrastructure that any -resources associated with the message object referenced by 'msg' are no longer -required and may be released. Actual release of resources associated with the -message object shall be postponed by 0MQ until all users of the message or -underlying data buffer have indicated it is no longer required. - -Applications should ensure that _zmq_msg_close()_ is called once a message is -no longer required, otherwise memory leaks may occur. - -CAUTION: Never access 'zmq_msg_t' members directly, instead always use the -_zmq_msg_ family of functions. - - -RETURN VALUE ------------- -The _zmq_msg_close()_ 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_init[3] -linkzmq:zmq_msg_init_size[3] -linkzmq:zmq_msg_init_data[3] -linkzmq:zmq_msg_data[3] -linkzmq:zmq_msg_size[3] -linkzmq:zmq[7] - - -AUTHORS -------- -The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and -Martin Lucina <martin@lucina.net>. diff --git a/doc/zmq_msg_copy.txt b/doc/zmq_msg_copy.txt deleted file mode 100644 index 56c93c1..0000000 --- a/doc/zmq_msg_copy.txt +++ /dev/null @@ -1,57 +0,0 @@ -zmq_msg_copy(3) -=============== - - -NAME ----- -zmq_msg_copy - copy content of a message to another message - - -SYNOPSIS --------- -*int zmq_msg_copy (zmq_msg_t '*dest', zmq_msg_t '*src');* - - -DESCRIPTION ------------ -The _zmq_msg_copy()_ function shall copy the message object referenced by 'src' -to the message object referenced by 'dest'. The original content of 'dest', if -any, shall be released. - -CAUTION: The implementation may choose not to physically copy the message -content, rather to share the underlying buffer between 'src' and 'dest'. Avoid -modifying message content after a message has been copied with -_zmq_msg_copy()_, doing so can result in undefined behaviour. If what you need -is an actual hard copy, allocate a new message using _zmq_msg_init_size()_ and -copy the message content using _memcpy()_. - -CAUTION: Never access 'zmq_msg_t' members directly, instead always use the -_zmq_msg_ family of functions. - - -RETURN VALUE ------------- -The _zmq_msg_copy()_ 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_move[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 -------- -The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and -Martin Lucina <martin@lucina.net>. diff --git a/doc/zmq_msg_data.txt b/doc/zmq_msg_data.txt deleted file mode 100644 index cf2e2da..0000000 --- a/doc/zmq_msg_data.txt +++ /dev/null @@ -1,48 +0,0 @@ -zmq_msg_data(3) -=============== - - -NAME ----- -zmq_msg_data - retrieve pointer to message content - - -SYNOPSIS --------- -*void *zmq_msg_data (zmq_msg_t '*msg');* - - -DESCRIPTION ------------ -The _zmq_msg_data()_ function shall return a pointer to the message 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_data()_ shall return a pointer to the -message content. - - -ERRORS ------- -No errors are defined. - - -SEE ALSO --------- -linkzmq:zmq_msg_size[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 -------- -The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and -Martin Lucina <martin@lucina.net>. diff --git a/doc/zmq_msg_init.txt b/doc/zmq_msg_init.txt deleted file mode 100644 index a46c759..0000000 --- a/doc/zmq_msg_init.txt +++ /dev/null @@ -1,65 +0,0 @@ -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 -------- -The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and -Martin Lucina <martin@lucina.net>. diff --git a/doc/zmq_msg_init_data.txt b/doc/zmq_msg_init_data.txt deleted file mode 100644 index d38dffb..0000000 --- a/doc/zmq_msg_init_data.txt +++ /dev/null @@ -1,85 +0,0 @@ -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 -------- -The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and -Martin Lucina <martin@lucina.net>. diff --git a/doc/zmq_msg_init_size.txt b/doc/zmq_msg_init_size.txt deleted file mode 100644 index e8412ae..0000000 --- a/doc/zmq_msg_init_size.txt +++ /dev/null @@ -1,58 +0,0 @@ -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 -------- -The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and -Martin Lucina <martin@lucina.net>. diff --git a/doc/zmq_msg_move.txt b/doc/zmq_msg_move.txt deleted file mode 100644 index 4d28b8b..0000000 --- a/doc/zmq_msg_move.txt +++ /dev/null @@ -1,52 +0,0 @@ -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 -------- -The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and -Martin Lucina <martin@lucina.net>. diff --git a/doc/zmq_msg_size.txt b/doc/zmq_msg_size.txt deleted file mode 100644 index 4fb3f10..0000000 --- a/doc/zmq_msg_size.txt +++ /dev/null @@ -1,48 +0,0 @@ -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 -------- -The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and -Martin Lucina <martin@lucina.net>. diff --git a/doc/zmq_poll.txt b/doc/zmq_poll.txt deleted file mode 100644 index ccdbaea..0000000 --- a/doc/zmq_poll.txt +++ /dev/null @@ -1,129 +0,0 @@ -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. - - -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 -------- -The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and -Martin Lucina <martin@lucina.net>. diff --git a/doc/zmq_strerror.txt b/doc/zmq_strerror.txt deleted file mode 100644 index 8cfcccd..0000000 --- a/doc/zmq_strerror.txt +++ /dev/null @@ -1,55 +0,0 @@ -zmq_strerror(3) -=============== - - -NAME ----- -zmq_strerror - get 0MQ error message string - - -SYNOPSIS --------- -*const char *zmq_strerror (int 'errnum');* - - -DESCRIPTION ------------ -The _zmq_strerror()_ function shall return a pointer to an error message string -corresponding to the error number specified by the 'errnum' argument. As 0MQ -defines additional error numbers over and above those defined by the operating -system, applications should use _zmq_strerror()_ in preference to the standard -_strerror()_ function. - - -RETURN VALUE ------------- -The _zmq_strerror()_ function shall return a pointer to an error message -string. - - -ERRORS ------- -No errors are defined. - - -EXAMPLE -------- -.Displaying an error message when a 0MQ context cannot be initialised ----- -void *ctx = zmq_init (1, 1, 0); -if (!ctx) { - printf ("Error occurred during zmq_init(): %s\n", zmq_strerror (errno)); - abort (); -} ----- - - -SEE ALSO --------- -linkzmq:zmq[7] - - -AUTHORS -------- -The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and -Martin Lucina <martin@lucina.net>. diff --git a/doc/zmq_term.txt b/doc/zmq_term.txt deleted file mode 100644 index ba8098d..0000000 --- a/doc/zmq_term.txt +++ /dev/null @@ -1,65 +0,0 @@ -zmq_term(3) -=========== - - -NAME ----- -zmq_term - terminate 0MQ context - - -SYNOPSIS --------- -*int zmq_term (void '*context');* - - -DESCRIPTION ------------ -The _zmq_term()_ function shall terminate 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_term()_ 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 behaviour refer to the _ZMQ_LINGER_ -option in linkzmq:zmq_setsockopt[3]. - - -RETURN VALUE ------------- -The _zmq_term()_ 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 -------- -The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and -Martin Lucina <martin@lucina.net>. diff --git a/doc/zmq_version.txt b/doc/zmq_version.txt deleted file mode 100644 index ef1388e..0000000 --- a/doc/zmq_version.txt +++ /dev/null @@ -1,53 +0,0 @@ -zmq_version(3) -============== - - -NAME ----- -zmq_version - report 0MQ library version - - -SYNOPSIS --------- -*void zmq_version (int '*major', int '*minor', int '*patch');* - - -DESCRIPTION ------------ -The _zmq_version()_ function shall fill in the integer variables pointed to by -the 'major', 'minor' and 'patch' arguments with the major, minor and patch level -components of the 0MQ library version. - -This functionality is intended for applications or language bindings -dynamically linking to the 0MQ library that wish to determine the actual -version of the 0MQ library they are using. - - -RETURN VALUE ------------- -There is no return value. - - -ERRORS ------- -No errors are defined. - - -EXAMPLE -------- -.Printing out the version of the 0MQ library ----- -int major, minor, patch; -zmq_version (&major, &minor, &patch); -printf ("Current 0MQ version is %d.%d.%d\n", major, minor, patch); ----- - - -SEE ALSO --------- -linkzmq:zmq[7] - -AUTHORS -------- -The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and -Martin Lucina <martin@lucina.net>. |