package require TclRingBuffer ?1.0?
ring attach ring-uri
ring get ring-uri ?type-list?
ring detach ring-uri
This package provides a mechanism for Tcl scripts to access data in ring buffers as a client. The package provides a command ensemble whose base command is ring. The subcommands are documented below
Attaches to the ringbuffer specified by the ring-uri.
The ring-uri is of the form:
tcp://hostname/ringname
Either the host localhost or the host name of the local system can be used to create a connection to a local ring without the need for a proxy ring.
Note that in the ring get and ring detach command below, the textually identical ring uri must be used to specify the same ring.
Blocks until a ring item is available on the ring specified by the
ring-uri. If selection-list
is present, it is a list of ring item type ids (as defined in the header
DataFormat.h), and all items whose type is not in the
list are skipped.
The ring items gotten is returned as a Tcl dict. See RING GET DICTS below for infomation about the keys and contents that appears in the dict from each type.
The ring-uri must be textually identical
to the ring-uri passed to a
ring attach commmand. For example
the URI's:
tcp://u6pc2.nscl.msu.edu/myring and
tcp://u6pc2/myring are not identical
(in the IP domain nscl.msu.edu).
Detaches from the ring specified by ring-uri once detached your script will throw an error if you attempt a ring get from that ring (unless you do another ring attach of course).
This section describes the dicts that are returned by the ring get command. NSCLDAQ-11.x ring items may or may not have a struture called a bodyheader. The bodyheader contains information used by the NSCLDAQ event builder.
If present in a ring item there will be a bodyheader key present in the dict returned by ring get. This dict will have the following key/values:
The value of this item is a long integer that contains the timestamp that says when the ring item was created. This is the high resolution timestamp used for event building, not the real time timestamp.
A timestamp value of -1 means that this ring item comes from a ring that will be input to an event builder and the data source wants the event builder to assign a timestamp equal to the latest timestamp seen in that item's input queue.
The value of this item is the id of the source that created this item.
The value associated with this key is the barrier type. A barrier type of 0 means the ring item was not submitted to the event builder as a barrier.
Barrier types are treated specially as event stream synchronization primitives. When a barrier is encountered at the head of a input queue, no further data is emitted from that queue until there is a barrier at the head of all input queues, at which time all barrier items are emitted.
All ring item dicts have a type key. The value of this key describes the ring item type.
State change items indicate that the run has undergone a state transition. These items are used to indicate a run has begun, ended, paused or resumed.
The key value pairs the dict returned for this ring item type are:
The ring item type. This will be a string containing one of Begin Run, End Run, Pause Run or Resume Run.
The value of this key is an integer run number.
The value of this key is an integer that is the number of seconds into the run at which this item was emitted.
The time at which the item was emitted. The Tcl clock format command can turn this value into a human readable date/time string.
Contains the run title string.
If present, the contents of this key are themselves a dict that describe the body header of the ring item as previously described.
These ring items have the following dict key/values:
Type of the item. This will be Scaler.
Together with the divisor value determines the time in floating point seconds relative to the start of the run of the start time of the begin of the interval represented by this scaler ring item.
Together with the divisor value determines the time in floating point seconds relative to the start of the run of the end of the interval represented by this scaler ring item.
The actual time at which this scaler item was produced. The Tcl command clock format can be used to turn this into a human readable date/time string.
The value of this key represents the time base for the start and end times. Doing a floating point division of these values by the divisor value gives time offsets in seconds relative to the start of the run.
The value of this key is 1 if the scalers are cleared as they are read or 0 if not.
The value of this key is a list of values of the scalers. You can use the Tcl llength command to determine how many scalers were read and pick off individual scalers either using the foreach or lindex commands.
If present, the contents of this key are themselves a dict that describe the body header of the ring item as previously described.
String list items contain a set of strings. The meaning of these strings depends on the actual item type. If the ring item contains monitored variables, each string is a Tcl set command that, if executed will set the variable to the value at the time. If a Documented packate variable ring item, each string is a colon separated set of fields that describe a packet type that can appear in a event.
Contains a string that is the type of the item. This string is either Packet types or Monitored Variables
Together with the divisor determines when relative to the start of the run this item was emitted.
If you do a floating point division of timeoffset by the value of this key the result is the time in floating point seconds relative to the start of the run this item was emitted.
The actual time at which this scaler item was produced. The Tcl command clock format can be used to turn this into a human readable date/time string.
If present, the contents of this key are themselves a dict that describe the body header of the ring item as previously described.
Ring format items are intended to inform consumers of data which version of NSCLDAQ was used to produce a stream of data. In general they are the first item inserted into a ring by a data source provider each run (even before the begin run). These items never have a body header. They have the following fields"
The item type which is Ring Item format version
The format major version. For NSCLDAQ-11 this will be 11 If a major version changes, existing ring items may have a different shape. Thus it is not safe to interpet items with a major version of 12 with a program that was built for major version of 11.
The format minor version. For NSCLDAQ-11.0 this will be 0. Minor version changes mean that the existing ring format items will be readable by any program built against the major version libraries, but there might be additional ring item types an earlier format version might not know how to interpret (e.g. 11.0 programs can understand 11.1 items but there might be 11.1 items that don't exist in 11.0).
Physics events contain the data read in response to a trigger in the data acquisition system. These dicts have the following key/values:
The ring item type which will be Event.
Number of bytes in the event body.
The body of the event. This is a binary array that can be decoded in an application specific way using he binary scan command.
If present, the contents of this key are themselves a dict that describe the body header of the ring item as previously described.
The intermediate ring (if enabled) between the event orderer and event glom in the event builder pipeline normally contains what are called event builder fragments. If you do a ring get from one of these rings you could get one of those ring items.
The dict for an event builder fragment contains:
Contains the ring item type which is Event fragment
Contains the fragment timestamp from the event building clock. This is converted and treated as a uint64_t and becomes a Tcl long integer in order to retain the full value range.
Contains an integer that is the id of the source program.
Contains the barrier type. For a complete description of the barrier type, see the descdription of the bodyheader dict at the beginning of this section.
Contains the number of bytes in the payload of the fragment.
Contains the payload of the fragment. This is stored as a Tcl Byte array that can be decoded in an application specific manner using the binary scan command. Note that for fragments that come from NSCLDAQ data sources the payload will be a ring item with a form described by the DataFormat.h C header.
This ring item contains trigger count statistics. It is used by SpecTcl to compute the fraction of the data that has been analyzed by SpecTcl. This ring item is converted into a dict of the following form:
Contains the ring item type which is Trigger count
Together with divisor this value determines when relative to the start of the run this item was emitted.
Doing a floating point division of the timeoffset value by this value results in the floating point number of seconds from the start of the run at which this item was emitted.
A timestamp that represents the date and time at which this item was emitted. Use the Tcl clock format command to turn this into a human readable date and times string.
A long integer value that represents the number of triggers emitted by this source so far in this run. The data come from a uint64_t value and a long integer is used to capture the full possible range of values.
If present, the contents of this key are themselves a dict that describe the body header of the ring item as previously described.
Normally this key is not present in systems with only one event source.
This item is created by the glom stage of the event builder and documents the setting glom is using to organize data from the event ordering stage of the event building pipeline. It is put in a dict with the following key/value pairs:
The type of the ring item which for this is always Glom Parameters
This is 1 if glom is building events from its input fragments and 0 if it is just passing data through and not event building.
Contains the number of ticks that define a coincidence with respect to event building. This is only meaningful if isBuilding is non zero. If that condition is true then glom has glued together all fragments that are within this number of timestamp clock ticks of the oldest fragment of a consecutive list of fragments into a single output event.
A text string that describes how glom creates an output timestamp for an event from the fragments that make it up. The output timestamp is important if you are doing hierarchical (or multilevel) event building.
The value of this key can be one of: first : the timestamp is that of the oldest fragment). last : the timestamp is that of the newest fragment. average : the timestamp is that of the average timestamp in the fragment.