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 cons