42.2. How do I use it?

The TclRingBuffer package can be incorporated in your script by:

Here is a script fragment that takes care of this, assuming that you have sourced the daqsetup.bash into your shell:

lappend auto_path [file join $::env(DAQROOT) TclLibs]
package require TclRingBuffer

The package provides a new command ensemble named ring. The example below shows a typical initialization and event processing loop:

Example 42-1. Processing ring items in Tcl.

ring attach $someRingUri                    (1)
while {[continueProcessing]} {
  set item [ring get -timeout 5 $someRingUri $itemTypes] (2)
  if {$item ne {}} {
    processItem $item
  } else {
     puts "timed out"
ring detach $someRingUri                     (3)

This generic processing loop externalizes a test for completion in the continueProcessing command. The actual processing of ring items is also externalized in processItem. Here's a description of the use of the TclRingBuffer opackage in this script fragment.

This command attaches the ringbuffer specified by the URI in the variable named someRingUri. The URI is used to identify the ringbuffer for any commands that operate on the ring. The resources associated with the attached ring are looked up by exact textual matching of the ringbuffer (e.g. tcp://spdaq19/aring is considered a different ring from tcp://spdaq19.nscl.msu.edu/aring).
the ring get command blocks until a ring items is available from the ring attached at someRingUri. Only ring items that match the type list in itemType are returned. The -timeout option is provided to timeout after 5 seconds. If the operation times out, then an empty string is returned. If this option is omitted, then the operation will block forever or until the desired item arrives.

The next matching ring items is translated to a dict (see the reference page for the structure of this dict) and and returned as the result of the ring get command.

Once processing is done, the ring is detached. Once detached, it is no longer available for use in a ring get command.

For reference information see: TclRingBuffer