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/xs_socket.txt | 347 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 347 insertions(+) create mode 100644 doc/xs_socket.txt (limited to 'doc/xs_socket.txt') diff --git a/doc/xs_socket.txt b/doc/xs_socket.txt new file mode 100644 index 0000000..217850f --- /dev/null +++ b/doc/xs_socket.txt @@ -0,0 +1,347 @@ +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 linkxs:xs_connect[3], or at least one +endpoint must be created for accepting incoming connections with +linkxs: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, publush-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 linkxs: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. + +[horizontal] +.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. + +[horizontal] +.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 +linkxs: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. + +[horizontal] +.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. + +[horizontal] +.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 linkxs: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. + +[horizontal] +.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 linkxs:xs_setsockopt[3] to +specify which messages to subscribe to. The _xs_send()_ function is not +implemented for this socket type. + +[horizontal] +.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. + +[horizontal] +.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. + +[horizontal] +.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 linkxs: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. + +[horizontal] +.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. + +[horizontal] +.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 + + +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 linkxs: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. + +[horizontal] +.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 +-------- +linkxs:xs_init[3] +linkxs:xs_setsockopt[3] +linkxs:xs_bind[3] +linkxs:xs_connect[3] +linkxs:xs_send[3] +linkxs:xs_recv[3] +linkxs:xs[7] + + +AUTHORS +------- +The Crossroads documentation was written by Martin Sustrik +and Martin Lucina . -- cgit v1.2.3