'\" t
.\"     Title: xs
.\"    Author: [see the "AUTHORS" section]
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
.\"      Date: 06/13/2012
.\"    Manual: Crossroads I/O Manual
.\"    Source: Crossroads I/O 1.2.0
.\"  Language: English
.\"
.TH "XS" "7" "06/13/2012" "Crossroads I/O 1\&.2\&.0" "Crossroads I/O Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
xs \- Crossroads I/O, a lightweight messaging layer
.SH "SYNOPSIS"
.sp
\fB#include <xs/xs\&.h>\fR
.sp
\fBcc\fR [\fIflags\fR] \fIfiles\fR \fB\-lxs\fR [\fIlibraries\fR]
.SH "DESCRIPTION"
.sp
Crossroads I/O is a library for building scalable and high performance distributed applications\&. It fits between classic BSD sockets, JMS/AMQP\-style message queues, and enterprise message\-oriented middleware\&.
.sp
Crossroads I/O extends the standard socket interfaces with features traditionally provided by specialised \fImessaging middleware\fR products\&. Crossroads sockets provide an abstraction of asynchronous \fImessage queues\fR, multiple \fImessaging patterns\fR, message filtering (\fIsubscriptions\fR), seamless access to multiple \fItransport protocols\fR and more\&.
.sp
Crossroads I/O provides a native C API for applications\&. Support for many more languages is provided by the community through language bindings which can be found at the Crossroads website\&.
.sp
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\&.
.SS "Context"
.sp
Before using any Crossroads library functions the caller must initialise a \fIcontext\fR using \fIxs_init()\fR\&. The following functions are provided to handle initialisation and termination of a \fIcontext\fR:
.PP
Initialise Crossroads context
.RS 4

\fBxs_init\fR(3)
.RE
.PP
Terminate Crossroads context
.RS 4

\fBxs_term\fR(3)
.RE
.PP
Set Crossroads context options
.RS 4

\fBxs_setctxopt\fR(3)
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBThread safety\fR
.RS 4
.sp
A \fIcontext\fR 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\&.
.sp
The individual \fIsockets\fR within a \fIcontext\fR are \fInot\fR thread safe \(em applications may \fInot\fR use a single \fIsocket\fR concurrently from multiple threads\&.
.sp
A \fIsocket\fR \fImay\fR be \fImigrated\fR from one thread to another, by issuing a full memory barrier between individual calls on the \fIsocket\fR\&. For example, this means applications can create a socket in one thread with \fIxs_socket()\fR and then pass it to a \fInewly created\fR thread as part of thread initialization via a structure passed as an argument to \fIpthread_create()\fR\&.
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBMultiple contexts\fR
.RS 4
.sp
Multiple \fIcontexts\fR 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\&.
.RE
.SS "Messages"
.sp
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\&.
.sp
Applications using the Crossroads library send and receive messages directly from/to buffers provided by the application, using the Crossroads functions \fIxs_send()\fR and \fIxs_recv()\fR\&.
.sp
Alternatively, applications desiring zero\-copy messaging and/or reference counted allocation of messages can use the message handling functions described in this section, and send and receive messages using \fIxs_sendmsg()\fR and \fIxs_recvmsg()\fR respectively\&. These two approaches are interchangeable\&.
.sp
The following functions are provided to work with messages using zero\-copy and/or reference\-counted allocation of messages:
.PP
Initialise a message
.RS 4

\fBxs_msg_init\fR(3)
\fBxs_msg_init_size\fR(3)
\fBxs_msg_init_data\fR(3)
.RE
.PP
Release a message
.RS 4

\fBxs_msg_close\fR(3)
.RE
.PP
Access message content
.RS 4

\fBxs_msg_data\fR(3)
\fBxs_msg_size\fR(3)
.RE
.PP
Message manipulation
.RS 4

\fBxs_msg_copy\fR(3)
\fBxs_msg_move\fR(3)
.RE
.PP
Retrieve message option
.RS 4

\fBxs_getmsgopt\fR(3)
.RE
.SS "Sockets"
.sp
Crossroads sockets present an abstraction of a asynchronous \fImessage queue\fR, with the exact queueing semantics depending on the socket type in use\&. See \fBxs_socket\fR(3) for the socket types provided\&.
.sp
The following functions are provided to work with sockets:
.PP
Creating a socket
.RS 4

\fBxs_socket\fR(3)
.RE
.PP
Closing a socket
.RS 4

\fBxs_close\fR(3)
.RE
.PP
Manipulating socket options
.RS 4

\fBxs_getsockopt\fR(3)
\fBxs_setsockopt\fR(3)
.RE
.PP
Creating and modifiying topologies
.RS 4

\fBxs_bind\fR(3)
\fBxs_connect\fR(3)
\fBxs_shutdown\fR(3)
.RE
.PP
Sending and receiving messages
.RS 4

\fBxs_send\fR(3)
\fBxs_recv\fR(3)
.RE
.PP
Sending and receiving messages (zero\-copy)
.RS 4

\fBxs_sendmsg\fR(3)
\fBxs_recvmsg\fR(3)
.RE
.PP
\fBInput/output multiplexing\fR. Crossroads provides a mechanism for applications to multiplex input/output events over a set containing both Crossroads sockets and standard sockets\&. This mechanism mirrors the standard
\fIpoll()\fR
system call, and is described in detail in
\fBxs_poll\fR(3)\&.
.SS "Transports"
.sp
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\&.
.sp
The following transport mechanisms are provided:
.PP
Unicast transport using TCP
.RS 4

\fBxs_tcp\fR(7)
.RE
.PP
Reliable multicast transport using PGM
.RS 4

\fBxs_pgm\fR(7)
.RE
.PP
Local inter\-process communication transport
.RS 4

\fBxs_ipc\fR(7)
.RE
.PP
Local in\-process (inter\-thread) communication transport
.RS 4

\fBxs_inproc\fR(7)
.RE
.SH "ERROR HANDLING"
.sp
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 \fIerrno\fR variable\&.
.sp
On non\-POSIX systems some users may experience issues with retrieving the correct value of the \fIerrno\fR variable\&. The \fIxs_errno()\fR function is provided to assist in these cases; for details refer to \fBxs_errno\fR(3)\&.
.sp
The \fIxs_strerror()\fR function is provided to translate Crossroads\-specific error codes into error message strings; for details refer to \fBxs_strerror\fR(3)\&.
.SH "MISCELLANEOUS"
.sp
The following miscellaneous functions are provided:
.PP
Report Crossroads library version
.RS 4

\fBxs_version\fR(3)
.RE
.SH "LANGUAGE BINDINGS"
.sp
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\&.
.SH "ZEROMQ COMPATIBILITY"
.sp
The Crossroads library provides an optional drop\-in \fIlibzmq\fR compatibility library for ZeroMQ applications\&. See \fBxs_zmq\fR(7) for documentation on this option\&.
.SH "AUTHORS"
.sp
The Crossroads documentation was written by Martin Sustrik <\m[blue]\fBsustrik@250bpm\&.com\fR\m[]\&\s-2\u[1]\d\s+2> and Martin Lucina <\m[blue]\fBmartin@lucina\&.net\fR\m[]\&\s-2\u[2]\d\s+2>\&.
.SH "COPYING"
.sp
Free use of the Crossroads library 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 libxs distribution\&.
.sp
As a special exception, the copyright holders of libxs grant you the right to link the library statically with your software\&. Refer to the end of the COPYING\&.LESSER file included with the libxs distribution for details\&.
.SH "NOTES"
.IP " 1." 4
sustrik@250bpm.com
.RS 4
\%mailto:sustrik@250bpm.com
.RE
.IP " 2." 4
martin@lucina.net
.RS 4
\%mailto:martin@lucina.net
.RE