package require TclRingBuffer
ringbuffer attach ring-uri
set item [ringbuffer get ?-timeout secs? 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. The optional
type-list limits the types
of ring items returned. The type list is a list of integer
item types. If the -timeout is provided to the
get subcommand, the operation will block
at most that many seconds. If a ring item is not read after the
timeout, an empty string is returned.
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.
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.
Provides the number of ticks in timeoffset in a second. This provides support for sub second timing resolution.
Uses the timeoffset and divisor values and returns the offset into the run as floating point seconds.
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.
Provides the original data source id that created this state change item. There is a source id in the body header, however the event builder pipeline will, in general edit that. This key provides the original source id and is immune from that editing.
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.
The counting interval start offset into the run in floating point seconds.
The counting interval end offset into the run in floating point seconds.
Boolean flag that is true if the scalers are incremental (cleared when latched/read) or false if not.
The original source id of the scaler item. While there is a source id in the body header, that is subject to editing by event builder piplines the item may have flowed through. This key provides a source id that is immune to that editing.
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.
The offset into the run in floating point seconds.
A unix time stamp value specifying when the item was emitted. This can be passed to clock format to get a date/time string.
The id of the original source that generated this item. While there is a source id in the body header, it is subject to editing by any event pipelines this item has flowed through. This key provides the authoritative source id for this item immune to event builder pipeline editing.
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 offset into the run at which this item was generated in floating point seconds.
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). Note that this is a wide integer (generated from a 64 bit source).
The id of the data source that generated this item. Note that while the body header contains a source id, it could have been edited by any event building pipelines the item flowed through. The value of this key is not subject to that sort of editing.
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.