2.2. Creating an event segment

Event segments are software components that manage the dgitizers associated with a logical part of your experiment. You can create an arbitrary number of event segments and control the order in which they are read. The abstraction of event segments supports the fact that experiments may be composed of re-usable detector subsystems and systems.

At the NSCL for example: One might run an experiment using the SeGA gamma ray spectrometer and the S800 spectrograph. One way to do this is to have a re-usable event segment for the S800, another for SeGA and to register them both with the readout framework to build the experiment.

Event segments are instances of classes (objects) that are derived from the class CEventSegment. This section will also describe the CEventPacket base class which is an event segment that wraps an event segment into an NSCL tagged packet.

The methods an event segment can implement are:

Enough theory already. Let's look at a sample implemetation of an event segment. First the header:

#include <stdint.h>   
#include <CEventSegment.h> 
class CAENcard;             


class CCAENEventSegment : public CEventSegment  
{
private:
  CAENcard*              m_pCard;              
public:
  CCAENEventSegment(uint32_t base, uint8_t id, int crate = 0); 
  ~CCAENEventSegment();


  virtual void   initialize();                      
  virtual void   clear();
  virtual size_t read(void* pBuffer, size_t maxwords);
private:
  bool haveEvent();
};

                

Lets look at the implementation (.cpp) file of the event segment a chunk at a time:

#include <config.h>      
#include "CCAENEventSegment.h" 

#include <CAENcard.h>    



#include <string>
#include <stdlib.h>
#include <iostream>
                  
                

The next code section we will look at contains the constructor and destructor of the event segment. The constructor is invoked when the event segment is created (usually in the Skeleton.cpp just prior to registration). The destructor is usually never invoked. However if you have some overarching event segment that, at initialization time, creates other event segments it contains, destructors may be called. In order to allow your code to be embedded in environments you don't initially anticipate, you should write correct constructors for all event segments.

CCAENEventSegment::CCAENEventSegment(uint32_t base, uint8_t id,
                                     int packet, int crate) :
  m_pCard(new CAENcard(id, 0, false, base))  
{

}

CCAENEventSegment::~CCAENEventSegment()
{
  delete m_pCard;   
}

                

Next lets look at the initialization code. In a production environment, this code might open a file and read some configuration data, using that data to figure out how to initialize the device. In keeping with showing the simplest code possible, we are going to hard code all configuration information.

void
CCAENEventSegment::initialize()
{
  m_pCard->reset();             
  sleep(2);
  for(int i =0; i < 32; i++) {  
    m_pCard->setThreshold(i, 0);
  }
  m_pCard->commonStart();          
  m_pCard->keepOverflowData();
  m_pCard->keepUnderThresholdData();
  m_pCard->setRange(0x1e);


}
                

The clear function is trivial:

CCAENEventSegment::clear()
{
  m_pCard->clearData();
}
                

The heart of the event segment is, of course, the code that reads out the module:

size_t
CCAENEventSegment::read(void* pBuffer, size_t maxwords)
{
  // Maximum number of words is 34*2:

  if (maxwords < 34*2 ) {          
    throw
      std::string(
      "CCAENEventSegment - insufficient buffers space for worst case event");
  }
  
  for (int i =0; i < 30; i++) {
    if(haveEvent()) break;            
  }
  int n = (m_pCard->readEvent(p))/sizeof(uint16_t); 


  return n; 
}
bool
CCAENEventSegment::haveEvent()     
{
  return m_pCard->dataPresent();
}

                

Before leaving the subject of event segments for the scaler readout, I want to touch on two other important classes you can use to help you organize your code:

Let's look at a simple example of a compound event segment. Earlier in this section, we've built a class; CCAENEventSegment that encapsulated a CAEN 32 channel TDC. Suppose we had an experiment that consisted of several of these TDCs (I know it's a bad example but it prevents me from having to build additional event segments and all I really want to show is the mechanics of using compound event segments.)

We might have code the builds a Compound event segment as follows:

...
    // Create a few CCAENEventSegment objects:
    CCAENEventSegment tdc1(0x10000000, 1);
    CCAENEventSegment tdc2(0x10010000, 2);
    CCAENEventSegment tdc3(0x10020000, 3);
    
    // Create a compound event segment that reads out tdc1, tdc2, tdc3 in order:
    
    CCompoundEventSegment tdcs;
    tdcs.AddEventSegment(&tdc1);
    tdcs.AddEventSegment(&tdc2);
    tdcs.AddEventSegment(&tdc3);
...
                

The key to this example is that a CCompoundEventSegment has a method named AddEventSegment whose parameter is a pointer to an existing event segment. This creates an ordered list of event segments.

Since a CCompoundEventSegment is itself an event segment it can be added to another CCompoundEventSegment as well. Continuing the example above:

...
      // Assume we've made more event segments named adcs and qdcs:
      
      CCompoundEventSegment myDetector;
      myDetector.AddEventSegment(&tdcs);
      myDetector.AddEventSegment(&adcs);
      myDetector.AddEventSegment(&qdcs);
...
                

The event segment hierarchy you build up can be as deep as you need to capture the needs of your detector system.

Suppose now that myDetector in the previous example is a know NSCL detector that has been assigned a packet id of 0x1234. We can now create an event segment that wraps our detector in that packet by using a CEventPacket as follows:

...
    CEventPacket myDetectorPacket(myDetector, 0x1234,
                                    "My  Detector",
                                    "Packet for the My Detector device"
                                    "V1.0");
                

It's pretty easy to understand what the first two parameters are, a reference to an event packet and the tag. The remaining information are bundled into a documentation event emitted at the start of run that describe the set of event packets that you can expect to see in the run. Each documenation event contains a set of strings, one for each packet you created. Each string is a colon separated set of fields consisting of the short name of the packet (My Detector above), The stringified packet id (0x1234) as a hexadecimal, a long name of the packet (Packet for the My Detector device above), and a packet version which should be changed whenever the format of the packet changes (V1.0 in the example above), and the date and time the packet object was constructed (e.g. Tue Oct 18 15:32:20 2011).

If you want to see what the description string looks like, you can call the Format method of the CEventPacket object.