Accessing TCL Variables from Event Processors

This application note describes how to access TCL variables from within SpecTcl event processors. Accessing TCL variables within event processors opens the door on a whole set of powerful applications for SpecTcl event processors. For example, variables can be used to gather statistics about calculations event processors are performing. Even more interesting, TCL Variables can be used to steer the calculations event processors perform. Boolean variables can switch on and off alternative sections of code. Numeric variables can parameterize other sections of code such as calibrations. Once variables have been established to communicate with event processors, Tk can be used to build application specific graphical user interfaces that control these variables.

TCL Variables can be accessed either by invoking API functions, or by linking C/C++ variables to the value of the TCL variable. If you will only be infrequently accessing a TCL variable value, the API approach is sufficient. If, however a variable will be accessed very frequently (for every event in an event processor for example), linking provides a zero overhead access to that variable.

This application note takes the form of a worked out example. The example creates and users four TCL Variables:

• BeginsSeen Is created and maintained using the TCL API interface. BeginsSeen will be statistic that shows how many Begin Run events have been processed by the event processor.
• KbytesProcessed is created using the TCL API interface, however it is linked to a member variable such that TCL scripts may read but not modify its value. KbytesProcessed will be a statistic that displays the number of kBytes of event data processed in this run. In order to allow Tk widget traces to operate, the API is used to fire traces when this variable is modified. Scaledowns can be used to ensure that this does not happen frequently if desired.
• Two variables, slope and offset are created and initialized via the API, and linked to class member variables. These two variables are used to steer the computation of a calibrated parameter from raw data.

Background Information

Background Information

To extend this example, you will need to become familiar with a few SpecTcl header files and the global storage that links the SpecTcl library together into the SpecTcl program. This section:

• Describes the global storage area and its header.
• Describes the headers you should become familiar with.

Global Storage

The global storage area is defined in the header Globals.h. The relevant storage for this discussion is a pointer to SpecTcl's histogramming engine. We will need to create a spectrum and make it known to the histogramming engine, as the histogramming engine also:

• Manages bindings with the displayer (Xamine)
• Contains the dictionary that the spectrum listing and manipulation commands use to locate spectra.

SpecTcl's event processing model is a pipeline. Each stage of the pipeline may contain other internal pipelines as well. The overall pipeline consists of the following elements:

• A data source (selected with the attach command).
• An analyzer that generates parameter sets for each event (this is a pipeline, containing your event processors as pipeline elements).
• An event sink. This is a pipeline as well that contains the Histogramming engine and any filters that have been defined.

The global storage area contains the following:

there are other variables defined in Globals.h however these are either not yet used or not useful to the application.

For this application, we will need gpInterpreter, a pointer to an object encapsulation of the TCL Interpreter.

Relevant Headers

• TCLInterpreter.h - The interface to the interpreter.
• TCLVariable.h - Encapsulates a variable.
• TCLList.h - Encapsulates TCL Lists.
• TCLProcessor.h - Base class for building and registering TCL commands.

The Event Processor

We will describe the following:

• The header file for a Sample Event Processor that will create and manipulate TCL Variables.
• The Implementation of the constructor and OnAttach.
• The implementation of OnBegin
• The Implementation of the operator() which processes events.

Our strategy will be as follows:

• The constructor will only set member data. We don't know when the constructor wll be called relative to the initialization of the intepreter. Building TCL Variables here is potentially dangerous.
• OnAttach creates the TCL Variables.
• OnBegin Handles BeginsProcessed, and other housekeeping chores.
• operator() uses slope and offset, and modifies KbytesProcessed.

The Header file

The key parts of the SampleProcessor Header file (SampleProcessor.h) are shown below:

 #ifndef __SAMPLEPROCESSOR_H
 #define __SAMPLEPROCESSOR_H

 // Headers I really need.

 #ifndef __EVENTPROCESSOR_H
 #include <EventProcessor.h>
 #endif

 #ifndef __HISTOTYPES_H
 #include <histotypes.h>
 #endif

 // Everything else I make a forward definition to minimize dependencies:
 // at compile time:

 class CAnalyzer;
 class CBufferDecoder;
 class CEvent;

 class SampleProcessor : public CEventProcessor
 {
 private:
  int    m_BeginsSeen;		//!< number of begin runs we've seen.
  int    m_nBytesProcessed;	//!< Number bytes of event data processed.
  int    m_nKbytesProcessed;	//!< Kbytes processed.
  double m_fSlope;		//!< Calibration slope.
  double m_fOffset;		//!< Calibration offset.

 public:
  SampleProcessor();
  Bool_t OnAttach(CAnalyzer&     rAnalyzer);
  Bool_t OnBegin(CAnalyzer&      rAnalyzer,
		 CBufferDecoder& rDecoder);

  Bool_t operator()(const Address_t pEvent,
		    CEvent& rEvent,
		    CAnalyzer& rAnalyzer,
		    CBufferDecoder& rDecoder); 
 private:
  void UpdateKbytes();
 };

 #endif

Notes:

• As much as possible forward definitions are used in preference to #include in header files. This reduces the chances of circular header depencency.
• The member variables are close match to the set of TCL Variables we will be managing.
• UpdateKbytes is a utility function that contains common code used by both OnBegin and operator() to ensure that traces set on KbytesProcessed will fire when we modify that variable.

The constructor and OnAttach

The constructor for SampleProcessor is shown below.

 // Header files:

 #include <config.h>

 #include "SampleProcessor.h"
 #include <Analyzer.h>
 #include <TCLAnalyzer.h>
 #include <BufferDecoder.h>
 #include <Event.h>

 #include <tcl.h>

 #include <TCLInterpreter.h>
 #include <TCLVariable.h>
 #include <Globals.h>

 #include <stdio.h>
 /*!
   The constructor will just initialize the member variables:
 */

 SampleProcessor::SampleProcessor() :
  m_BeginsSeen(0),
  m_nBytesProcessed(0),
  m_nKbytesProcessed(0),
  m_fSlope(1.0),
  m_fOffset(0.0)
 {
 }

Constructor notes:

• Since we don't know when the constructor is invoked relative to the startup of TCL/Tk it is not safe to create TCL variables in the constructor.
• Only variable initialization is done here.
• Variable names are hard coded.

OnAttach is run once, and at that time, we know that TCL is all set up and can be manipulated. Here we ensure all variables are created and have proper initial values. We link the linked variables to the TCL Variables as follows:

• m_fSlope is linked as a r/w double to "slope"
• m_fOffset is linked as a r/w double to "offset"
• m_nKbytesProcessed - is linked as an int, readonly by TCL to "KbytesProcessed"

 Bool_t
 SampleProcessor::OnAttach(CAnalyzer& rAnalyzer)
 {
  // This next step of finding the interpreter will be deprecated when
  // SpecTcl 3.0 is comissioned.

  CTCLInterpreter* pInterp = gpInterpreter;

  // Now create object encapsulations of the variables we care about
  // and set them to initial values:

  CTCLVariable BeginsSeen(pInterp, "BeginsSeen", kfFALSE);
  BeginsSeen.Set("0");
  
  CTCLVariable slope(pInterp, "slope", kfFALSE);
  slope.Set("1.0");

  CTCLVariable offset(pInterp, "offset", kfFALSE);
  offset.Set("0.0");

  CTCLVariable KbytesProcessed(pInterp, "KbytesProcessed", kfFALSE);
  KbytesProcessed.Set(0);

  // Link the variables to member data:

  slope.Link(&m_fSlope, TCL_LINK_DOUBLE);
  offset.Link(&m_fOffset, TCL_LINK_DOUBLE);

  KbytesProcessed.Link(&m_nKbytesProcessed, TCL_LINK_INT | TCL_LINK_READ_ONLY);

  return kfTRUE;
 }

Notes:

• The mechanism used to get the interpreter object pointer will be deprecated with the introduction of a formal API to the SpecTcl Internals in version 3.0.
• After deprecation, the global variable interface will be retained for approximately a year to allow users time to port their code to the API.
• The CTCLVariable class encapsulates a Tcl variable. CTCLVariable::Set is identical to a TCL set command except that no substitutions are performed on the value of the set.
• The CTCLVariable::Link function makes a connection between a TCL variable and a C/C++ variable as follows:
  • TCL set values are constrained to be compatible with the data type flag.
  • TCL set commands will modify the linked variable immediately.
  • TCL variable references will fetch the value from the linked variable.
  • TCL Traces set on the variable will only fire after the C/C++ program modifies the variable if the Tcl_UpdateLinkedVar function is called. Note that Tk widgets that have -variable and -textvariable options maintain their window contents via variable traces.
  • Tk widgets that modify variables will modify the linked C/C++ variable.
  • Using the TCL_LINK_READ_ONLY flag prevents the Tcl/Tk interpreter from modifying the value of the variable, only the C/C++ code can modify this variable.

OnBegin and utility functions.

On Begin is going to get the value of BeginsSeen, parse it as an integer, increment it and Set it. We could just set the value of m_BeginsSeen, but

• We want to demonstrate the Get member.
• The user may have modified/corrected BeginsSeen.

Error cases:

• The variable has been destroyed: Re-create it and set it to the correct number of begins.
• The variable does not parse as an int... Set it from our internal copy.
• The variable parses but does not match our idea of the number of begins: The variable value overrides our value.

 Bool_t 
 SampleProcessor::OnBegin(CAnalyzer& rAnalyzer, CBufferDecoder& rDecoder)
 {
  CTCLInterpreter* pInterp = gpInterpreter;

  CTCLVariable BeginsSeen(pInterp, "BeginsSeen", kfFALSE);
  const char*       pValue = BeginsSeen.Get();
  if(pValue) {			// The variable exists...
    int nCurrent;
    if(sscanf(pValue, "%d", &nCurrent)) { // It's an int.. override.
      m_BeginsSeen = nCurrent;
    }
    
  }
  // If we get to here we need to increment the value of m_BeginsSeen and
  // Set a new variable value.

  m_BeginsSeen++;
  char textVersion[100];
  sprintf(textVersion, "%d", m_BeginsSeen);
  BeginsSeen.Set(textVersion);

  // While we're at it we need to reset m_nKbytesProcessed and
  // trigger an update on it

  m_nBytesProcessed = 0;
  m_nKbytesProcessed = 0;
  UpdateKbytes();
 

  return kfTRUE;
 }

Notes:

• The CTCLVariable::Set function requires a character string, hence the sprintf's.
• The call to UpdateKbytes fires any necessary traces on KbytesProcessed (see below). This is required to ensure that any Tk widgets that are monitoring this variable get informed of its change.

This utility does the common work of ensuring that traces set on KbytesProcessed will fire: doing this requires a call to Tcl_UpdateLinkedVar which is not yet wrapped by the TCL++ library.

void SampleProcessor::UpdateKbytes() {

  CTCLInterpreter* pInterp = gpInterpreter;
  Tcl_Interp*      pI      = pInterp->getInterpreter(); // This next function is not
  Tcl_UpdateLinkedVar(pI,	                       // yet wrapped. 
		       "KbytesProcessed");

}

Note:

• The Tcl_UpdateLinkedVar function is a direct Tcl API function that is not yet wrapped by the TCL++ library.

operator()

Several assumptions:

• The events are fixed length events.
• There's at least a single parameter... right after the event size.
• The Byte order of event source is the same as ours.

Bool_t SampleProcessor::operator()(const Address_t pEvent,

			    CEvent& rEvent,
			    CAnalyzer& rAnalyzer,
			    CBufferDecoder& rDecoder)

  UShort_t* p    = static_cast<UShort_t*>(pEvent);

  UShort_t nSize = *p++ * sizeof(UShort_t);
  UShort_t Value = *p++;

  CTclAnalyzer& rA(static_cast<CTclAnalyzer&>(rAnalyzer));
  rA.SetEventSize(nSize);

  // Now the TCL fun begins: rEvent[0] - raw parameter.
  //                         rEvent[1] - Calibrated parameter:
  // m_fSlope and m_fOffset are maintained by TCL to reflect
  // the values of the slope/offset variables.
  //

  rEvent[0] = Value;
  rEvent[1] = static_cast<float>(Value)*m_fSlope + m_fOffset; 

  // report the statistics.  Each time a k clicks over, 
  // we increment the m_nKbytesProcessed and update the linked var.

  m_nBytesProcessed += nSize;
  if( (m_nBytesProcessed / 1024) != m_nKbytesProcessed) {
    m_nKbytesProcessed = m_nBytesProcessed / 1024;
    UpdateKbytes();
    
  }
 }

Notes:

• Since the variables m_fSlope and m_fOffset are linked, changes at the TCL script level will immediately affect the computation of the calibrated parameter.
• The technique used to fire the traces on KbytesProcessed can also be used to fire traces somewhat less frequently than a variable is actually modified. For example, suppose we wanted to link m_nBytesProcessed, we don't want the overhead of executing Tcl trace scripts for every event when typically these traces are used to manage the contents of Tk widges. We can make many changes to the linked variable and just fire the traces as often as needed to make the user interface appear like it's continuously updating. In the meantime, any script level processing that refers to the variable will get the value of the C/C++ variable.
• If we only care about maintaining GUI's we can, in fact, not call UpdateKbytes at all. Instead, the script can run an after proc that polls the variable for modification e.g.:

  label .l -textvariable kBytes
  # ... code to layout the label in the GUI omitted.

  proc UpdatekBytes {ms} {
       global KbytesProcessed
       global kBytes

       set kBytes $KbytesProcessed
       after $ms "UpdatekBytes $ms"
  }  
  UpdatekBytes 1000