From 4a7aad06d95701cf232198093ce396dcdbb53e5b Mon Sep 17 00:00:00 2001 From: Martin Sustrik Date: Thu, 16 Feb 2012 10:01:47 +0900 Subject: ZeroMQ renamed to Crossroads Signed-off-by: Martin Sustrik --- doc/Makefile.am | 22 +-- doc/asciidoc.conf | 18 +- doc/xs.txt | 187 ++++++++++++++++++++ doc/xs_bind.txt | 93 ++++++++++ doc/xs_close.txt | 52 ++++++ doc/xs_connect.txt | 91 ++++++++++ doc/xs_epgm.txt | 1 + doc/xs_errno.txt | 50 ++++++ doc/xs_getmsgopt.txt | 85 +++++++++ doc/xs_getsockopt.txt | 438 ++++++++++++++++++++++++++++++++++++++++++++++ doc/xs_init.txt | 51 ++++++ doc/xs_inproc.txt | 83 +++++++++ doc/xs_ipc.txt | 80 +++++++++ doc/xs_msg_close.txt | 55 ++++++ doc/xs_msg_copy.txt | 57 ++++++ doc/xs_msg_data.txt | 48 +++++ doc/xs_msg_init.txt | 65 +++++++ doc/xs_msg_init_data.txt | 85 +++++++++ doc/xs_msg_init_size.txt | 58 ++++++ doc/xs_msg_move.txt | 52 ++++++ doc/xs_msg_size.txt | 48 +++++ doc/xs_pgm.txt | 161 +++++++++++++++++ doc/xs_poll.txt | 129 ++++++++++++++ doc/xs_recv.txt | 94 ++++++++++ doc/xs_recvmsg.txt | 121 +++++++++++++ doc/xs_send.txt | 105 +++++++++++ doc/xs_sendmsg.txt | 121 +++++++++++++ doc/xs_setsockopt.txt | 410 +++++++++++++++++++++++++++++++++++++++++++ doc/xs_socket.txt | 347 ++++++++++++++++++++++++++++++++++++ doc/xs_strerror.txt | 55 ++++++ doc/xs_tcp.txt | 162 +++++++++++++++++ doc/xs_term.txt | 65 +++++++ doc/xs_version.txt | 53 ++++++ doc/zmq.txt | 217 ----------------------- doc/zmq_bind.txt | 93 ---------- doc/zmq_close.txt | 52 ------ doc/zmq_connect.txt | 91 ---------- doc/zmq_epgm.txt | 1 - doc/zmq_errno.txt | 50 ------ doc/zmq_getmsgopt.txt | 85 --------- doc/zmq_getsockopt.txt | 438 ---------------------------------------------- doc/zmq_init.txt | 51 ------ doc/zmq_inproc.txt | 89 ---------- doc/zmq_ipc.txt | 80 --------- doc/zmq_msg_close.txt | 55 ------ doc/zmq_msg_copy.txt | 57 ------ doc/zmq_msg_data.txt | 48 ----- doc/zmq_msg_init.txt | 65 ------- doc/zmq_msg_init_data.txt | 85 --------- doc/zmq_msg_init_size.txt | 58 ------ doc/zmq_msg_move.txt | 52 ------ doc/zmq_msg_size.txt | 48 ----- doc/zmq_pgm.txt | 161 ----------------- doc/zmq_poll.txt | 129 -------------- doc/zmq_recv.txt | 94 ---------- doc/zmq_recvmsg.txt | 121 ------------- doc/zmq_send.txt | 105 ----------- doc/zmq_sendmsg.txt | 121 ------------- doc/zmq_setsockopt.txt | 409 ------------------------------------------- doc/zmq_socket.txt | 347 ------------------------------------ doc/zmq_strerror.txt | 55 ------ doc/zmq_tcp.txt | 162 ----------------- doc/zmq_term.txt | 65 ------- doc/zmq_version.txt | 53 ------ 64 files changed, 3520 insertions(+), 3559 deletions(-) create mode 100644 doc/xs.txt create mode 100644 doc/xs_bind.txt create mode 100644 doc/xs_close.txt create mode 100644 doc/xs_connect.txt create mode 120000 doc/xs_epgm.txt create mode 100644 doc/xs_errno.txt create mode 100644 doc/xs_getmsgopt.txt create mode 100644 doc/xs_getsockopt.txt create mode 100644 doc/xs_init.txt create mode 100644 doc/xs_inproc.txt create mode 100644 doc/xs_ipc.txt create mode 100644 doc/xs_msg_close.txt create mode 100644 doc/xs_msg_copy.txt create mode 100644 doc/xs_msg_data.txt create mode 100644 doc/xs_msg_init.txt create mode 100644 doc/xs_msg_init_data.txt create mode 100644 doc/xs_msg_init_size.txt create mode 100644 doc/xs_msg_move.txt create mode 100644 doc/xs_msg_size.txt create mode 100644 doc/xs_pgm.txt create mode 100644 doc/xs_poll.txt create mode 100644 doc/xs_recv.txt create mode 100644 doc/xs_recvmsg.txt create mode 100644 doc/xs_send.txt create mode 100644 doc/xs_sendmsg.txt create mode 100644 doc/xs_setsockopt.txt create mode 100644 doc/xs_socket.txt create mode 100644 doc/xs_strerror.txt create mode 100644 doc/xs_tcp.txt create mode 100644 doc/xs_term.txt create mode 100644 doc/xs_version.txt delete mode 100644 doc/zmq.txt delete mode 100644 doc/zmq_bind.txt delete mode 100644 doc/zmq_close.txt delete mode 100644 doc/zmq_connect.txt delete mode 120000 doc/zmq_epgm.txt delete mode 100644 doc/zmq_errno.txt delete mode 100644 doc/zmq_getmsgopt.txt delete mode 100644 doc/zmq_getsockopt.txt delete mode 100644 doc/zmq_init.txt delete mode 100644 doc/zmq_inproc.txt delete mode 100644 doc/zmq_ipc.txt delete mode 100644 doc/zmq_msg_close.txt delete mode 100644 doc/zmq_msg_copy.txt delete mode 100644 doc/zmq_msg_data.txt delete mode 100644 doc/zmq_msg_init.txt delete mode 100644 doc/zmq_msg_init_data.txt delete mode 100644 doc/zmq_msg_init_size.txt delete mode 100644 doc/zmq_msg_move.txt delete mode 100644 doc/zmq_msg_size.txt delete mode 100644 doc/zmq_pgm.txt delete mode 100644 doc/zmq_poll.txt delete mode 100644 doc/zmq_recv.txt delete mode 100644 doc/zmq_recvmsg.txt delete mode 100644 doc/zmq_send.txt delete mode 100644 doc/zmq_sendmsg.txt delete mode 100644 doc/zmq_setsockopt.txt delete mode 100644 doc/zmq_socket.txt delete mode 100644 doc/zmq_strerror.txt delete mode 100644 doc/zmq_tcp.txt delete mode 100644 doc/zmq_term.txt delete mode 100644 doc/zmq_version.txt (limited to 'doc') 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)[\\]?(?Plinkzmq):(?P\S*?)\[(?P.*?)\]= +(?su)[\\]?(?Plinkxs):(?P\S*?)\[(?P.*?)\]= ifdef::backend-docbook[] -[linkzmq-inlinemacro] +[linkxs-inlinemacro] {0%{target}} {0#} {0#{target}{0}} @@ -13,7 +13,7 @@ ifdef::backend-docbook[] endif::backend-docbook[] ifdef::backend-xhtml11[] -[linkzmq-inlinemacro] +[linkxs-inlinemacro] {target}{0?({0})} endif::backend-xhtml11[] @@ -25,9 +25,9 @@ template::[header-declarations] {mantitle} {manvolnum} -0MQ -{zmq_version} -0MQ Manual +Crossroads +{xs_version} +Crossroads Manual {manname} @@ -42,7 +42,7 @@ ifdef::backend-xhtml11[] {disable-javascript%
} @@ -50,7 +50,3 @@ Last updated {docdate} {doctime} 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 * + +*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 +and Martin Lucina . + +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/xs_bind.txt b/doc/xs_bind.txt new file mode 100644 index 0000000..8cd49bc --- /dev/null +++ b/doc/xs_bind.txt @@ -0,0 +1,93 @@ +xs_bind(3) +========== + + +NAME +---- +xs_bind - accept connections on a socket + + +SYNOPSIS +-------- +*int xs_bind (void '*socket', const char '*endpoint');* + + +DESCRIPTION +----------- +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: +'transport'`://`'address'. The 'transport' part specifies the underlying +transport protocol to use. The meaning of the 'address' part is specific to +the underlying transport protocol selected. + +The following transports are defined: + +'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 '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 +_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 _xs_bind()_ function shall return zero if successful. Otherwise it shall +return `-1` and set 'errno' to one of the values defined below. + + +ERRORS +------ +*EINVAL*:: +The endpoint supplied is invalid. +*EPROTONOSUPPORT*:: +The requested 'transport' protocol is not supported. +*ENOCOMPATPROTO*:: +The requested 'transport' protocol is not compatible with the socket type. +*EADDRINUSE*:: +The requested 'address' is already in use. +*EADDRNOTAVAIL*:: +The requested 'address' was not local. +*ENODEV*:: +The requested 'address' specifies a nonexistent interface. +*ETERM*:: +The 'context' associated with the specified 'socket' was terminated. +*ENOTSOCK*:: +The provided 'socket' was invalid. +*EMTHREAD*:: +No I/O thread is available to accomplish the task. + + +EXAMPLE +------- +.Binding a publisher socket to an in-process and a TCP transport +---- +/* Create a 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 = xs_bind (socket, "inproc://my_publisher"); +assert (rc == 0); +/* Bind it to a TCP transport on port 5555 of the 'eth0' interface */ +rc = xs_bind (socket, "tcp://eth0:5555"); +assert (rc == 0); +---- + + +SEE ALSO +-------- +linkxs:xs_connect[3] +linkxs:xs_socket[3] +linkxs:xs[7] + + +AUTHORS +------- +The Crossroads documentation was written by Martin Sustrik +and Martin Lucina . 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 +and Martin Lucina . diff --git a/doc/xs_connect.txt b/doc/xs_connect.txt new file mode 100644 index 0000000..a0a6ae7 --- /dev/null +++ b/doc/xs_connect.txt @@ -0,0 +1,91 @@ +xs_connect(3) +============= + + +NAME +---- +xs_connect - connect a socket + + +SYNOPSIS +-------- +*int xs_connect (void '*socket', const char '*endpoint');* + + +DESCRIPTION +----------- +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: +'transport'`://`'address'. The 'transport' part specifies the underlying +transport protocol to use. The meaning of the 'address' part is specific to +the underlying transport protocol selected. + +The following transports are defined: + +'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 '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 +_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 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 _xs_connect()_ function shall return zero if successful. Otherwise it +shall return `-1` and set 'errno' to one of the values defined below. + + +ERRORS +------ +*EINVAL*:: +The endpoint supplied is invalid. +*EPROTONOSUPPORT*:: +The requested 'transport' protocol is not supported. +*ENOCOMPATPROTO*:: +The requested 'transport' protocol is not compatible with the socket type. +*ETERM*:: +The 'context' associated with the specified 'socket' was terminated. +*ENOTSOCK*:: +The provided 'socket' was invalid. +*EMTHREAD*:: +No I/O thread is available to accomplish the task. + + +EXAMPLE +------- +.Connecting a subscriber socket to an in-process and a TCP transport +---- +/* Create a 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 = xs_connect (socket, "inproc://my_publisher"); +assert (rc == 0); +/* Connect it to the host server001, port 5555 using a TCP transport */ +rc = xs_connect (socket, "tcp://server001:5555"); +assert (rc == 0); +---- + + +SEE ALSO +-------- +linkxs:xs_bind[3] +linkxs:xs_socket[3] +linkxs:xs[7] + + +AUTHORS +------- +The Crossroads documentation was written by Martin Sustrik +and Martin Lucina . diff --git a/doc/xs_epgm.txt b/doc/xs_epgm.txt new file mode 120000 index 0000000..4d58b1b --- /dev/null +++ b/doc/xs_epgm.txt @@ -0,0 +1 @@ +zmq_pgm.txt \ No newline at end of file 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 +and Martin Lucina . diff --git a/doc/xs_getmsgopt.txt b/doc/xs_getmsgopt.txt new file mode 100644 index 0000000..4b06322 --- /dev/null +++ b/doc/xs_getmsgopt.txt @@ -0,0 +1,85 @@ +xs_getmsgopt(3) +=============== + + +NAME +---- +xs_getmsgopt - retrieve message option + + +SYNOPSIS +-------- +*int xs_getmsgopt (xs_msg_t '*message', int 'option_name', void '*option_value', size_t '*option_len');* + + +DESCRIPTION +----------- +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 _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 _xs_getmsgopt()_ function: + +*XS_MORE*:: +Indicates that there are more message parts to follow after the 'message'. + +RETURN VALUE +------------ +The _xs_getmsgopt()_ function shall return zero if successful. Otherwise it +shall return `-1` and set 'errno' to one of the values defined below. + + +ERRORS +------ +*EINVAL*:: +The requested option _option_name_ is unknown, or the requested _option_size_ or +_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. + + +EXAMPLE +------- +.Receiving a multi-part message +---- +xs_msg_t part; +int more; +size_t more_size = sizeof (more); +while (true) { + /* 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 = xs_recvmsg (socket, &part, 0); + assert (rc != -1); + rc = getmsgopt (&part, XS_MORE, &more, &more_size); + assert (rc == 0); + if (more) { + fprintf (stderr, "more\n"); + } + else { + fprintf (stderr, "end\n"); + break; + } + xs_msg_close (part); +} +---- + + +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 +------- +This manual page was written by Chuck Remes . diff --git a/doc/xs_getsockopt.txt b/doc/xs_getsockopt.txt new file mode 100644 index 0000000..e7ddb8e --- /dev/null +++ b/doc/xs_getsockopt.txt @@ -0,0 +1,438 @@ +xs_getsockopt(3) +================ + + +NAME +---- + +xs_getsockopt - get Crossroads socket option + + +SYNOPSIS +-------- +*int xs_getsockopt (void '*socket', int 'option_name', void '*option_value', size_t '*option_len');* + + +DESCRIPTION +----------- +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 _xs_getsockopt()_ function: + + +XS_TYPE: Retrieve socket type +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +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. + +[horizontal] +Option value type:: int +Option value unit:: N/A +Default value:: N/A +Applicable socket types:: all + + +XS_RCVMORE: More message data parts to follow +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +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 linkxs:xs_send[3] and linkxs:xs_recv[3] for a detailed description +of multi-part messages. + +[horizontal] +Option value type:: int +Option value unit:: boolean +Default value:: N/A +Applicable socket types:: all + + +XS_SNDHWM: Retrieves 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 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, the library shall take appropriate action such as +blocking or dropping sent messages. Refer to the individual socket descriptions +in linkxs:xs_socket[3] for details on the exact action taken for each socket +type. + +[horizontal] +Option value type:: int +Option value unit:: messages +Default value:: 1000 +Applicable socket types:: all + + +XS_RCVHWM: Retrieve high water mark for inbound messages +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +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 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, the library shall take appropriate action such as +blocking or dropping sent messages. Refer to the individual socket descriptions +in linkxs:xs_socket[3] for details on the exact action taken for each socket +type. + +[horizontal] +Option value type:: int +Option value unit:: messages +Default value:: 1000 +Applicable socket types:: all + + +XS_AFFINITY: Retrieve I/O thread affinity +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +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 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 linkxs:xs_init[3] for details on allocating the number of I/O +threads for a specific _context_. + +[horizontal] +Option value type:: uint64_t +Option value unit:: N/A (bitmap) +Default value:: 0 +Applicable socket types:: N/A + +XS_IDENTITY: Set socket identity +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +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 Crossroads infrastructure. + +[horizontal] +Option value type:: binary data +Option value unit:: N/A +Default value:: NULL +Applicable socket types:: all + + +XS_RATE: Retrieve multicast data rate +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'XS_RATE' option shall retrieve the maximum send or receive data rate for +multicast transports using the specified 'socket'. + +[horizontal] +Option value type:: int +Option value unit:: kilobits per second +Default value:: 100 +Applicable socket types:: all, when using multicast transports + + +XS_RECOVERY_IVL: Get multicast recovery interval +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +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. + +[horizontal] +Option value type:: int +Option value unit:: milliseconds +Default value:: 10000 +Applicable socket types:: all, when using multicast transports + + +XS_SNDBUF: Retrieve kernel transmit buffer size +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +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. + +[horizontal] +Option value type:: int +Option value unit:: bytes +Default value:: 0 +Applicable socket types:: all + + +XS_RCVBUF: Retrieve kernel receive buffer size +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +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. + +[horizontal] +Option value type:: int +Option value unit:: bytes +Default value:: 0 +Applicable socket types:: all + + +XS_LINGER: Retrieve linger period for socket shutdown +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +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 +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 _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 _xs_close()_. + +* Positive values specify an upper bound for the linger period in milliseconds. + 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. + +[horizontal] +Option value type:: int +Option value unit:: milliseconds +Default value:: -1 (infinite) +Applicable socket types:: all + + +XS_RECONNECT_IVL: Retrieve reconnection interval +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +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 the library to prevent +reconnection storms in topologies with a large number of peers per socket. + +[horizontal] +Option value type:: int +Option value unit:: milliseconds +Default value:: 100 +Applicable socket types:: all, only for connection-oriented transports + + +XS_RECONNECT_IVL_MAX: Retrieve maximum reconnection interval +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +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 XS_RECONNECT_IVL will be ignored. + +[horizontal] +Option value type:: int +Option value unit:: milliseconds +Default value:: 0 (only use XS_RECONNECT_IVL) +Applicable socket types:: all, only for connection-oriented transport + + +XS_BACKLOG: Retrieve maximum length of the queue of outstanding connections +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +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. + +[horizontal] +Option value type:: int +Option value unit:: connections +Default value:: 100 +Applicable socket types:: all, only for connection-oriented transports + + +XS_MAXMSGSIZE: Maximum acceptable inbound message size +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The option shall retrieve limit for the inbound messages. If a peer sends +a message larger than XS_MAXMSGSIZE it is disconnected. Value of -1 means +'no limit'. + +[horizontal] +Option value type:: int64_t +Option value unit:: bytes +Default value:: -1 +Applicable socket types:: all + + +XS_MULTICAST_HOPS: Maximum network hops for multicast packets +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The option shall retrieve time-to-live used for outbound multicast packets. +The default of 1 means that the multicast packets don't leave the local network. + +[horizontal] +Option value type:: int +Option value unit:: network hops +Default value:: 1 +Applicable socket types:: all, when using multicast transports + + +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`, +_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. + +[horizontal] +Option value type:: int +Option value unit:: milliseconds +Default value:: -1 (infinite) +Applicable socket types:: all + + +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`, +_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. + +[horizontal] +Option value type:: int +Option value unit:: milliseconds +Default value:: -1 (infinite) +Applicable socket types:: all + + +XS_IPV4ONLY: Retrieve IPv4-only socket override status +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Retrieve the underlying native socket type. A value of `1` will use IPv4 +sockets, while the value of `0` will use IPv6 sockets. An IPv6 socket +lets applications connect to and accept connections from both IPv4 and IPv6 +hosts. + +[horizontal] +Option value type:: int +Option value unit:: boolean +Default value:: 1 (true) +Applicable socket types:: all, when using TCP transports. + + +XS_FD: Retrieve file descriptor associated with the socket +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +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 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 '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 +to it directly, neither should they try to close it. + +[horizontal] +Option value type:: int on POSIX systems, SOCKET on Windows +Option value unit:: N/A +Default value:: N/A +Applicable socket types:: all + + +XS_EVENTS: Retrieve socket event state +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +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: + +*XS_POLLIN*:: +Indicates that at least one message may be received from the specified socket +without blocking. + +*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 'XS_FD' option being +ready for reading but no actual events returned by a subsequent retrieval of +the 'XS_EVENTS' option is valid; applications should simply ignore this case +and restart their polling operation/event loop. + +[horizontal] +Option value type:: int +Option value unit:: N/A (flags) +Default value:: N/A +Applicable socket types:: all + + +RETURN VALUE +------------ +The _xs_getsockopt()_ function shall return zero if successful. Otherwise it +shall return `-1` and set 'errno' to one of the values defined below. + + +ERRORS +------ +*EINVAL*:: +The requested option _option_name_ is unknown, or the requested _option_len_ or +_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 'context' associated with the specified 'socket' was terminated. +*ENOTSOCK*:: +The provided 'socket' was invalid. +*EINTR*:: +The operation was interrupted by delivery of a signal. + + +EXAMPLE +------- +.Retrieving the high water mark for outgoing messages +---- +/* Retrieve high water mark into sndhwm */ +int sndhwm; +size_t sndhwm_size = sizeof (sndhwm); +rc = xs_getsockopt (socket, XS_SNDHWM, &sndhwm, &sndhwm_size); +assert (rc == 0); +---- + + +SEE ALSO +-------- +linkxs:xs_setsockopt[3] +linkxs:xs_socket[3] +linkxs:xs[7] + + +AUTHORS +------- +The Crossroads documentation was written by Martin Sustrik +and Martin Lucina . diff --git a/doc/xs_init.txt b/doc/xs_init.txt new file mode 100644 index 0000000..e642824 --- /dev/null +++ b/doc/xs_init.txt @@ -0,0 +1,51 @@ +xs_init(3) +========== + + +NAME +---- +xs_init - initialise Crossroads context + + +SYNOPSIS +-------- +*void *xs_init (int 'io_threads');* + + +DESCRIPTION +----------- +The _xs_init()_ function initialises a Crossroads 'context'. + +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 '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 _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. + + +ERRORS +------ +*EINVAL*:: +An invalid number of 'io_threads' was requested. + + +SEE ALSO +-------- +linkxs:xs[7] +linkxs:xs_term[3] + + +AUTHORS +------- +The Crossroads documentation was written by Martin Sustrik +and Martin Lucina . diff --git a/doc/xs_inproc.txt b/doc/xs_inproc.txt new file mode 100644 index 0000000..9ec255f --- /dev/null +++ b/doc/xs_inproc.txt @@ -0,0 +1,83 @@ +xs_inproc(7) +============ + + +NAME +---- +xs_inproc - local in-process (inter-thread) transport + + +SYNOPSIS +-------- +The in-process transport passes messages via memory directly between threads +sharing a single 'context'. + +ADDRESSING +---------- +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 +defined below. + + +Assigning a local address to a socket +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +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 +'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 _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 'context' +as the 'socket' being connected. + + +WIRE FORMAT +----------- +Not applicable. + + +EXAMPLES +-------- +.Assigning a local address to a socket +---- +/* Assign the in-process name "#1" */ +rc = xs_bind(socket, "inproc://#1"); +assert (rc == 0); +/* Assign the in-process name "my-endpoint" */ +rc = xs_bind(socket, "inproc://my-endpoint"); +assert (rc == 0); +---- + +.Connecting a socket +---- +/* Connect to the in-process name "#1" */ +rc = xs_connect(socket, "inproc://#1"); +assert (rc == 0); +/* Connect to the in-process name "my-endpoint" */ +rc = xs_connect(socket, "inproc://my-endpoint"); +assert (rc == 0); +---- + + +SEE ALSO +-------- +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 Crossroads documentation was written by Martin Sustrik +and Martin Lucina . diff --git a/doc/xs_ipc.txt b/doc/xs_ipc.txt new file mode 100644 index 0000000..f3c5147 --- /dev/null +++ b/doc/xs_ipc.txt @@ -0,0 +1,80 @@ +xs_ipc(7) +========= + + +NAME +---- +xs_ipc - local inter-process transport + + +SYNOPSIS +-------- +The inter-process transport passes messages between local processes using a +system-dependent IPC mechanism. + +NOTE: The inter-process transport is currently only implemented on operating +systems that provide UNIX domain sockets. + + +ADDRESSING +---------- +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 +defined below. + + +Assigning a local address to a socket +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +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 +any restrictions placed by the operating system on the format and length of a +'pathname'. + +Connecting a socket +~~~~~~~~~~~~~~~~~~~ +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 _xs_bind()_. + + +WIRE FORMAT +----------- +Not applicable. + + +EXAMPLES +-------- +.Assigning a local address to a socket +---- +/* Assign the pathname "/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 = xs_connect(socket, "ipc:///tmp/feeds/0"); +assert (rc == 0); +---- + +SEE ALSO +-------- +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 Crossroads documentation was written by Martin Sustrik +and Martin Lucina . 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 +and Martin Lucina . 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 +and Martin Lucina . 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 +and Martin Lucina . 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 +and Martin Lucina . 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 +and Martin Lucina . 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 +and Martin Lucina . 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 +and Martin Lucina . 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 +and Martin Lucina . diff --git a/doc/xs_pgm.txt b/doc/xs_pgm.txt new file mode 100644 index 0000000..fcce19a --- /dev/null +++ b/doc/xs_pgm.txt @@ -0,0 +1,161 @@ +xs_pgm(7) +========= + + +NAME +---- +xs_pgm - reliable multicast transport via PGM protocol + + +SYNOPSIS +-------- +PGM (Pragmatic General Multicast) is a protocol for reliable multicast +transport of data over IP networks. + + +DESCRIPTION +----------- +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 'XS_PUB' and +'XS_SUB' socket types. + +Further, PGM sockets are rate limited by default. For details, refer to the +'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 +operation. Applications not requiring direct interoperability with other PGM +implementations are encouraged to use the 'epgm' transport instead which does +not require any special privileges. + + +ADDRESSING +---------- +A 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 +`epgm`. The meaning of the 'endpoint' part for both the 'pgm' and 'epgm' +transport is defined below. + + +Connecting a socket +~~~~~~~~~~~~~~~~~~~ +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. + +An 'interface' may be specified by either of the following: + +* The interface name as defined by the operating system. +* The primary IPv4 address assigned to the interface, in it's numeric + representation. + +NOTE: Interface names are not standardised in any way and should be assumed to +be arbitrary and platform dependent. On Win32 platforms no short interface +names exist, thus only the primary IPv4 address may be used to specify an +'interface'. + +A 'multicast address' is specified by an IPv4 multicast address in it's numeric +representation. + + +WIRE FORMAT +----------- +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 Crossroads: + +.... +datagram = (offset data) +offset = 2OCTET +data = *OCTET +.... + +In order for late joining consumers to be able to identify message boundaries, +each PGM datagram payload starts with a 16-bit unsigned integer in network byte +order specifying either the offset of the first message 'frame' in the datagram +or containing the value `0xFFFF` if the datagram contains solely an +intermediate part of a larger message. + +Note that offset specifies where the first message begins rather than the first +message part. Thus, if there are trailing message parts at the beginning of +the packet the offset ignores them and points to first initial message part +in the packet. + +The following diagram illustrates the layout of a single PGM datagram payload: + +.... ++------------------+----------------------+ +| offset (16 bits) | data | ++------------------+----------------------+ +.... + +The following diagram further illustrates how three example Crossroads frames +are laid out in consecutive PGM datagram payloads: + +.... +First datagram payload ++--------------+-------------+---------------------+ +| Frame offset | Frame 1 | Frame 2, part 1 | +| 0x0000 | (Message 1) | (Message 2, part 1) | ++--------------+-------------+---------------------+ + +Second datagram payload ++--------------+---------------------+ +| Frame offset | Frame 2, part 2 | +| 0xFFFF | (Message 2, part 2) | ++--------------+---------------------+ + +Third datagram payload ++--------------+----------------------------+-------------+ +| Frame offset | Frame 2, final 8 bytes | Frame 3 | +| 0x0008 | (Message 2, final 8 bytes) | (Message 3) | ++--------------+----------------------------+-------------+ +.... + + +EXAMPLE +------- +.Connecting a socket +---- +/* Connecting to the multicast address 239.192.1.1, port 5555, */ +/* using the first Ethernet network interface on Linux */ +/* and the Encapsulated PGM protocol */ +rc = 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 = xs_connect(socket, "pgm://192.168.1.1;239.192.1.1:5555"); +assert (rc == 0); +---- + + +SEE ALSO +-------- +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 Crossroads documentation was written by Martin Sustrik +and Martin Lucina . 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 +and Martin Lucina . diff --git a/doc/xs_recv.txt b/doc/xs_recv.txt new file mode 100644 index 0000000..26a6c54 --- /dev/null +++ b/doc/xs_recv.txt @@ -0,0 +1,94 @@ +xs_recv(3) +========== + + +NAME +---- +xs_recv - receive a message part from a socket + + +SYNOPSIS +-------- +*int xs_recv (void '*socket', void '*buf', size_t 'len', int 'flags');* + + +DESCRIPTION +----------- +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 _xs_recv()_ function shall block until the request can be satisfied. +The 'flags' argument is a combination of the flags defined below: + +*XS_DONTWAIT*:: +Specifies that the operation should be performed in non-blocking mode. If there +are no messages available on the specified 'socket', the _xs_recv()_ +function shall fail with 'errno' set to EAGAIN. + + +Multi-part messages +~~~~~~~~~~~~~~~~~~~ +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 _XS_RCVMORE_ +linkxs:xs_getsockopt[3] option after calling _xs_recv()_ to determine if +there are further parts to receive. + +RETURN VALUE +------------ +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. + + +ERRORS +------ +*EAGAIN*:: +Non-blocking mode was requested and no messages are available at the moment. +*ENOTSUP*:: +The _xs_recv()_ operation is not supported by this socket type. +*EFSM*:: +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 XS_REP. See the +_messaging patterns_ section of linkxs:xs_socket[3] for more information. +*ETERM*:: +The 'context' associated with the specified 'socket' was terminated. +*ENOTSOCK*:: +The provided 'socket' was invalid. +*EINTR*:: +The operation was interrupted by delivery of a signal before a message was +available. + + +EXAMPLE +------- +.Receiving a message from a socket +---- +char buf [256]; +nbytes = xs_recv (socket, buf, 256, 0); +assert (nbytes != -1); +---- + + +SEE ALSO +-------- +linkxs:xs_recvmsg[3] +linkxs:xs_send[3] +linkxs:xs_sendmsg[3] +linkxs:xs_getsockopt[3] +linkxs:xs_socket[7] +linkxs:xs[7] + + +AUTHORS +------- ++This man page was written by Martin Sustrik , Martin ++Lucina and Pieter Hintjens . + diff --git a/doc/xs_recvmsg.txt b/doc/xs_recvmsg.txt new file mode 100644 index 0000000..735fed0 --- /dev/null +++ b/doc/xs_recvmsg.txt @@ -0,0 +1,121 @@ +xs_recvmsg(3) +============= + + +NAME +---- +xs_recvmsg - receive a message part from a socket + + +SYNOPSIS +-------- +*int xs_recvmsg (void '*socket', xs_msg_t '*msg', int 'flags');* + + +DESCRIPTION +----------- +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 _xs_recvmsg()_ function shall block until the request can be satisfied. +The 'flags' argument is a combination of the flags defined below: + +*XS_DONTWAIT*:: +Specifies that the operation should be performed in non-blocking mode. If there +are no messages available on the specified 'socket', the _xs_recvmsg()_ +function shall fail with 'errno' set to EAGAIN. + + +Multi-part messages +~~~~~~~~~~~~~~~~~~~ +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 _XS_RCVMORE_ +linkxs:xs_getsockopt[3] option after calling _xs_recvmsg()_ to determine if +there are further parts to receive. + + +RETURN VALUE +------------ +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. + + +ERRORS +------ +*EAGAIN*:: +Non-blocking mode was requested and no messages are available at the moment. +*ENOTSUP*:: +The _xs_recvmsg()_ operation is not supported by this socket type. +*EFSM*:: +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 XS_REP. See the +_messaging patterns_ section of linkxs:xs_socket[3] for more information. +*ETERM*:: +The 'context' associated with the specified 'socket' was terminated. +*ENOTSOCK*:: +The provided 'socket' was invalid. +*EINTR*:: +The operation was interrupted by delivery of a signal before a message was +available. +*EFAULT*:: +The message passed to the function was invalid. + + +EXAMPLE +------- +.Receiving a message from a socket +---- +/* Create an empty 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 = xs_recvmsg (socket, &msg, 0); +assert (rc != -1); +/* Release message */ +xs_msg_close (&msg); +---- + +.Receiving a multi-part message +---- +int64_t more; +size_t more_size = sizeof more; +do { + /* 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 = xs_recvmsg (socket, &part, 0); + assert (rc != -1); + /* Determine if more message parts are to follow */ + rc = xs_getsockopt (socket, XS_RCVMORE, &more, &more_size); + assert (rc == 0); + xs_msg_close (&part); +} while (more); +---- + + +SEE ALSO +-------- +linkxs:xs_recv[3] +linkxs:xs_send[3] +linkxs:xs_sendmsg[3] +linkxs:xs_getsockopt[3] +linkxs:xs_socket[7] +linkxs:xs[7] + + +AUTHORS +------- +This man page was written by Martin Sustrik , Martin +Lucina and Pieter Hintjens . + diff --git a/doc/xs_send.txt b/doc/xs_send.txt new file mode 100644 index 0000000..c5b7d74 --- /dev/null +++ b/doc/xs_send.txt @@ -0,0 +1,105 @@ +xs_send(3) +========== + + +NAME +---- +xs_send - send a message part on a socket + + +SYNOPSIS +-------- +*int xs_send (void '*socket', void '*buf', size_t 'len', int 'flags');* + + +DESCRIPTION +----------- +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: + +*XS_DONTWAIT*:: +Specifies that the operation should be performed in non-blocking mode. If the +message cannot be queued on the 'socket', the _xs_send()_ function shall +fail with 'errno' set to EAGAIN. + +*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 _xs_send()_ does not indicate that the +message has been transmitted to the network, only that it has been queued on +the 'socket' and Crossroads have assumed responsibility for the message. + + +Multi-part messages +~~~~~~~~~~~~~~~~~~~ +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 _XS_SNDMORE_ flag +when sending each data part except the final one. + + +RETURN VALUE +------------ +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. + + +ERRORS +------ +*EAGAIN*:: +Non-blocking mode was requested and the message cannot be sent at the moment. +*ENOTSUP*:: +The _xs_send()_ operation is not supported by this socket type. +*EFSM*:: +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 XS_REP. See the +_messaging patterns_ section of linkxs:xs_socket[3] for more information. +*ETERM*:: +The 'context' associated with the specified 'socket' was terminated. +*ENOTSOCK*:: +The provided 'socket' was invalid. +*EINTR*:: +The operation was interrupted by delivery of a signal before the message was +sent. +*ECANTROUTE*:: +Message cannot be routed to the destination specified as the peer is either +dead or disconnected. This error makes sense only with XS_ROUTER socket. + + +EXAMPLE +------- +.Sending a multi-part message +---- +/* Send a multi-part message consisting of three parts to socket */ +rc = xs_send (socket, "ABC", 3, XS_SNDMORE); +assert (rc == 3); +rc = xs_send (socket, "DEFGH", 5, XS_SNDMORE); +assert (rc == 5); +/* Final part; no more parts to follow */ +rc = xs_send (socket, "JK", 2, 0); +assert (rc == 2); +---- + +SEE ALSO +-------- +linkxs:xs_sendmsg[3] +linkxs:xs_recv[3] +linkxs:xs_recvmsg[3] +linkxs:xs_socket[7] +linkxs:xs[7] + + +AUTHORS +------- ++This man page was written by Martin Sustrik , Martin ++Lucina and Pieter Hintjens . + diff --git a/doc/xs_sendmsg.txt b/doc/xs_sendmsg.txt new file mode 100644 index 0000000..bf94ecd --- /dev/null +++ b/doc/xs_sendmsg.txt @@ -0,0 +1,121 @@ +xs_sendmsg(3) +============= + + +NAME +---- +xs_sendmsg - send a message part on a socket + + +SYNOPSIS +-------- +*int xs_sendmsg (void '*socket', xs_msg_t '*msg', int 'flags');* + + +DESCRIPTION +----------- +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: + +*XS_DONTWAIT*:: +Specifies that the operation should be performed in non-blocking mode. If the +message cannot be queued on the 'socket', the _xs_sendmsg()_ function shall +fail with 'errno' set to EAGAIN. + +*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 _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 _xs_msg_copy()_). + +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 Crossroads have assumed responsibility for the message. + + +Multi-part messages +~~~~~~~~~~~~~~~~~~~ +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 _XS_SNDMORE_ flag +when sending each data part except the final one. + +RETURN VALUE +------------ +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. + + +ERRORS +------ +*EAGAIN*:: +Non-blocking mode was requested and the message cannot be sent at the moment. +*ENOTSUP*:: +The _xs_sendmsg()_ operation is not supported by this socket type. +*EFSM*:: +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 XS_REP. See the +_messaging patterns_ section of linkxs:xs_socket[3] for more information. +*ETERM*:: +The 'context' associated with the specified 'socket' was terminated. +*ENOTSOCK*:: +The provided 'socket' was invalid. +*EINTR*:: +The operation was interrupted by delivery of a signal before the message was +sent. +*EFAULT*:: +Invalid message. +*ECANTROUTE*:: +Message cannot be routed to the destination specified as the peer is either +dead or disconnected. This error makes sense only with XS_ROUTER socket. + + +EXAMPLE +------- +.Filling in a message and sending it to a socket +---- +/* Create a new message, allocating 6 bytes for message content */ +xs_msg_t msg; +int rc = xs_msg_init_size (&msg, 6); +assert (rc == 0); +/* Fill in message content with 'AAAAAA' */ +memset (xs_msg_data (&msg), 'A', 6); +/* Send the message to the socket */ +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 = xs_sendmsg (socket, &part1, XS_SNDMORE); +rc = xs_sendmsg (socket, &part2, XS_SNDMORE); +/* Final part; no more parts to follow */ +rc = xs_sendmsg (socket, &part3, 0); +---- + + +SEE ALSO +-------- +linkxs:xs_recv[3] +linkxs:xs_recv[3] +linkxs:xs_recvmsg[3] +linkxs:xs_socket[7] +linkxs:xs[7] + + +AUTHORS +------- ++This man page was written by Martin Sustrik , Martin ++Lucina and Pieter Hintjens . + diff --git a/doc/xs_setsockopt.txt b/doc/xs_setsockopt.txt new file mode 100644 index 0000000..7cb91d2 --- /dev/null +++ b/doc/xs_setsockopt.txt @@ -0,0 +1,410 @@ +xs_setsockopt(3) +================ + + +NAME +---- + +xs_setsockopt - set Crossroads socket options + + +SYNOPSIS +-------- +*int xs_setsockopt (void '*socket', int 'option_name', const void '*option_value', size_t 'option_len');* + +Caution: All options, with the exception of XS_SUBSCRIBE, XS_UNSUBSCRIBE and +XS_LINGER, only take effect for subsequent socket bind/connects. + +DESCRIPTION +----------- +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 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 _xs_setsockopt()_ function: + + +XS_SNDHWM: Set high water mark for outbound messages +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +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 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, the library shall take appropriate action such as +blocking or dropping sent messages. Refer to the individual socket descriptions +in linkxs:xs_socket[3] for details on the exact action taken for each socket +type. + +[horizontal] +Option value type:: int +Option value unit:: messages +Default value:: 1000 +Applicable socket types:: all + + +XS_RCVHWM: Set high water mark for inbound messages +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +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 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, the library shall take appropriate action such as +blocking or dropping sent messages. Refer to the individual socket descriptions +in linkxs:xs_socket[3] for details on the exact action taken for each socket +type. + +[horizontal] +Option value type:: int +Option value unit:: messages +Default value:: 1000 +Applicable socket types:: all + + +XS_AFFINITY: Set I/O thread affinity +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +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 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 linkxs:xs_init[3] for details on allocating the number of I/O +threads for a specific _context_. + +[horizontal] +Option value type:: uint64_t +Option value unit:: N/A (bitmap) +Default value:: 0 +Applicable socket types:: N/A + + +XS_SUBSCRIBE: Establish message filter +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +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 +'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:: XS_SUB + + +XS_UNSUBSCRIBE: Remove message filter +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +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:: XS_SUB + + +XS_IDENTITY: Set socket identity +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +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 Crossroads infrastructure. + +[horizontal] +Option value type:: binary data +Option value unit:: N/A +Default value:: NULL +Applicable socket types:: all + + +XS_RATE: Set multicast data rate +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +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 +Option value unit:: kilobits per second +Default value:: 100 +Applicable socket types:: all, when using multicast transports + + +XS_RECOVERY_IVL: Set multicast recovery interval +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +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. + +CAUTION: Exercise care when setting large recovery intervals as the data +needed for recovery will be held in memory. For example, a 1 minute recovery +interval at a data rate of 1Gbps requires a 7GB in-memory buffer. + +[horizontal] +Option value type:: int +Option value unit:: milliseconds +Default value:: 10000 +Applicable socket types:: all, when using multicast transports + +XS_SNDBUF: Set 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. + +[horizontal] +Option value type:: int +Option value unit:: bytes +Default value:: 0 +Applicable socket types:: all + + +XS_RCVBUF: Set kernel receive buffer size +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +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. + +[horizontal] +Option value type:: int +Option value unit:: bytes +Default value:: 0 +Applicable socket types:: all + + +XS_LINGER: Set linger period for socket shutdown +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +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 +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 _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 _xs_close()_. + +* Positive values specify an upper bound for the linger period in milliseconds. + 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. + +[horizontal] +Option value type:: int +Option value unit:: milliseconds +Default value:: -1 (infinite) +Applicable socket types:: all + + +XS_RECONNECT_IVL: Set reconnection interval +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +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 the library to prevent +reconnection storms in topologies with a large number of peers per socket. + +[horizontal] +Option value type:: int +Option value unit:: milliseconds +Default value:: 100 +Applicable socket types:: all, only for connection-oriented transports + + +XS_RECONNECT_IVL_MAX: Set maximum reconnection interval +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +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 XS_RECONNECT_IVL will be ignored. + +[horizontal] +Option value type:: int +Option value unit:: milliseconds +Default value:: 0 (only use XS_RECONNECT_IVL) +Applicable socket types:: all, only for connection-oriented transports + + +XS_BACKLOG: Set maximum length of the queue of outstanding connections +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +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. + +[horizontal] +Option value type:: int +Option value unit:: connections +Default value:: 100 +Applicable socket types:: all, only for connection-oriented transports. + + +XS_MAXMSGSIZE: Maximum acceptable inbound message size +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Limits the size of the inbound message. If a peer sends a message larger than +XS_MAXMSGSIZE it is disconnected. Value of -1 means 'no limit'. + +[horizontal] +Option value type:: int64_t +Option value unit:: bytes +Default value:: -1 +Applicable socket types:: all + + +XS_MULTICAST_HOPS: Maximum network hops for multicast packets +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Sets the time-to-live field in every multicast packet sent from this socket. +The default is 1 which means that the multicast packets don't leave the local +network. + +[horizontal] +Option value type:: int +Option value unit:: network hops +Default value:: 1 +Applicable socket types:: all, when using multicast transports + + +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`, +_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. + +[horizontal] +Option value type:: int +Option value unit:: milliseconds +Default value:: -1 (infinite) +Applicable socket types:: all + + +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`, +_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. + +[horizontal] +Option value type:: int +Option value unit:: milliseconds +Default value:: -1 (infinite) +Applicable socket types:: all + + +XS_IPV4ONLY: Use IPv4-only sockets +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Sets the underlying native socket type. A value of `1` will use IPv4 sockets, +while the value of `0` will use IPv6 sockets. An IPv6 socket lets +applications connect to and accept connections from both IPv4 and IPv6 hosts. + +[horizontal] +Option value type:: int +Option value unit:: boolean +Default value:: 1 (true) +Applicable socket types:: all, when using TCP transports. + + +RETURN VALUE +------------ +The _xs_setsockopt()_ function shall return zero if successful. Otherwise it +shall return `-1` and set 'errno' to one of the values defined below. + + +ERRORS +------ +*EINVAL*:: +The requested option _option_name_ is unknown, or the requested _option_len_ or +_option_value_ is invalid. +*ETERM*:: +The 'context' associated with the specified 'socket' was terminated. +*ENOTSOCK*:: +The provided 'socket' was invalid. +*EINTR*:: +The operation was interrupted by delivery of a signal. + + +EXAMPLE +------- +.Subscribing to messages on a 'XS_SUB' socket +---- +/* Subscribe to all messages */ +rc = xs_setsockopt (socket, XS_SUBSCRIBE, "", 0); +assert (rc == 0); +/* Subscribe to messages prefixed with "ANIMALS.CATS" */ +rc = xs_setsockopt (socket, XS_SUBSCRIBE, "ANIMALS.CATS", 12); +---- + +.Setting I/O thread affinity +---- +int64_t affinity; +/* Incoming connections on TCP port 5555 shall be handled by I/O thread 1 */ +affinity = 1; +rc = xs_setsockopt (socket, XS_AFFINITY, &affinity, sizeof affinity); +assert (rc); +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 = xs_setsockopt (socket, XS_AFFINITY, &affinity, sizeof affinity); +assert (rc); +rc = xs_bind (socket, "tcp://lo:5556"); +assert (rc); +---- + + +SEE ALSO +-------- +linkxs:xs_getsockopt[3] +linkxs:xs_socket[3] +linkxs:xs[7] + + +AUTHORS +------- +The Crossroads documentation was written by Martin Sustrik +and Martin Lucina . diff --git a/doc/xs_socket.txt b/doc/xs_socket.txt new file mode 100644 index 0000000..217850f --- /dev/null +++ b/doc/xs_socket.txt @@ -0,0 +1,347 @@ +xs_socket(3) +============ + + +NAME +---- +xs_socket - create Crossroads socket + + +SYNOPSIS +-------- +*void *xs_socket (void '*context', int 'type');* + + +DESCRIPTION +----------- +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 linkxs:xs_connect[3], or at least one +endpoint must be created for accepting incoming connections with +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, 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_. + +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 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 '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 +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 +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 Crossroads library: + + +Request-reply pattern +~~~~~~~~~~~~~~~~~~~~~ +The request-reply pattern is used for sending requests from a _client_ to one +or more instances of a stateless _service_, and receiving subsequent replies +to each request sent. + + +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 _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 '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 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 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 +XS_HWM option action:: Block + + +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 _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 '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 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 +XS_HWM option action:: Drop + + +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 '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 +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 XS_XREQ characteristics +Compatible peer sockets:: 'XS_XREP', 'XS_REP' +Send/receive pattern:: Unrestricted +Outgoing routing strategy:: Load-balanced +Incoming routing strategy:: Fair-queued +XS_HWM option action:: Block + + +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 '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 XS_XREP characteristics +Compatible peer sockets:: 'XS_XREQ', 'XS_REQ' +Send/receive pattern:: Unrestricted +Outgoing routing strategy:: See text +Incoming routing strategy:: Fair-queued +XS_HWM option action:: Drop + + +Publish-subscribe pattern +~~~~~~~~~~~~~~~~~~~~~~~~~ +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. + + +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 linkxs:xs_recv[3] function is not implemented for this socket type. + +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 _xs_send()_ function shall never block for this socket type. + +[horizontal] +.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 +XS_HWM option action:: Drop + + +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 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 +XS_HWM option action:: Drop + + +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 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 +XS_HWM option action:: Drop + + +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 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 +XS_HWM option action:: Drop + + +Pipeline pattern +~~~~~~~~~~~~~~~~ +The pipeline pattern is used for distributing data to _nodes_ arranged in +a pipeline. Data always flows down the pipeline, and each stage of the pipeline +is connected to at least one _node_. When a pipeline stage is connected to +multiple _nodes_ data is load-balanced among all connected _nodes_. + + +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 _xs_recv()_ function is not implemented for this +socket type. + +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 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 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 +XS_HWM option action:: Block + + +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 _xs_send()_ function is not implemented for +this socket type. + +[horizontal] +.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 +XS_HWM option action:: N/A + + +Exclusive pair pattern +~~~~~~~~~~~~~~~~~~~~~~ +The exclusive pair is an advanced pattern used for communicating exclusively +between two peers. + + +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 +'XS_PAIR' socket. + +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 linkxs:xs_send[3] operations on the socket shall block until the peer +becomes available for sending; messages are not discarded. + +NOTE: 'XS_PAIR' sockets are experimental, and are currently missing several +features such as auto-reconnection. + +[horizontal] +.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 +XS_HWM option action:: Block + + +RETURN VALUE +------------ +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. + + +ERRORS +------ +*EINVAL*:: +The requested socket 'type' is invalid. +*EFAULT*:: +The provided 'context' is invalid. +*EMFILE*:: +The limit on the total number of open Crossroads sockets has been reached. +*ETERM*:: +The context specified was terminated. + +SEE ALSO +-------- +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 Crossroads documentation was written by Martin Sustrik +and Martin Lucina . 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 +and Martin Lucina . diff --git a/doc/xs_tcp.txt b/doc/xs_tcp.txt new file mode 100644 index 0000000..5d5cbca --- /dev/null +++ b/doc/xs_tcp.txt @@ -0,0 +1,162 @@ +xs_tcp(7) +========= + + +NAME +---- +xs_tcp - Crossroads unicast transport using TCP + + +SYNOPSIS +-------- +TCP is an ubiquitous, reliable, unicast transport. When connecting distributed +applications over a network with Crossroads, using the TCP transport will likely +be your first choice. + + +ADDRESSING +---------- +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. + + +Assigning a local address to a socket +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +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. + +An 'interface' may be specified by either of the following: + +* The wild-card `*`, meaning all available interfaces. +* The primary IPv4 or IPv6 address assigned to the interface, in its numeric + representation. +* The interface name as defined by the operating system. + +NOTE: Interface names are not standardised in any way and should be assumed to +be arbitrary and platform dependent. On Win32 platforms no short interface +names exist, thus only the primary IP address may be used to specify an +'interface'. + +Connecting a socket +~~~~~~~~~~~~~~~~~~~ +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. + +A 'peer address' may be specified by either of the following: + +* The DNS name of the peer. +* The IPv4 or IPv6 address of the peer, in it's numeric representation. + + +WIRE FORMAT +----------- +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. + +For frames with a 'payload length' not exceeding 254 octets, the 'payload +length' shall be encoded as a single octet. The minimum valid 'payload length' +of a frame is 1 octet, thus a 'payload length' of 0 octets is invalid and such +frames SHOULD be ignored. + +For frames with a 'payload length' exceeding 254 octets, the 'payload length' +shall be encoded as a single octet with the value `255` followed by the +'payload length' represented as a 64-bit unsigned integer in network byte +order. + +The 'flags' field consists of a single octet containing various control flags: + +Bit 0 (MORE): _More message parts to follow_. A value of 0 indicates that there +are no more message parts to follow; or that the message being sent is not a +multi-part message. A value of 1 indicates that the message being sent is a +multi-part message and more message parts are to follow. + +Bits 1-7: _Reserved_. Bits 1-7 are reserved for future expansion and MUST be +set to zero. + +The following ABNF grammar represents a single 'frame': + +.... + frame = (length flags data) + length = OCTET / (escape 8OCTET) + flags = OCTET + escape = %xFF + data = *OCTET +.... + +The following diagram illustrates the layout of a frame with a 'payload length' +not exceeding 254 octets: + +.... +0 1 2 3 +0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| Payload length| Flags | Message body ... | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| Message body ... ++-+-+-+-+-+-+- ... +.... + +The following diagram illustrates the layout of a frame with a 'payload length' +exceeding 254 octets: + +.... +0 1 2 3 +0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| 0xff | Payload length ... | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| Payload length ... | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| Payload length| Flags | Message body ... | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| Message body ... ++-+-+-+-+-+-+-+ ... +.... + + +EXAMPLES +-------- +.Assigning a local address to a socket +---- +/* TCP port 5555 on all available interfaces */ +rc = xs_bind(socket, "tcp://*:5555"); +assert (rc == 0); +/* TCP port 5555 on the local loop-back interface on all platforms */ +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 = xs_bind(socket, "tcp://eth0:5555"); +assert (rc == 0); +---- + +.Connecting a socket +---- +/* Connecting using an IP address */ +rc = xs_connect(socket, "tcp://192.168.1.1:5555"); +assert (rc == 0); +/* Connecting using a DNS name */ +rc = xs_connect(socket, "tcp://server1:5555"); +assert (rc == 0); +---- + + +SEE ALSO +-------- +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 Crossroads documentation was written by Martin Sustrik +and Martin Lucina . 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 +and Martin Lucina . 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 +and Martin Lucina . 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 * - -*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 and -Martin Lucina . - - -RESOURCES ---------- -Main web site: - -Report bugs to the 0MQ development mailing list: - - -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_bind.txt b/doc/zmq_bind.txt deleted file mode 100644 index 58517ec..0000000 --- a/doc/zmq_bind.txt +++ /dev/null @@ -1,93 +0,0 @@ -zmq_bind(3) -=========== - - -NAME ----- -zmq_bind - accept connections on a socket - - -SYNOPSIS --------- -*int zmq_bind (void '*socket', const char '*endpoint');* - - -DESCRIPTION ------------ -The _zmq_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: -'transport'`://`'address'. The 'transport' part specifies the underlying -transport protocol to use. The meaning of the 'address' part is specific to -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] - -With the exception of 'ZMQ_PAIR' sockets, a single socket may be connected to -multiple endpoints using _zmq_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 -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 -return `-1` and set 'errno' to one of the values defined below. - - -ERRORS ------- -*EINVAL*:: -The endpoint supplied is invalid. -*EPROTONOSUPPORT*:: -The requested 'transport' protocol is not supported. -*ENOCOMPATPROTO*:: -The requested 'transport' protocol is not compatible with the socket type. -*EADDRINUSE*:: -The requested 'address' is already in use. -*EADDRNOTAVAIL*:: -The requested 'address' was not local. -*ENODEV*:: -The requested 'address' specifies a nonexistent interface. -*ETERM*:: -The 0MQ 'context' associated with the specified 'socket' was terminated. -*ENOTSOCK*:: -The provided 'socket' was invalid. -*EMTHREAD*:: -No I/O thread is available to accomplish the task. - - -EXAMPLE -------- -.Binding a publisher socket to an in-process and a TCP transport ----- -/* Create a ZMQ_PUB socket */ -void *socket = zmq_socket (context, ZMQ_PUB); -assert (socket); -/* Bind it to a in-process transport with the address 'my_publisher' */ -int rc = zmq_bind (socket, "inproc://my_publisher"); -assert (rc == 0); -/* Bind it to a TCP transport on port 5555 of the 'eth0' interface */ -rc = zmq_bind (socket, "tcp://eth0:5555"); -assert (rc == 0); ----- - - -SEE ALSO --------- -linkzmq:zmq_connect[3] -linkzmq:zmq_socket[3] -linkzmq:zmq[7] - - -AUTHORS -------- -The 0MQ documentation was written by Martin Sustrik and -Martin Lucina . 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 and -Martin Lucina . diff --git a/doc/zmq_connect.txt b/doc/zmq_connect.txt deleted file mode 100644 index d0045c4..0000000 --- a/doc/zmq_connect.txt +++ /dev/null @@ -1,91 +0,0 @@ -zmq_connect(3) -============== - - -NAME ----- -zmq_connect - connect a socket - - -SYNOPSIS --------- -*int zmq_connect (void '*socket', const char '*endpoint');* - - -DESCRIPTION ------------ -The _zmq_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: -'transport'`://`'address'. The 'transport' part specifies the underlying -transport protocol to use. The meaning of the 'address' part is specific to -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] - -With the exception of 'ZMQ_PAIR' sockets, a single socket may be connected to -multiple endpoints using _zmq_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 -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 -physical connection was or can actually be established. - - -RETURN VALUE ------------- -The _zmq_connect()_ function shall return zero if successful. Otherwise it -shall return `-1` and set 'errno' to one of the values defined below. - - -ERRORS ------- -*EINVAL*:: -The endpoint supplied is invalid. -*EPROTONOSUPPORT*:: -The requested 'transport' protocol is not supported. -*ENOCOMPATPROTO*:: -The requested 'transport' protocol is not compatible with the socket type. -*ETERM*:: -The 0MQ 'context' associated with the specified 'socket' was terminated. -*ENOTSOCK*:: -The provided 'socket' was invalid. -*EMTHREAD*:: -No I/O thread is available to accomplish the task. - - -EXAMPLE -------- -.Connecting a subscriber socket to an in-process and a TCP transport ----- -/* Create a ZMQ_SUB socket */ -void *socket = zmq_socket (context, ZMQ_SUB); -assert (socket); -/* Connect it to an in-process transport with the address 'my_publisher' */ -int rc = zmq_connect (socket, "inproc://my_publisher"); -assert (rc == 0); -/* Connect it to the host server001, port 5555 using a TCP transport */ -rc = zmq_connect (socket, "tcp://server001:5555"); -assert (rc == 0); ----- - - -SEE ALSO --------- -linkzmq:zmq_bind[3] -linkzmq:zmq_socket[3] -linkzmq:zmq[7] - - -AUTHORS -------- -The 0MQ documentation was written by Martin Sustrik and -Martin Lucina . diff --git a/doc/zmq_epgm.txt b/doc/zmq_epgm.txt deleted file mode 120000 index 4d58b1b..0000000 --- a/doc/zmq_epgm.txt +++ /dev/null @@ -1 +0,0 @@ -zmq_pgm.txt \ No newline at end of file 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 and -Martin Lucina . diff --git a/doc/zmq_getmsgopt.txt b/doc/zmq_getmsgopt.txt deleted file mode 100644 index a82c30c..0000000 --- a/doc/zmq_getmsgopt.txt +++ /dev/null @@ -1,85 +0,0 @@ -zmq_getmsgopt(3) -================ - - -NAME ----- -zmq_getmsgopt - retrieve message option - - -SYNOPSIS --------- -*int zmq_getmsgopt (zmq_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 -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 -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: - -*ZMQ_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 -shall return `-1` and set 'errno' to one of the values defined below. - - -ERRORS ------- -*EINVAL*:: -The requested option _option_name_ is unknown, or the requested _option_size_ or -_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. - - -EXAMPLE -------- -.Receiving a multi-part message ----- -zmq_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); - assert (rc == 0); - /* Block until a message is available to be received from socket */ - rc = zmq_recvmsg (socket, &part, 0); - assert (rc != -1); - rc = getmsgopt (&part, ZMQ_MORE, &more, &more_size); - assert (rc == 0); - if (more) { - fprintf (stderr, "more\n"); - } - else { - fprintf (stderr, "end\n"); - break; - } - zmq_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] - - -AUTHORS -------- -The 0MQ documentation was written by Chuck Remes . diff --git a/doc/zmq_getsockopt.txt b/doc/zmq_getsockopt.txt deleted file mode 100644 index 50b80fd..0000000 --- a/doc/zmq_getsockopt.txt +++ /dev/null @@ -1,438 +0,0 @@ -zmq_getsockopt(3) -================= - - -NAME ----- - -zmq_getsockopt - get 0MQ socket options - - -SYNOPSIS --------- -*int zmq_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 following options can be retrieved with the _zmq_getsockopt()_ function: - - -ZMQ_TYPE: Retrieve socket type -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_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. - -[horizontal] -Option value type:: int -Option value unit:: N/A -Default value:: N/A -Applicable socket types:: all - - -ZMQ_RCVMORE: More message data parts to follow -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_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 -of multi-part messages. - -[horizontal] -Option value type:: int -Option value unit:: boolean -Default value:: N/A -Applicable socket types:: all - - -ZMQ_SNDHWM: Retrieves high water mark for outbound messages -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_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. - -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 -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 -type. - -[horizontal] -Option value type:: int -Option value unit:: messages -Default value:: 1000 -Applicable socket types:: all - - -ZMQ_RCVHWM: Retrieve high water mark for inbound messages -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_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. - -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 -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 -type. - -[horizontal] -Option value type:: int -Option value unit:: messages -Default value:: 1000 -Applicable socket types:: all - - -ZMQ_AFFINITY: Retrieve I/O thread affinity -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_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 -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 -threads for a specific _context_. - -[horizontal] -Option value type:: uint64_t -Option value unit:: N/A (bitmap) -Default value:: 0 -Applicable socket types:: N/A - -ZMQ_IDENTITY: Set socket identity -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_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. - -[horizontal] -Option value type:: binary data -Option value unit:: N/A -Default value:: NULL -Applicable socket types:: all - - -ZMQ_RATE: Retrieve multicast data rate -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_RATE' option shall retrieve the maximum send or receive data rate for -multicast transports using the specified 'socket'. - -[horizontal] -Option value type:: int -Option value unit:: kilobits per second -Default value:: 100 -Applicable socket types:: all, when using multicast transports - - -ZMQ_RECOVERY_IVL: Get multicast recovery interval -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_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. - -[horizontal] -Option value type:: int -Option value unit:: milliseconds -Default value:: 10000 -Applicable socket types:: all, when using multicast transports - - -ZMQ_SNDBUF: Retrieve kernel transmit buffer size -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_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. - -[horizontal] -Option value type:: int -Option value unit:: bytes -Default value:: 0 -Applicable socket types:: all - - -ZMQ_RCVBUF: Retrieve kernel receive buffer size -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_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. - -[horizontal] -Option value type:: int -Option value unit:: bytes -Default value:: 0 -Applicable socket types:: all - - -ZMQ_LINGER: Retrieve linger period for socket shutdown -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_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 -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 - 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()_. - -* 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 - until either all pending messages have been sent to a peer, or the linger - period expires, after which any pending messages shall be discarded. - -[horizontal] -Option value type:: int -Option value unit:: milliseconds -Default value:: -1 (infinite) -Applicable socket types:: all - - -ZMQ_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 -connection-oriented transports. - -NOTE: The reconnection interval may be randomized by 0MQ to prevent -reconnection storms in topologies with a large number of peers per socket. - -[horizontal] -Option value type:: int -Option value unit:: milliseconds -Default value:: 100 -Applicable socket types:: all, only for connection-oriented transports - - -ZMQ_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. - -NOTE: Values less than ZMQ_RECONNECT_IVL will be ignored. - -[horizontal] -Option value type:: int -Option value unit:: milliseconds -Default value:: 0 (only use ZMQ_RECONNECT_IVL) -Applicable socket types:: all, only for connection-oriented transport - - -ZMQ_BACKLOG: Retrieve maximum length of the queue of outstanding connections -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_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. - -[horizontal] -Option value type:: int -Option value unit:: connections -Default value:: 100 -Applicable socket types:: all, only for connection-oriented transports - - -ZMQ_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 -'no limit'. - -[horizontal] -Option value type:: int64_t -Option value unit:: bytes -Default value:: -1 -Applicable socket types:: all - - -ZMQ_MULTICAST_HOPS: Maximum network hops for multicast packets -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The option shall retrieve time-to-live used for outbound multicast packets. -The default of 1 means that the multicast packets don't leave the local network. - -[horizontal] -Option value type:: int -Option value unit:: network hops -Default value:: 1 -Applicable socket types:: all, when using multicast transports - - -ZMQ_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 -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. - -[horizontal] -Option value type:: int -Option value unit:: milliseconds -Default value:: -1 (infinite) -Applicable socket types:: all - - -ZMQ_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 -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. - -[horizontal] -Option value type:: int -Option value unit:: milliseconds -Default value:: -1 (infinite) -Applicable socket types:: all - - -ZMQ_IPV4ONLY: Retrieve IPv4-only socket override status -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Retrieve the underlying native socket type. A value of `1` will use IPv4 -sockets, while the value of `0` will use IPv6 sockets. An IPv6 socket -lets applications connect to and accept connections from both IPv4 and IPv6 -hosts. - -[horizontal] -Option value type:: int -Option value unit:: boolean -Default value:: 1 (true) -Applicable socket types:: all, when using TCP transports. - - -ZMQ_FD: Retrieve file descriptor associated with the socket -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_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 -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. - -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 -to it directly, neither should they try to close it. - -[horizontal] -Option value type:: int on POSIX systems, SOCKET on Windows -Option value unit:: N/A -Default value:: N/A -Applicable socket types:: all - - -ZMQ_EVENTS: Retrieve socket event state -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_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*:: -Indicates that at least one message may be received from the specified socket -without blocking. - -*ZMQ_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 -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 -and restart their polling operation/event loop. - -[horizontal] -Option value type:: int -Option value unit:: N/A (flags) -Default value:: N/A -Applicable socket types:: all - - -RETURN VALUE ------------- -The _zmq_getsockopt()_ function shall return zero if successful. Otherwise it -shall return `-1` and set 'errno' to one of the values defined below. - - -ERRORS ------- -*EINVAL*:: -The requested option _option_name_ is unknown, or the requested _option_len_ or -_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. -*ENOTSOCK*:: -The provided 'socket' was invalid. -*EINTR*:: -The operation was interrupted by delivery of a signal. - - -EXAMPLE -------- -.Retrieving the high water mark for outgoing messages ----- -/* Retrieve high water mark into sndhwm */ -int sndhwm; -size_t sndhwm_size = sizeof (sndhwm); -rc = zmq_getsockopt (socket, ZMQ_SNDHWM, &sndhwm, &sndhwm_size); -assert (rc == 0); ----- - - -SEE ALSO --------- -linkzmq:zmq_setsockopt[3] -linkzmq:zmq_socket[3] -linkzmq:zmq[7] - - -AUTHORS -------- -The 0MQ documentation was written by Martin Sustrik and -Martin Lucina . diff --git a/doc/zmq_init.txt b/doc/zmq_init.txt deleted file mode 100644 index 74f4b3e..0000000 --- a/doc/zmq_init.txt +++ /dev/null @@ -1,51 +0,0 @@ -zmq_init(3) -=========== - - -NAME ----- -zmq_init - initialise 0MQ context - - -SYNOPSIS --------- -*void *zmq_init (int 'io_threads');* - - -DESCRIPTION ------------ -The _zmq_init()_ function initialises a 0MQ 'context'. - -The 'io_threads' argument specifies the size of the 0MQ thread pool to handle -I/O operations. If your application is using only the 'inproc' transport for -messaging you may set this to zero, otherwise set it to at least one. - -.Thread safety -A 0MQ 'context' is thread safe and may be shared among as many application -threads as necessary, without any additional locking required on the part of -the caller. - - -RETURN VALUE ------------- -The _zmq_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. - - -ERRORS ------- -*EINVAL*:: -An invalid number of 'io_threads' was requested. - - -SEE ALSO --------- -linkzmq:zmq[7] -linkzmq:zmq_term[3] - - -AUTHORS -------- -The 0MQ documentation was written by Martin Sustrik and -Martin Lucina . diff --git a/doc/zmq_inproc.txt b/doc/zmq_inproc.txt deleted file mode 100644 index a2ae6e3..0000000 --- a/doc/zmq_inproc.txt +++ /dev/null @@ -1,89 +0,0 @@ -zmq_inproc(7) -============= - - -NAME ----- -zmq_inproc - 0MQ local in-process (inter-thread) communication 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. - - -ADDRESSING ----------- -A 0MQ 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 -defined below. - - -Assigning a local address to a socket -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -When assigning a local address to a 'socket' using _zmq_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 -'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 -'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' -as the 'socket' being connected. - - -WIRE FORMAT ------------ -Not applicable. - - -EXAMPLES --------- -.Assigning a local address to a socket ----- -/* Assign the in-process name "#1" */ -rc = zmq_bind(socket, "inproc://#1"); -assert (rc == 0); -/* Assign the in-process name "my-endpoint" */ -rc = zmq_bind(socket, "inproc://my-endpoint"); -assert (rc == 0); ----- - -.Connecting a socket ----- -/* Connect to the in-process name "#1" */ -rc = zmq_connect(socket, "inproc://#1"); -assert (rc == 0); -/* Connect to the in-process name "my-endpoint" */ -rc = zmq_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] - - -AUTHORS -------- -The 0MQ documentation was written by Martin Sustrik and -Martin Lucina . diff --git a/doc/zmq_ipc.txt b/doc/zmq_ipc.txt deleted file mode 100644 index 80109ee..0000000 --- a/doc/zmq_ipc.txt +++ /dev/null @@ -1,80 +0,0 @@ -zmq_ipc(7) -========== - - -NAME ----- -zmq_ipc - 0MQ local inter-process communication transport - - -SYNOPSIS --------- -The inter-process transport passes messages between local processes using a -system-dependent IPC mechanism. - -NOTE: The inter-process transport is currently only implemented on operating -systems that provide UNIX domain sockets. - - -ADDRESSING ----------- -A 0MQ 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 -defined below. - - -Assigning a local address to a socket -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -When assigning a local address to a 'socket' using _zmq_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 -any restrictions placed by the operating system on the format and length of a -'pathname'. - -Connecting a socket -~~~~~~~~~~~~~~~~~~~ -When connecting a 'socket' to a peer address using _zmq_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()_. - - -WIRE FORMAT ------------ -Not applicable. - - -EXAMPLES --------- -.Assigning a local address to a socket ----- -/* Assign the pathname "/tmp/feeds/0" */ -rc = zmq_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"); -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] - - -AUTHORS -------- -The 0MQ documentation was written by Martin Sustrik and -Martin Lucina . 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 and -Martin Lucina . 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 and -Martin Lucina . 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 and -Martin Lucina . 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 and -Martin Lucina . 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 and -Martin Lucina . 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 and -Martin Lucina . 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 and -Martin Lucina . 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 and -Martin Lucina . diff --git a/doc/zmq_pgm.txt b/doc/zmq_pgm.txt deleted file mode 100644 index d96d3ba..0000000 --- a/doc/zmq_pgm.txt +++ /dev/null @@ -1,161 +0,0 @@ -zmq_pgm(7) -========== - - -NAME ----- -zmq_pgm - 0MQ reliable multicast transport using PGM - - -SYNOPSIS --------- -PGM (Pragmatic General Multicast) is a protocol for reliable multicast -transport of data over IP networks. - - -DESCRIPTION ------------ -0MQ implements two variants of PGM, the standard protocol where PGM datagrams -are layered directly on top of IP datagrams as defined by RFC 3208 (the 'pgm' -transport) and "Encapsulated PGM" where PGM datagrams are encapsulated inside -UDP datagrams (the 'epgm' transport). - -The 'pgm' and 'epgm' transports can only be used with the 'ZMQ_PUB' and -'ZMQ_SUB' socket types. - -Further, PGM sockets are rate limited by default. For details, refer to the -'ZMQ_RATE', and 'ZMQ_RECOVERY_IVL' options documented in -linkzmq:zmq_setsockopt[3]. - -CAUTION: The 'pgm' transport implementation requires access to raw IP sockets. -Additional privileges may be required on some operating systems for this -operation. Applications not requiring direct interoperability with other PGM -implementations are encouraged to use the 'epgm' transport instead which does -not require any special privileges. - - -ADDRESSING ----------- -A 0MQ 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 -`epgm`. The meaning of the 'endpoint' part for both the 'pgm' and 'epgm' -transport is defined below. - - -Connecting a socket -~~~~~~~~~~~~~~~~~~~ -When connecting a socket to a peer address using _zmq_connect()_ with the 'pgm' -or 'epgm' transport, the 'endpoint' shall be interpreted as an 'interface' -followed by a semicolon, followed by a 'multicast address', followed by a colon -and a port number. - -An 'interface' may be specified by either of the following: - -* The interface name as defined by the operating system. -* The primary IPv4 address assigned to the interface, in it's numeric - representation. - -NOTE: Interface names are not standardised in any way and should be assumed to -be arbitrary and platform dependent. On Win32 platforms no short interface -names exist, thus only the primary IPv4 address may be used to specify an -'interface'. - -A 'multicast address' is specified by an IPv4 multicast address in it's numeric -representation. - - -WIRE FORMAT ------------ -Consecutive PGM datagrams are interpreted by 0MQ as a single continuous stream -of data where 0MQ messages are not necessarily aligned with PGM datagram -boundaries and a single 0MQ message may span several PGM datagrams. This stream -of data consists of 0MQ messages encapsulated in 'frames' as described in -linkzmq:zmq_tcp[7]. - - -PGM datagram payload -~~~~~~~~~~~~~~~~~~~~ -The following ABNF grammar represents the payload of a single PGM datagram as -used by 0MQ: - -.... -datagram = (offset data) -offset = 2OCTET -data = *OCTET -.... - -In order for late joining consumers to be able to identify message boundaries, -each PGM datagram payload starts with a 16-bit unsigned integer in network byte -order specifying either the offset of the first message 'frame' in the datagram -or containing the value `0xFFFF` if the datagram contains solely an -intermediate part of a larger message. - -Note that offset specifies where the first message begins rather than the first -message part. Thus, if there are trailing message parts at the beginning of -the packet the offset ignores them and points to first initial message part -in the packet. - -The following diagram illustrates the layout of a single PGM datagram payload: - -.... -+------------------+----------------------+ -| offset (16 bits) | data | -+------------------+----------------------+ -.... - -The following diagram further illustrates how three example 0MQ frames are laid -out in consecutive PGM datagram payloads: - -.... -First datagram payload -+--------------+-------------+---------------------+ -| Frame offset | Frame 1 | Frame 2, part 1 | -| 0x0000 | (Message 1) | (Message 2, part 1) | -+--------------+-------------+---------------------+ - -Second datagram payload -+--------------+---------------------+ -| Frame offset | Frame 2, part 2 | -| 0xFFFF | (Message 2, part 2) | -+--------------+---------------------+ - -Third datagram payload -+--------------+----------------------------+-------------+ -| Frame offset | Frame 2, final 8 bytes | Frame 3 | -| 0x0008 | (Message 2, final 8 bytes) | (Message 3) | -+--------------+----------------------------+-------------+ -.... - - -EXAMPLE -------- -.Connecting a socket ----- -/* Connecting to the multicast address 239.192.1.1, port 5555, */ -/* using the first Ethernet network interface on Linux */ -/* and the Encapsulated PGM protocol */ -rc = zmq_connect(socket, "epgm://eth0;239.192.1.1:5555"); -assert (rc == 0); -/* Connecting to the multicast address 239.192.1.1, port 5555, */ -/* using the network interface with the address 192.168.1.1 */ -/* and the standard PGM protocol */ -rc = zmq_connect(socket, "pgm://192.168.1.1;239.192.1.1:5555"); -assert (rc == 0); ----- - - -SEE ALSO --------- -linkzmq:zmq_connect[3] -linkzmq:zmq_setsockopt[3] -linkzmq:zmq_tcp[7] -linkzmq:zmq_ipc[7] -linkzmq:zmq_inproc[7] -linkzmq:zmq[7] - -AUTHORS -------- -The 0MQ documentation was written by Martin Sustrik and -Martin Lucina . 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 and -Martin Lucina . diff --git a/doc/zmq_recv.txt b/doc/zmq_recv.txt deleted file mode 100644 index 3a5be9c..0000000 --- a/doc/zmq_recv.txt +++ /dev/null @@ -1,94 +0,0 @@ -zmq_recv(3) -=========== - - -NAME ----- -zmq_recv - receive a message part from a socket - - -SYNOPSIS --------- -*int zmq_recv (void '*socket', void '*buf', size_t 'len', int 'flags');* - - -DESCRIPTION ------------ -The _zmq_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 'flags' argument is a combination of the flags defined below: - -*ZMQ_DONTWAIT*:: -Specifies that the operation should be performed in non-blocking mode. If there -are no messages available on the specified 'socket', the _zmq_recv()_ -function shall fail with 'errno' set to EAGAIN. - - -Multi-part messages -~~~~~~~~~~~~~~~~~~~ -A 0MQ message is composed of 1 or more message parts. Each message -part is an independent 'zmq_msg_t' in its own right. 0MQ ensures atomic -delivery of messages; peers shall receive either all _message parts_ of a -message or none at all. The total number of message parts is unlimited except -by available memory. - -An application that processes multipart messages must use the _ZMQ_RCVMORE_ -linkzmq:zmq_getsockopt[3] option after calling _zmq_recv()_ to determine if -there are further parts to receive. - -RETURN VALUE ------------- -The _zmq_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. - - -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. -*EFSM*:: -The _zmq_recv()_ operation cannot be performed on this socket at the moment -due to the socket not being in the appropriate state. This error may occur with -socket types that switch between several states, such as ZMQ_REP. See the -_messaging patterns_ section of linkzmq:zmq_socket[3] for more information. -*ETERM*:: -The 0MQ 'context' associated with the specified 'socket' was terminated. -*ENOTSOCK*:: -The provided 'socket' was invalid. -*EINTR*:: -The operation was interrupted by delivery of a signal before a message was -available. - - -EXAMPLE -------- -.Receiving a message from a socket ----- -char buf [256]; -nbytes = zmq_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] - - -AUTHORS -------- -+This man page was written by Martin Sustrik , Martin -+Lucina and Pieter Hintjens . - diff --git a/doc/zmq_recvmsg.txt b/doc/zmq_recvmsg.txt deleted file mode 100644 index b7575a0..0000000 --- a/doc/zmq_recvmsg.txt +++ /dev/null @@ -1,121 +0,0 @@ -zmq_recvmsg(3) -============== - - -NAME ----- -zmq_recvmsg - receive a message part from a socket - - -SYNOPSIS --------- -*int zmq_recvmsg (void '*socket', zmq_msg_t '*msg', int 'flags');* - - -DESCRIPTION ------------ -The _zmq_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 'flags' argument is a combination of the flags defined below: - -*ZMQ_DONTWAIT*:: -Specifies that the operation should be performed in non-blocking mode. If there -are no messages available on the specified 'socket', the _zmq_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 -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 -there are further parts to receive. - - -RETURN VALUE ------------- -The _zmq_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. - - -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. -*EFSM*:: -The _zmq_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. -*ETERM*:: -The 0MQ 'context' associated with the specified 'socket' was terminated. -*ENOTSOCK*:: -The provided 'socket' was invalid. -*EINTR*:: -The operation was interrupted by delivery of a signal before a message was -available. -*EFAULT*:: -The message passed to the function was invalid. - - -EXAMPLE -------- -.Receiving a message from a socket ----- -/* Create an empty 0MQ message */ -zmq_msg_t msg; -int rc = zmq_msg_init (&msg); -assert (rc == 0); -/* Block until a message is available to be received from socket */ -rc = zmq_recvmsg (socket, &msg, 0); -assert (rc != -1); -/* Release message */ -zmq_msg_close (&msg); ----- - -.Receiving a multi-part message ----- -int64_t more; -size_t more_size = sizeof more; -do { - /* Create an empty 0MQ message to hold the message part */ - zmq_msg_t part; - int rc = zmq_msg_init (&part); - assert (rc == 0); - /* Block until a message is available to be received from socket */ - rc = zmq_recvmsg (socket, &part, 0); - assert (rc != -1); - /* Determine if more message parts are to follow */ - rc = zmq_getsockopt (socket, ZMQ_RCVMORE, &more, &more_size); - assert (rc == 0); - zmq_msg_close (&part); -} while (more); ----- - - -SEE ALSO --------- -linkzmq:zmq_recv[3] -linkzmq:zmq_send[3] -linkzmq:zmq_sendmsg[3] -linkzmq:zmq_getsockopt[3] -linkzmq:zmq_socket[7] -linkzmq:zmq[7] - - -AUTHORS -------- -This man page was written by Martin Sustrik , Martin -Lucina and Pieter Hintjens . - diff --git a/doc/zmq_send.txt b/doc/zmq_send.txt deleted file mode 100644 index 58c761f..0000000 --- a/doc/zmq_send.txt +++ /dev/null @@ -1,105 +0,0 @@ -zmq_send(3) -=========== - - -NAME ----- -zmq_send - send a message part on a socket - - -SYNOPSIS --------- -*int zmq_send (void '*socket', void '*buf', size_t 'len', int 'flags');* - - -DESCRIPTION ------------ -The _zmq_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*:: -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 -fail with 'errno' set to EAGAIN. - -*ZMQ_SNDMORE*:: -Specifies that the message being sent is a multi-part message, and that further -message parts are to follow. Refer to the section regarding multi-part messages -below for a detailed description. - -NOTE: A successful invocation of _zmq_send()_ does not indicate that the -message has been transmitted to the network, only that it has been queued on -the 'socket' and 0MQ has assumed responsibility for the message. - - -Multi-part messages -~~~~~~~~~~~~~~~~~~~ -A 0MQ message is composed of 1 or more message parts. Each message -part is an independent 'zmq_msg_t' in its own right. 0MQ ensures atomic -delivery of messages; peers shall receive either all _message parts_ of a -message or none at all. The total number of message parts is unlimited except -by available memory. - -An application that sends multipart messages must use the _ZMQ_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 -if successful. Otherwise it shall return `-1` and set 'errno' to one of the -values defined below. - - -ERRORS ------- -*EAGAIN*:: -Non-blocking mode was requested and the message cannot be sent at the moment. -*ENOTSUP*:: -The _zmq_send()_ operation is not supported by this socket type. -*EFSM*:: -The _zmq_send()_ operation cannot be performed on this socket at the moment -due to the socket not being in the appropriate state. This error may occur with -socket types that switch between several states, such as ZMQ_REP. See the -_messaging patterns_ section of linkzmq:zmq_socket[3] for more information. -*ETERM*:: -The 0MQ 'context' associated with the specified 'socket' was terminated. -*ENOTSOCK*:: -The provided 'socket' was invalid. -*EINTR*:: -The operation was interrupted by delivery of a signal before the message was -sent. -*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. - - -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); -assert (rc == 3); -rc = zmq_send (socket, "DEFGH", 5, ZMQ_SNDMORE); -assert (rc == 5); -/* Final part; no more parts to follow */ -rc = zmq_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] - - -AUTHORS -------- -+This man page was written by Martin Sustrik , Martin -+Lucina and Pieter Hintjens . - diff --git a/doc/zmq_sendmsg.txt b/doc/zmq_sendmsg.txt deleted file mode 100644 index 3c09bec..0000000 --- a/doc/zmq_sendmsg.txt +++ /dev/null @@ -1,121 +0,0 @@ -zmq_sendmsg(3) -============== - - -NAME ----- -zmq_sendmsg - send a message part on a socket - - -SYNOPSIS --------- -*int zmq_sendmsg (void '*socket', zmq_msg_t '*msg', int 'flags');* - - -DESCRIPTION ------------ -The _zmq_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*:: -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 -fail with 'errno' set to EAGAIN. - -*ZMQ_SNDMORE*:: -Specifies that the message being sent is a multi-part message, and that further -message parts are to follow. Refer to the section regarding multi-part messages -below for a detailed description. - -The _zmq_msg_t_ structure passed to _zmq_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()_). - -NOTE: A successful invocation of _zmq_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. - - -Multi-part messages -~~~~~~~~~~~~~~~~~~~ -A 0MQ message is composed of 1 or more message parts. Each message -part is an independent 'zmq_msg_t' in its own right. 0MQ ensures atomic -delivery of messages; peers shall receive either all _message parts_ of a -message or none at all. The total number of message parts is unlimited except -by available memory. - -An application that sends multipart messages must use the _ZMQ_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 -if successful. Otherwise it shall return `-1` and set 'errno' to one of the -values defined below. - - -ERRORS ------- -*EAGAIN*:: -Non-blocking mode was requested and the message cannot be sent at the moment. -*ENOTSUP*:: -The _zmq_sendmsg()_ operation is not supported by this socket type. -*EFSM*:: -The _zmq_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. -*ETERM*:: -The 0MQ 'context' associated with the specified 'socket' was terminated. -*ENOTSOCK*:: -The provided 'socket' was invalid. -*EINTR*:: -The operation was interrupted by delivery of a signal before the message was -sent. -*EFAULT*:: -Invalid message. -*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. - - -EXAMPLE -------- -.Filling in a message and sending it to a socket ----- -/* Create a new message, allocating 6 bytes for message content */ -zmq_msg_t msg; -int rc = zmq_msg_init_size (&msg, 6); -assert (rc == 0); -/* Fill in message content with 'AAAAAA' */ -memset (zmq_msg_data (&msg), 'A', 6); -/* Send the message to the socket */ -rc = zmq_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); -/* Final part; no more parts to follow */ -rc = zmq_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] - - -AUTHORS -------- -+This man page was written by Martin Sustrik , Martin -+Lucina and Pieter Hintjens . - diff --git a/doc/zmq_setsockopt.txt b/doc/zmq_setsockopt.txt deleted file mode 100644 index ca8ced0..0000000 --- a/doc/zmq_setsockopt.txt +++ /dev/null @@ -1,409 +0,0 @@ -zmq_setsockopt(3) -================= - - -NAME ----- - -zmq_setsockopt - set 0MQ socket options - - -SYNOPSIS --------- -*int zmq_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. - -DESCRIPTION ------------ -The _zmq_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' -argument is the size of the option value in bytes. - -The following socket options can be set with the _zmq_setsockopt()_ function: - - -ZMQ_SNDHWM: Set high water mark for outbound messages -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_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. - -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 -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 -type. - -[horizontal] -Option value type:: int -Option value unit:: messages -Default value:: 1000 -Applicable socket types:: all - - -ZMQ_RCVHWM: Set high water mark for inbound messages -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_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. - -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 -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 -type. - -[horizontal] -Option value type:: int -Option value unit:: messages -Default value:: 1000 -Applicable socket types:: all - - -ZMQ_AFFINITY: Set I/O thread affinity -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_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. - -See also linkzmq:zmq_init[3] for details on allocating the number of I/O -threads for a specific _context_. - -[horizontal] -Option value type:: uint64_t -Option value unit:: N/A (bitmap) -Default value:: 0 -Applicable socket types:: N/A - - -ZMQ_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, -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 -least one filter. - -[horizontal] -Option value type:: binary data -Option value unit:: N/A -Default value:: N/A -Applicable socket types:: ZMQ_SUB - - -ZMQ_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 -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 - - -ZMQ_IDENTITY: Set socket identity -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_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. - -[horizontal] -Option value type:: binary data -Option value unit:: N/A -Default value:: NULL -Applicable socket types:: all - - -ZMQ_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'. - -[horizontal] -Option value type:: int -Option value unit:: kilobits per second -Default value:: 100 -Applicable socket types:: all, when using multicast transports - - -ZMQ_RECOVERY_IVL: Set multicast recovery interval -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_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. - -CAUTION: Exercise care when setting large recovery intervals as the data -needed for recovery will be held in memory. For example, a 1 minute recovery -interval at a data rate of 1Gbps requires a 7GB in-memory buffer. - -[horizontal] -Option value type:: int -Option value unit:: milliseconds -Default value:: 10000 -Applicable socket types:: all, when using multicast transports - -ZMQ_SNDBUF: Set kernel transmit buffer size -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_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. - -[horizontal] -Option value type:: int -Option value unit:: bytes -Default value:: 0 -Applicable socket types:: all - - -ZMQ_RCVBUF: Set kernel receive buffer size -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_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. - -[horizontal] -Option value type:: int -Option value unit:: bytes -Default value:: 0 -Applicable socket types:: all - - -ZMQ_LINGER: Set linger period for socket shutdown -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_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 -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 - 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()_. - -* 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 - until either all pending messages have been sent to a peer, or the linger - period expires, after which any pending messages shall be discarded. - -[horizontal] -Option value type:: int -Option value unit:: milliseconds -Default value:: -1 (infinite) -Applicable socket types:: all - - -ZMQ_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 -shall wait between attempts to reconnect disconnected peers when using -connection-oriented transports. - -NOTE: The reconnection interval may be randomized by 0MQ to prevent -reconnection storms in topologies with a large number of peers per socket. - -[horizontal] -Option value type:: int -Option value unit:: milliseconds -Default value:: 100 -Applicable socket types:: all, only for connection-oriented transports - - -ZMQ_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. - -NOTE: Values less than ZMQ_RECONNECT_IVL will be ignored. - -[horizontal] -Option value type:: int -Option value unit:: milliseconds -Default value:: 0 (only use ZMQ_RECONNECT_IVL) -Applicable socket types:: all, only for connection-oriented transports - - -ZMQ_BACKLOG: Set maximum length of the queue of outstanding connections -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'ZMQ_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. - -[horizontal] -Option value type:: int -Option value unit:: connections -Default value:: 100 -Applicable socket types:: all, only for connection-oriented transports. - - -ZMQ_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'. - -[horizontal] -Option value type:: int64_t -Option value unit:: bytes -Default value:: -1 -Applicable socket types:: all - - -ZMQ_MULTICAST_HOPS: Maximum network hops for multicast packets -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Sets the time-to-live field in every multicast packet sent from this socket. -The default is 1 which means that the multicast packets don't leave the local -network. - -[horizontal] -Option value type:: int -Option value unit:: network hops -Default value:: 1 -Applicable socket types:: all, when using multicast transports - - -ZMQ_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 -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. - -[horizontal] -Option value type:: int -Option value unit:: milliseconds -Default value:: -1 (infinite) -Applicable socket types:: all - - -ZMQ_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 -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. - -[horizontal] -Option value type:: int -Option value unit:: milliseconds -Default value:: -1 (infinite) -Applicable socket types:: all - - -ZMQ_IPV4ONLY: Use IPv4-only sockets -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Sets the underlying native socket type. A value of `1` will use IPv4 sockets, -while the value of `0` will use IPv6 sockets. An IPv6 socket lets -applications connect to and accept connections from both IPv4 and IPv6 hosts. - -[horizontal] -Option value type:: int -Option value unit:: boolean -Default value:: 1 (true) -Applicable socket types:: all, when using TCP transports. - - -RETURN VALUE ------------- -The _zmq_setsockopt()_ function shall return zero if successful. Otherwise it -shall return `-1` and set 'errno' to one of the values defined below. - - -ERRORS ------- -*EINVAL*:: -The requested 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. -*ENOTSOCK*:: -The provided 'socket' was invalid. -*EINTR*:: -The operation was interrupted by delivery of a signal. - - -EXAMPLE -------- -.Subscribing to messages on a 'ZMQ_SUB' socket ----- -/* Subscribe to all messages */ -rc = zmq_setsockopt (socket, ZMQ_SUBSCRIBE, "", 0); -assert (rc == 0); -/* Subscribe to messages prefixed with "ANIMALS.CATS" */ -rc = zmq_setsockopt (socket, ZMQ_SUBSCRIBE, "ANIMALS.CATS", 12); ----- - -.Setting I/O thread affinity ----- -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); -assert (rc); -rc = zmq_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); -assert (rc); -rc = zmq_bind (socket, "tcp://lo:5556"); -assert (rc); ----- - - -SEE ALSO --------- -linkzmq:zmq_getsockopt[3] -linkzmq:zmq_socket[3] -linkzmq:zmq[7] - - -AUTHORS -------- -The 0MQ documentation was written by Martin Sustrik and -Martin Lucina . diff --git a/doc/zmq_socket.txt b/doc/zmq_socket.txt deleted file mode 100644 index 39ddebf..0000000 --- a/doc/zmq_socket.txt +++ /dev/null @@ -1,347 +0,0 @@ -zmq_socket(3) -============= - - -NAME ----- -zmq_socket - create 0MQ socket - - -SYNOPSIS --------- -*void *zmq_socket (void '*context', int 'type');* - - -DESCRIPTION ------------ -The 'zmq_socket()' function shall create a 0MQ 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 -endpoint must be created for accepting incoming connections with -linkzmq:zmq_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_. - -0MQ 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. - -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. - -.Thread safety -0MQ '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 -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: - - -Request-reply pattern -~~~~~~~~~~~~~~~~~~~~~ -The request-reply pattern is used for sending requests from a _client_ to one -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 -receive replies from a _service_. This socket type allows only an alternating -sequence of _zmq_send(request)_ and subsequent _zmq_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 -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 -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' -Send/receive pattern:: Send, Receive, Send, Receive, ... -Outgoing routing strategy:: Load-balanced -Incoming routing strategy:: Last peer -ZMQ_HWM option action:: Block - - -ZMQ_REP -^^^^^^^ -A socket of type 'ZMQ_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 -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 -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' -Send/receive pattern:: Receive, Send, Receive, Send, ... -Incoming routing strategy:: Fair-queued -Outgoing routing strategy:: Last peer -ZMQ_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 -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 -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 -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' -Send/receive pattern:: Unrestricted -Outgoing routing strategy:: Load-balanced -Incoming routing strategy:: Fair-queued -ZMQ_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 -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 -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' -Send/receive pattern:: Unrestricted -Outgoing routing strategy:: See text -Incoming routing strategy:: Fair-queued -ZMQ_HWM option action:: Drop - - -Publish-subscribe pattern -~~~~~~~~~~~~~~~~~~~~~~~~~ -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. -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. - -When a 'ZMQ_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. - -[horizontal] -.Summary of ZMQ_PUB characteristics -Compatible peer sockets:: 'ZMQ_SUB', 'ZMQ_XSUB' -Send/receive pattern:: Send only -Incoming routing strategy:: N/A -Outgoing routing strategy:: Fan out -ZMQ_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 -implemented for this socket type. - -[horizontal] -.Summary of ZMQ_SUB characteristics -Compatible peer sockets:: 'ZMQ_PUB', 'ZMQ_XPUB' -Send/receive pattern:: Receive only -Incoming routing strategy:: Fair-queued -Outgoing routing strategy:: N/A -ZMQ_HWM option action:: Drop - - -ZMQ_XPUB -^^^^^^^^ -Same as ZMQ_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' -Send/receive pattern:: Send messages, receive subscriptions -Incoming routing strategy:: N/A -Outgoing routing strategy:: Fan out -ZMQ_HWM option action:: Drop - - -ZMQ_XSUB -^^^^^^^^ -Same as ZMQ_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' -Send/receive pattern:: Receive messages, send subscriptions -Incoming routing strategy:: Fair-queued -Outgoing routing strategy:: N/A -ZMQ_HWM option action:: Drop - - -Pipeline pattern -~~~~~~~~~~~~~~~~ -The pipeline pattern is used for distributing data to _nodes_ arranged in -a pipeline. Data always flows down the pipeline, and each stage of the pipeline -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 -to downstream pipeline _nodes_. Messages are load-balanced to all connected -downstream _nodes_. The _zmq_recv()_ function is not implemented for this -socket type. - -When a 'ZMQ_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 -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' -Direction:: Unidirectional -Send/receive pattern:: Send only -Incoming routing strategy:: N/A -Outgoing routing strategy:: Load-balanced -ZMQ_HWM option action:: Block - - -ZMQ_PULL -^^^^^^^^ -A socket of type 'ZMQ_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 -this socket type. - -[horizontal] -.Summary of ZMQ_PULL characteristics -Compatible peer sockets:: 'ZMQ_PUSH' -Direction:: Unidirectional -Send/receive pattern:: Receive only -Incoming routing strategy:: Fair-queued -Outgoing routing strategy:: N/A -ZMQ_HWM option action:: N/A - - -Exclusive pair pattern -~~~~~~~~~~~~~~~~~~~~~~ -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 -time. No message routing or filtering is performed on messages sent over a -'ZMQ_PAIR' socket. - -When a 'ZMQ_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 -becomes available for sending; messages are not discarded. - -NOTE: 'ZMQ_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' -Direction:: Bidirectional -Send/receive pattern:: Unrestricted -Incoming routing strategy:: N/A -Outgoing routing strategy:: N/A -ZMQ_HWM option action:: Block - - -RETURN VALUE ------------- -The _zmq_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. - - -ERRORS ------- -*EINVAL*:: -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. -*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] - - -AUTHORS -------- -The 0MQ documentation was written by Martin Sustrik and -Martin Lucina . 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 and -Martin Lucina . diff --git a/doc/zmq_tcp.txt b/doc/zmq_tcp.txt deleted file mode 100644 index f5499d3..0000000 --- a/doc/zmq_tcp.txt +++ /dev/null @@ -1,162 +0,0 @@ -zmq_tcp(7) -========== - - -NAME ----- -zmq_tcp - 0MQ 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. - - -ADDRESSING ----------- -A 0MQ 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. - - -Assigning a local address to a socket -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -When assigning a local address to a socket using _zmq_bind()_ with the 'tcp' -transport, the 'endpoint' shall be interpreted as an 'interface' followed by a -colon and the TCP port number to use. - -An 'interface' may be specified by either of the following: - -* The wild-card `*`, meaning all available interfaces. -* The primary IPv4 or IPv6 address assigned to the interface, in its numeric - representation. -* The interface name as defined by the operating system. - -NOTE: Interface names are not standardised in any way and should be assumed to -be arbitrary and platform dependent. On Win32 platforms no short interface -names exist, thus only the primary IP address may be used to specify an -'interface'. - -Connecting a socket -~~~~~~~~~~~~~~~~~~~ -When connecting a socket to a peer address using _zmq_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. - -A 'peer address' may be specified by either of the following: - -* The DNS name of the peer. -* The IPv4 or IPv6 address of the peer, in it's numeric representation. - - -WIRE FORMAT ------------ -0MQ 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. - -For frames with a 'payload length' not exceeding 254 octets, the 'payload -length' shall be encoded as a single octet. The minimum valid 'payload length' -of a frame is 1 octet, thus a 'payload length' of 0 octets is invalid and such -frames SHOULD be ignored. - -For frames with a 'payload length' exceeding 254 octets, the 'payload length' -shall be encoded as a single octet with the value `255` followed by the -'payload length' represented as a 64-bit unsigned integer in network byte -order. - -The 'flags' field consists of a single octet containing various control flags: - -Bit 0 (MORE): _More message parts to follow_. A value of 0 indicates that there -are no more message parts to follow; or that the message being sent is not a -multi-part message. A value of 1 indicates that the message being sent is a -multi-part message and more message parts are to follow. - -Bits 1-7: _Reserved_. Bits 1-7 are reserved for future expansion and MUST be -set to zero. - -The following ABNF grammar represents a single 'frame': - -.... - frame = (length flags data) - length = OCTET / (escape 8OCTET) - flags = OCTET - escape = %xFF - data = *OCTET -.... - -The following diagram illustrates the layout of a frame with a 'payload length' -not exceeding 254 octets: - -.... -0 1 2 3 -0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Payload length| Flags | Message body ... | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Message body ... -+-+-+-+-+-+-+- ... -.... - -The following diagram illustrates the layout of a frame with a 'payload length' -exceeding 254 octets: - -.... -0 1 2 3 -0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| 0xff | Payload length ... | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Payload length ... | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Payload length| Flags | Message body ... | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Message body ... -+-+-+-+-+-+-+-+ ... -.... - - -EXAMPLES --------- -.Assigning a local address to a socket ----- -/* TCP port 5555 on all available interfaces */ -rc = zmq_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"); -assert (rc == 0); -/* TCP port 5555 on the first Ethernet network interface on Linux */ -rc = zmq_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"); -assert (rc == 0); -/* Connecting using a DNS name */ -rc = zmq_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] - - -AUTHORS -------- -The 0MQ documentation was written by Martin Sustrik and -Martin Lucina . 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 and -Martin Lucina . 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 and -Martin Lucina . -- cgit v1.2.3