package require TclRingBuffer
ringbuffer attach ring-uri
set item [ringbuffer get ?-timeout seconds? ring-uri ?type-list?]
ringbuffer detach ring-uri
Provides Tcl scripts with access to ring buffer data. NSCLDAQ ring buffers are identified by Uniform Resource Identifiers (URI). These URIs are of the form: tcp://hostname/ringname.
A program wishing to get data from ring must first use the ringbuffer attach command to attach as a client to that ring. Once attached the ringbuffer get command gets data fromt he ring, blocking as needed. One can prevent blocking forever by specifying the -timeout option, which takes an argument of the number of seconds until timeout. The optional type-list limits the types of ring items returned. The type list is a list of integer item types. See the header DataFormat.h for the ring data types.
Once done with a ring, the script either exits, which automatically detaches all rings that have been attached, or explicitly uses the detach command to detach the ring.
The items returned by ring get are dicts that are descsribed in the RING ITEM DICT section below. The exception to this is that an empty string is returned when the operation times out.
Ring items returned by the ringitem get command are decoded into dicts. All dicts contain a type key whose value is a textually encoded ring item type. Further more, if a ring item has a body header it has an additional key bodyheader whos value is a dict that contains three key value pairs: timestamp is the timestamp from the body header, source is an integer that identifies the data source and barrier is the barrier flag, nonzero if the item was an event builder barrier synchronization item and zero if not.
The remaining keys depend on the type of ring item>
These are types Begin, Pause, Resume, and End. The additional dict key/value pairs these item type have are:
The number of the run affected.
The number of seconds into the run at which this item was emitted.
The title of the run.
A unix timestamp that can, for example be passed to clock format to get date and time at which this item was emitted.
These items are of type Scaler. The additional key value pairs specific to this ring item are:
Number of seconds into the run at which the counting interval for this scaler item started. See divisor below, however.
Number of seconds into the run at which the counting interval ended. See divisor below, however.
A unix timestamp that indicates the absolute time at which this item was emitted. This can be passed to clock format to get a date/time string.
Applications can do fractional second timing. If so, this value is the what to divide the start and end offsets by to actually get seconds.
Boolean flag that is true if the scalers are incremental (cleared when latched/read) or false if not.
A list of the scaler values.
These are types Packet Types and Monitored Variables. The have the additional key value pairs:
Number of seconds into the run the item was emitted. See, however divisor below.
If the producer is using fractional timing, this is the value to divide the time offset by to get seconds again.
A unix time stamp value specifying when the item was emitted. This can be passed to clock format to get a date/time string.
A valid Tcl list of the strings in the item. The meanings of these strings depends on the actual item type.
This item type; Ring Item format version, describes the format of the data. It should be the first item emitted in a run. It contains the following key/value pairs
The major version of the format.
The minor version of the format.
This dict contains data acquired in response to accepted physics triggers. It contains the following items:
Number of bytes of data in the event body.
The body of the physics event as a byte array. Byte arrays can be decoded using the Tcl binary scan command. Byte arrays are used because, unlike other item types, we have no clues to the semantics of the body contents.
These represent event fragments. They can occur if you monitor a ring that is the direct output of the event orderer. Using the ReadoutGUI this is done by requesting a 'tee ring' and looking at it.
Event fragment dicts have the following key/value pairs:
The timestamp associated with the fragment. Note that event fragments don't ever have body headers.
Id of the source of this event.
Barrier type of the fragment. Nonzero values indicate the fragment cause a barrier synchronization of the event orderer's output while zero means the fragment is did not.
Number of bytes in the body of the fragment.
A byte array contaning the fragment body (payload). This byte arrays can be decoded using the Tcl binary scan command.
Of type Trigger count, these items provide gross statistics for the triggers seen by a data source. These are normally used by SpecTcl to determine the fraction of data analyzed online.
The following key/value pairs are used by this type:
Offset into the run at which this item was emitted.
Dividing timeoffset by this value yields the number of seconds into the run at which this item was emitted.
The unix time of day value at which this item was emitted. This can be passed to clock format to get a time/day string.
Number of triggers this source responded to this run (live trigers).
When the event builder pipeline is in use, the glom stage of the pipeline has a set of parameters it uses to determine how, or if to glue event fragments together to make an event. These parameters are documented in a ring item it emits at the start of each run.
The glom parameter item has the type Glom Parameters. It never has a body header and has the following key/value pairs:
Boolean value that is true if glom was told to build events and false if ont.
This only has meaning if isBuilding is true. In that case it is the width of the window in ticks that defines a coincidence.
Only meaningful if isBuilding is true, this value describes how timestamps are assigned to built events. If this value is first, the event timestamp is taken from the earliest fragment. If last, the timestamp is taken from the last fragment. Finally, if average, indicates the timestamp is the average of all fragments in the event.