Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
XS(7)			     Crossroads	I/O Manual			 XS(7)

NAME
       xs - Crossroads I/O, a lightweight messaging layer

SYNOPSIS
       #include	<xs/xs.h>

       cc [flags] files	-lxs [libraries]

DESCRIPTION
       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.

       Crossroads I/O 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.

       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.

       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

	   xs_init(3)

       Terminate Crossroads context

	   xs_term(3)

       Set Crossroads context options

	   xs_setctxopt(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.

	   The individual sockets within a context are not thread safe --
	   applications	may not	use a single socket concurrently from multiple
	   threads.

	   A socket may	be migrated from one thread to another,	by issuing a
	   full	memory barrier between individual calls	on the socket. For
	   example, 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 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.

   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.

       Applications using the Crossroads library send and receive messages
       directly	from/to	buffers	provided by the	application, using the
       Crossroads functions xs_send() and xs_recv().

       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 xs_sendmsg() and xs_recvmsg() respectively. These two approaches
       are interchangeable.

       The following functions are provided to work with messages using
       zero-copy and/or	reference-counted allocation of	messages:

       Initialise a message

	   xs_msg_init(3) xs_msg_init_size(3) xs_msg_init_data(3)

       Release a message

	   xs_msg_close(3)

       Access message content

	   xs_msg_data(3) xs_msg_size(3)

       Message manipulation

	   xs_msg_copy(3) xs_msg_move(3)

       Retrieve	message	option

	   xs_getmsgopt(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 xs_socket(3)	for the	socket types provided.

       The following functions are provided to work with sockets:

       Creating	a socket

	   xs_socket(3)

       Closing a socket

	   xs_close(3)

       Manipulating socket options

	   xs_getsockopt(3) xs_setsockopt(3)

       Creating	and modifiying topologies

	   xs_bind(3) xs_connect(3) xs_shutdown(3)

       Sending and receiving messages

	   xs_send(3) xs_recv(3)

       Sending and receiving messages (zero-copy)

	   xs_sendmsg(3) xs_recvmsg(3)

       Input/output multiplexing. 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 poll() system call,	and is described in detail in
       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

	   xs_tcp(7)

       Reliable	multicast transport using PGM

	   xs_pgm(7)

       Local inter-process communication transport

	   xs_ipc(7)

       Local in-process	(inter-thread) communication transport

	   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 xs_errno(3).

       The xs_strerror() function is provided to translate Crossroads-specific
       error codes into	error message strings; for details refer to
       xs_strerror(3).

MISCELLANEOUS
       The following miscellaneous functions are provided:

       Report Crossroads library version

	   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.

ZEROMQ COMPATIBILITY
       The Crossroads library provides an optional drop-in libzmq
       compatibility library for ZeroMQ	applications. See xs_zmq(7) for
       documentation on	this option.

AUTHORS
       The Crossroads documentation was	written	by Martin Sustrik
       <sustrik@250bpm.com[1]> and Martin Lucina <martin@lucina.net[2]>.

COPYING
       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.

       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.

NOTES
	1. sustrik@250bpm.com
	   mailto:sustrik@250bpm.com

	2. martin@lucina.net
	   mailto:martin@lucina.net

Crossroads I/O 1.2.0		  04/29/2017				 XS(7)

NAME | SYNOPSIS | DESCRIPTION | ERROR HANDLING | MISCELLANEOUS | LANGUAGE BINDINGS | ZEROMQ COMPATIBILITY | AUTHORS | COPYING | NOTES

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=xs&sektion=7&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help