4.3. The API and the gates dictionary

The SpecTcl class provides a family of creationals that allow you to create any of the types of gates SpecTcl supports and to add them to the gate dictionary.

Gates in SpecTcl are mutable. That is once defined a gate can be modified. This modification may change the gate type. In order to allow gate checking to be done without regard to this mutability, software that checks gates should hold CGateContainer objects rather than directly holding CGate objects.

CGateContainer objects provide an additional level of indirection. Linguistically , they look like pointers. What they point to, however, can be dynamically modified by SpecTcl. Thus a gate container that points to a specific named can be used to check that named gate regardless of changes that may have been made to that gate.

This means that if you create a gate and add it to the dictionary, rather than holding on to the CGate* object and checking that, you should, instead, then use FindGate to obtain a gate container that you can use to reference the new gate.

The example we're going to use demonstrates this; We're going to show how to create a parameter whose value reflects which of several gate (if any) an event satisfied. One use for this is to create a particle ID 1-d spectrum where the channels of the spectrum represent individual particle types.

Our example will implement an event processor that will:

• Create several gates and enter them into the gate dictionary so that the user can modify them. For simplicity, these will be cuts on a single parameter: raw.00.

• Obtain gate containers for the gates and put them in an std::vector of gate containers.

• Create a new tree parameter named PID.

• For each event, if at least one gate is satisfied, the PID tree parameter is given the index of the gate container for that gate in the vector.

	NOTE
	The discussion above means that our event processor must be placed in the event processing pipeline after all parameters have been set. This is because gates are evaluated on the parameters of the event, not on the raw event data.

Before turning to code, there's a bit more background that must be provided.

Gate evaluations get cached. That is once a gate is evaluated, a second evaluation just refers to the cached value. The event sink pipeline invalidates the cached values prior to each event. This is done so that costly gate evaluations are only done once even though there may be several compound gates that refer to them.

This is a problem because in order to improve program cache hit performance in SpecTcl, several events are run through the event processing pipeline before being passed on as a bunch to the evetn sink pipeline.

What this means for us is that we have to invalidate the cache for each gate each event manually in our event processor. If we don't our code will seem to run properly but we'll get runs of the same PID for groups of events where only the first event in each run is properly identified.

Let's look at the header for our event processor.

#ifndef GATEPROCESSOR_H
#define GATEPROCESSOR_H

#include <EventProcessor.h>
#include <TreeParameter.h>
#include <vector>

class CGateContainer;


class GateProcessor : public CEventProcessor
{
private:
  CTreeParameter m_pid;
  std::vector<CGateContainer*> m_gates;
public:
  GateProcessor();
  Bool_t OnInitialize();

  Bool_t operator()(const Address_t pEvent, CEvent& rEvent,
		    CAnalyzer& rAna, CBufferDecoder& rDec);
};

#endif

            

About the only thing I'm going to say about the header is that the constructor will create the tree parameter, but OnInitialize will be used to create the gates to ensure that enough of SpecTcl has been put together to support that operation.

The constructor is trivial:

#include "GateProcessor.h"
#include <SpecTcl.h>
#include <GateContainer.h>
#include <Gate.h>


GateProcessor::GateProcessor() :
  m_pid("PID")
{}

            

OnInitialize creates the gates, gets gate containers for them and builds the vector m_gates:

static const char* gateNames[] = {
  "Protons", "Deuterons", "Tritons", "3He", "Alphas", 0
};                                                
static float lows[] = {0, 100, 200, 300, 400};
static float highs[]  = {50, 150, 250, 350, 450};

static const char* pGateParam="raw.00";           

Bool_t
GateProcessor::OnInitialize()
{
  SpecTcl& api(*SpecTcl::getInstance());

  const char** pNames(gateNames);
  float* pLows(lows);
  float* pHighs(highs);

  while (*pNames) {
    CGate* pCut = api.CreateCut(pGateParam, *pLows, *pHighs); 
    api.AddGate(*pNames, pCut);                               

    CGateContainer* pContainer = api.FindGate(*pNames);       
    assert(pContainer);                   // Must have a matching container.

    m_gates.push_back(pContainer);                           
    
    pNames++;
    pLows++;
    pHighs++;
  }
  return kfTRUE;
}

            

This preparation makes the operator() relatively simple. We must

• Clear the cache in each gate via its stored gate container

• Loop over the gate containers asking each gate to check itself. If we find a match we can set the value of the PID parameter and exit the loop.

Here's the code for that:

Bool_t
GateProcessor::operator()(const Address_t pEvent, CEvent& rEvent,
			  CAnalyzer& rAnA, CBufferDecoder& rDecoder)
{
  for (int i = 0; i < m_gates.size(); i++) {
    CGateContainer& p(*(m_gates[i]));            
    p->Reset();                                   
    if ((*p)(rEvent)) {                              
      m_pid = i;                                     
      break;
    }
  }
  return kfTRUE;
}