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

FreeBSD Manual Pages

  
 
  

home | help
XS_SOCKET(3)		     Crossroads	I/O Manual		  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 xs_connect(3), or at least
       one endpoint must be created for	accepting incoming connections with
       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,
       publish-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 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.

	   Table 1. 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.

	   Table 2. 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 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.

	   Table 3. 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.

	   Table 4. 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 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.

	   Table 5. 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
	   xs_setsockopt(3) to specify which messages to subscribe to. The
	   xs_send() function is not implemented for this socket type.

	   Table 6. 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.

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

	   Table 8. 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 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.

	   Table 9. 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.

	   Table 10. 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

   Survey pattern
       Survey pattern can be used to post a survey to a	set of notes and
       collect responses from them. The	survey is distributed from surveyor to
       all connected respondents. Responses are	routed back to the original
       surveyor.

       XS_SURVEYOR
	   XS_SURVEYOR socket type can be used to send surveys to all
	   respondents in the topology and receive the replies from all	of
	   them. Each survey sent is distributed to all	connected peers, and
	   incoming replies are	fair-queue. As you don't know the number of
	   respondents in the topology you don't know the number of responses
	   you are going to get, therefore you should use XS_SURVEY_TIMEOUT
	   socket option to set	the deadline for the survey.

	   Table 11. Summary of	XS_SURVEYOR characteristics
	   Compatible peer sockets     XS_RESPONDENT,
				       XS_XRESPONDENT

	   Direction		       Bidirectional

	   Send/receive	pattern	       Send one	message, receive
				       many messages.

	   Incoming routing strategy   Fair-queued

	   Outgoing routing strategy   Fan out

	   XS_HWM option action	       Drop

       XS_RESPONDENT
	   This	socket type receives surveys from surveyors and	sends
	   responses. Incoming surveys are fair-queued.	Outgoing responses are
	   routed back to the original surveyor.

	   Table 12. Summary of	XS_RESPONDENT characteristics
	   Compatible peer sockets     XS_SURVEYOR, XS_XSURVEYOR

	   Direction		       Bidirectional

	   Send/receive	pattern	       Receive a survey, send one
				       response.

	   Incoming routing strategy   Fair-queued

	   Outgoing routing strategy   Last peer

	   XS_HWM option action	       Drop

       XS_XSURVEYOR
	   A socket of type XS_XSURVEYOR is a socket type underlying
	   XS_SURVEYOR.	It doesn't impose the strict order of sends and	recvs
	   as XS_SURVEYOR does and it is intended for use in intermediate
	   devices in survey topologies.

	   Table 13. Summary of	XS_XSURVEYOR characteristics
	   Compatible peer sockets     XS_RESPONDENT,
				       XS_XRESPONDENT

	   Direction		       Bidirectional

	   Send/receive	pattern	       Send surveys, receive
				       responses.

	   Incoming routing strategy   Fair-queued

	   Outgoing routing strategy   Fan out

	   XS_HWM option action	       Drop

       XS_XRESPONDENT
	   A socket of type XS_XRESPONDENT is a	socket type underlying
	   XS_RESPONDENT. It doesn't impose the	strict order of	sends and
	   recvs as XS_RESPONDENT does and it is intended for use in
	   intermediate	devices	in survey topologies.

	   Incoming surveys are	fair-queued. Each survey is prefixed by	a
	   message part	identifying the	surveyor it was	received from.
	   Outgoing responses are routed to the	original surveyor based	on the
	   first message part.

	   Table 14. Summary of	XS_XRESPONDENT characteristics
	   Compatible peer sockets     XS_SURVEYOR, XS_XSURVEYOR

	   Direction		       Bidirectional

	   Send/receive	pattern	       Receive surveys,	send
				       responses.

	   Incoming routing strategy   Fair-queued

	   Outgoing routing strategy   See text

	   XS_HWM option action	       Drop

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

	   Table 15. 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
       xs_init(3) xs_setsockopt(3) xs_bind(3) xs_connect(3) xs_send(3)
       xs_recv(3) xs(7)

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

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_SOCKET(3)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | SEE ALSO | AUTHORS | NOTES

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

home | help