Provided by: libxs-dev_1.2.0-1.1_amd64 bug

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