The NSCL event builder consists of a two stage pipeline. The first stage accepts a set of event fragments from an arbitrary number of event sources and produces output that is a total ordering of the event fragments with respect to the value of a timestamp associated with each fragment. The synchronization of the source of this timstamp is beyond the scope of the event builder software as that normally must be done by the experimental hardware.
The event orderer stage operates as a TCP/IP server. Data sources follow a well defined protocol to connect with the server, send data and, eventually, disconnect from the server.
The server never initiates an interaction with the clients. Only clients initiate interactions through messages. Messages consist of a command segment followed by an optional data segment. The server responds to each message to indicate how the request has been processed.
Messages consist of a header followed by an optional body. The Headers are pure ASCII while the bodies consist of binary data. Each messages is descdribed fully in the next section: MESSAGES
The event orderer uses the NSCL port manager to advertise its presence. The service name used is "ORDERER"
Each subsection describes a specific message. Messages consist of a header and an optional body. The message type determines if there is a body. Each segment consist of a 32 bit little endian size followed by its contents. For headers, the contents are an ASCII string. For bodies, the contents are message specific. Messages that don't have bodies send a body size of 0.
The server replies to the client are fully textual. Each reply is a single line of text. The server replies are success and error replies:
Successful completion of the request.
The request failed. The text following the ERROR return is an English string that gives the reason for the failure.
See ERROR STRINGS below for the various failur reasons that have been anticipated.
Must be sent by the client immediately following a connection. The body contains contains a null terminated string that describes the connection. This is followed by a uint32_t count of the number of uint32_t items that follow and contain the source ids that will be carried across this connection.
This message causes a transition from the CONNECTING to the CONNECTED state.
Indicates an orderly, alarm free, disconnect of the client from the event builder. If the client simply closes the socket, the connection loss is considered abnormal, and alarms may be raised. Therefore clients should properly disconnect rather than just letting sockets close on exit e.g.
The body of the DISCONNECT message is empty. Note that the actual sequence the API software imposes is:
Send the DISCONNECT message.
Receive the OK message back from the server
Both close the socket. The server closes the socket as soon as the OK message has been sent. The client closes the socket as soon as the server reply message has been sent (note that in the future if the server can send an ERROR, the client will still close after recieving that reply).
A FRAGMENTS indicates the body is a set of fragments from the data source. Each fragment can be thought of as a header followed immediately by its payload. The payload itself is the event fragment. The header describes the payload. Note that the size of the body is still the first 32 bits in the entire body. It is followed immediately by the first header.
The header has the following structure:
typedef struct _PacketHeader {uint64_t s_timestamp;;uint32_t s_sourceId;;uint32_t s_size;; } PacketHeader, *pPacketHeader;
uint64_t s_timestamp;
The timestamp of the event fragment.
uint32_t s_sourceId;
The unique source id of the fragment. The sourceId is used to determine into which fragment queue the fragment is put. At this time it is required that data from each source id come in monotonic time order.
uint32_t s_size;
The number of bytes in the payload that follows this struct.
Connections have well defined states. The connection state changes due to a well defined set of events. If the state machine is violated, the server will disconnect from the client immediately without reporting an error.