9.1.1. A framework for analyzing fragments from and event

Data from the NSCL event builder are ring items that with bodies that are composed of event fragments. Event Builder describes the structure of an event in detail. Each event fragment contains a header and a payload. Each payload is a ring item. Beginning with nscldaq-11.0 each ring item body can have a body header. Normally the event builder client software (CRingDataSource) uses the contents of this body header to build the fragment header. Thus there is some data repetition.

We want to provide a framework that knows as little as possible about the format of the underlying data so that we can be insensitive to changes in the data format as NSCLDAQ evolves. To maintain this insensitivity we're going to use two chunks of the NSCLDAQ API:

Our framework is going to accept a ring item. If the ring item is a PHYSICS_EVENT, it will iterate over the event builder fragments in the body. For each fragment, it will invoke an appropriate handler object, if registered. After iterating over all the fragments, it will invoke an end of event handler, if one is registered.

The idea is that each event fragment handler knows about the format of the data in its fragment. The end of event handler, if needed, can compute data that has been marshalled across all the fragment handlers.

The files that make up the framework are:

Let's look at the class definition for CRingItemDecoder (CRingItemDecoder.h).

class CRingItemDecoder {
private:
    std::map<std::uint32_t, CFragmentHandler*> m_fragmentHandlers; 
    CEndOfEventHandler* m_endHandler;                                    

public:
    void registerFragmentHandler(
        std::uint32_t sourceId, CFragmentHandler* pHandler             
    );
    void registerEndHandler(CEndOfEventHandler* pHandler);             
    void operator()(CRingItem* pItem);                                 

protected:

    void decodePhysicsEvent(CPhysicsEventItem* pItem);                
    void decodeOtherItems(CRingItem* pItem);                          
};
                

Let's look at the implementation source code (CRingItemDecoder.cpp). We'll divide this into:

• Examining code to establish handlers.

• Examining code that processes ring items (the function call operator and the methods it call).

...
void
CRingItemDecoder::registerFragmentHandler(std::uint32_t sourceId, CFragmentHandl
er* pHandler)
{
    m_fragmentHandlers[sourceId] = pHandler;         
}
...
void
CRingItemDecoder::registerEndHandler(CEndOfEventHandler* pHandler)
{
    m_endHandler = pHandler;                         
}


                    

void
CRingItemDecoder::operator()(CRingItem* pItem)
{
    std::uint32_t itemType = pItem->type();               
    CRingItem* pActualItem =
        CRingItemFactory::createRingItem(*pItem);         

    if (itemType == PHYSICS_EVENT) {
        CPhysicsEventItem* pPhysics =
            dynamic_cast<CPhysicsEventItem*>(pActualItem); 
        if (!pPhysics) {
            std::cerr << "Error item type was PHYSICS_EVENT but factory could no
t convert it";
            return;
        }
        decodePhysicsEvent(pPhysics);                  
    } else {
        decodeOtherItems(pActualItem);                 
    }
    delete pActualItem;                                
}

                    

void
CRingItemDecoder::decodeOtherItems(CRingItem* pItem)
{

    std::cout << pItem->toString() << std::endl; 
}

                    

void
CRingItemDecoder::decodePhysicsEvent(CPhysicsEventItem* pItem)
{
    if (! pItem->hasBodyHeader()) {                    
        std::cerr << "Warning - an event has no body header - won't be processed
\n";
        return;
    }

    std::uint64_t timestamp = pItem->getEventTimestamp();
    std::uint32_t srcid     = pItem->getSourceId();       
    std::uint32_t btype     = pItem->getBarrierType();
    
    
    

    FragmentIndex iterator(reinterpret_cast<std::uint16_t*>(pItem->getBodyPointer()));
    size_t  nFrags = iterator.getNumberFragments();

    for (size_t i = 0; i < nFrags; i++) {
        FragmentInfo f = iterator.getFragment(i);
        CFragmentHandler* h = m_fragmentHandlers[f.s_sourceId];  
        if (h) (*h)(f); 
    }

    if (m_endHandler) (*m_endHandler)(pItem);              
}
                    

9.1.2. Sample handlers for fragment types.

In this section we'll look at a pair of sample fragment handlers. Specifically, we'll look at fragment handlers for the S800 and CAESAR data acquisition systems as they were for the NSCL run in April of 2018.

In order to register fragment and end handlers, we need to set up a class hierarchy of polymorphic classes. This requires the definition of an abstract base class that defines a pure virtual method that concrete fragment handlers will implement.

The CRingItemDecoder class stores pointers to handlers. Dereferencing these pointers will invoke the actual virtual method of the implemented class.

These base classe are defined in CFragmentHandler.h, for fragment handlers and CEndOfEventHandler.h for the end of event handlers. Their definitions are trivial and both are shown below.

class CFragmentHandler {

public:
    virtual void operator()(FragmentInfo& frag) = 0;
};

class CEndOfEventHandler {

public:
    virtual void operator()(CRingItem* pItem) = 0;
};
                    
                

Fragment handler and end of event handler implementations must define and implement the function call operator (operator()), which is polymorphic over their class hierarcies.

Let's look at a trivial end of event handler's definition and implementation (definition in CMyEndOfEventHandler.h implementation in CMyEndOfEventHandler.cpp):

// CMyEndOfEventHandler.h:

class CMyEndOfEventHandler : public CEndOfEventHandler
{
public:
    void operator()(CRingItem* pItem);            
};

// CMyEndOfEventHandler.cpp:

void
CMyEndOfEventHandler::operator()(CRingItem* pItem)  
{
    std::cout << "--------------------End of Event -----------------------\n";
}
                

Before looking at the individual fragment handlers, let's step back and think about the structure of the data from the S800 and CAESAR. Both of these data acquisition systems, at the time, used tagged item formats. A tagged item is something very much like a ring item. A tagged item is an item with a size (self, inlcusive, units of uint16_t), a type, (16 bits), and a body that depends on the type.

Both systems produce an event that consists of a tagged item type with tagged items living inside of that outer item. While the item types and their contents differ between CAESAR and the S800, item identification and iteration over the subitems present does not.

As our fragment handlers will just make a formatted dump of the data (a very sketchy dump at that), we can imagine common methods for packet type to string lookup and iteration over the subpackets.

These are defined and implemented in PacketUtils.h (definition) and PacketUtils.cpp. The definition file contains:

namespace PacketUtils {
    std::uint16_t* nextPacket(std::uint16_t& nRemaining, std::uint16_t* here);
    std::string    packetName(
        std::uint16_t type, const std::map<std::uint16_t,
        std::string>& typeMap, const char* defaultName);
}

                

This header defines a namespace in which the utility functions will be isolated and two functions:

Armed with this, let's look at the CAESAR fragment handler first. CCAESARFragmentHandler.h has the class definition:

class CCAESARFragmentHandler : public CFragmentHandler
{
private:
    /**
     * maps packet ids to packet name strings.
     */
    std::map<std::uint16_t, std::string< m_packetNames; 
public:
    CCAESARFragmentHandler();

    void operator()(FragmentInfo& frag);
private:
    void timestampPacket(std::uint16_t* pPacket);            
};

                

This is about what we'd expect to see, a couple of points:

On to the implementation. We're not going to show the constructor, all that does is fill m_packetNames. Here's the operator() implementation:

void
CCAESARFragmentHandler::operator()(FragmentInfo& frag)
{
    std::cout << "==== CEASAR Fragment: \n";
    std::cout << "   Timestamp: " << frag.s_timestamp << std::endl;
    std::cout << "   Sourceid:  " << std::hex << frag.s_sourceId << std::dec << "(hex)\n";

    std::uint16_t* p = frag.s_itembody;                
    p += sizeof(std::uint32_t)/sizeof(std::uint16_t);   

    std::uint16_t remaining = *p++;                     
    std::uint16_t caesarType = *p++;                   
    remaining -= 2;                                     

    if (caesarType != 0x2300) {
        std::cout << " *** Error - CAESAR packet id should be 0x2300 but was: "
            << std::hex << caesarType << std::dec << std::endl;
        return;
    }
    p += 2;                                         
    remaining -= 2;

    while (p) {
        std::uint16_t subPktSize = *p;
        std::uint16_t subPktType = p[1];
                                                   
        std::string subPacketTypeName =
            PacketUtils::packetName(subPktType, m_packetNames, "Unknown");

        std::cout << "   Subpacket for " << subPacketTypeName << " " << subPktSize << " words long\n";

        if (subPktType == 0x2303) {
          timestampPacket(p);                    
        }

        p = PacketUtils::nextPacket(remaining, p);  
    }

}

                

9.1.3. A simple program that uses the framework.

This section shows how the framework can be used in a simple program. The program simply takes a stream of ring items from a data source (online or file) and invokes a CRingItemDecoder for each item as it arrives. The full source code is in Main.cpp.

This file includes a function usage which outputs simple help describing how to invoke the program. We're not going to show that function here. The program takes a single parameter which is the URI of a source of ring items. The URI can be a tcp URI to accept data from the online system or a file URI to accept data from file.

Here's the main function in Main.cpp

int
main(int argc, char**argv)
{
    if (argc != 2) {                      
        usage();
        std::exit(EXIT_FAILURE);
    }
    std::string uri(argv[1]);
    std::vector<uint16_t> sample = {PHYSICS_EVENT};   // means nothing from file.
    std::vector<uint16_t> exclude;                    // get all ring item types:

    CDataSource* pSource;
    try {
        pSource = CDataSourceFactory::makeSource(uri, sample, exclude); 
    }
    catch (...) {
        std::cerr << "Failed to open the data source.  Check that your URI is valid and exists\n";
        std::exit(EXIT_FAILURE);
    }

    CDataSource& source(*pSource);

    CRingItemDecoder       decoder;
    CS800FragmentHandler   s800handler;
    CCAESARFragmentHandler caesarhandler;        
    CMyEndOfEventHandler   endhandler;

    decoder.registerFragmentHandler(2, &s800handler);
    decoder.registerFragmentHandler(0x2300, &caesarhandler); 
    decoder.registerEndHandler(&endhandler);

    try {
        CRingItem* pItem;
        while (pItem = source.getItem()) {
            decoder(pItem);                         
            delete pItem;
        }
        if (errno != ESUCCESS) throw errno;         

        std::exit(EXIT_SUCCESS);
    }
    catch (int errcode) {                          

        std::cerr << "Ring item read failed: " << std::strerror(errcode) << std::endl;
        std::exit(EXIT_FAILURE);
    }
    catch (std::string msg) {
        std::cout << msg << std::endl;
        std::exit(EXIT_FAILURE);
    }                                             
    std::cerr << "BUG - control fell to the bottom of the main\n";
    std::exit(EXIT_FAILURE);
}

                

9.1.4. Suggestions for embedding the framework in SpecTcl or Root

It's reasonable to want to use this framework as a starting point for SpecTcl event processors that decode data from the event builder. Note that it's also reasonable to want to use this framework to unpack data read into Root. This section is going to outline mechanisms to do both with minimal code changes when switching from between SpecTcl and Root.

The key to doing this is, again separation of concerns. Analysis of data in either framework requires:

• Iterating over the event fragments in a ring item invoking processors for each fragment; RingItemDecoder does this.

• In each fragment processor, decoding the raw event structure of the fragment into a set of parameters.

• Making those decoded parameter available to the analysis framework (SpecTcl or Root).

Where almost all attempts to do this fall over is by combining the last two concerns into a single class (e.g. having event processors that directly fill in CTreeParameter objects while decoding raw data).

An approach that better separates concerns is to unpack the raw event fragments into some struct or other object that is independent of Root or SpecTcl in one class and then having classes for SpecTcl and Root that unpack that object in to tree parameters or trees.

SpecTcl's event processors offer a simple mechanism to do this. My recommendation is that at least three event processors be used to unpack raw data to tree parameters:

• The first event processor would be based on the framework described in this example. It would create structs or objects containing the raw parameters in the event.

• The second event processor would embed an object that would compute parameters that require more than one event fragment (for example timestamp differences). These too would go into a struct or object.

• The remaining event processor(s) would marshall data from these intermediate structs/objects into tree parameters so that SpecTcl can use them.

This approach can be transplanted into Root, by using the framework to process ring items. After each ring item is processed, the object embedded into the second event processor would be run. That would be followed by code to marshall data from the structs into Root trees.

In the remainder of this section we'll look at an event processor that embeds the CRingItemDecoder processing framework. This code will be fragmentary and incomplete. It is intended to give you a direction from which you can embed this framework.

Here's some sample code that shows how to get from an event processor into the ring item decoder. We're going to assume that the constructor, or OnAttach has created an instance of the decoder in m_pEventDecoder and that the fragment handlers have already been registered.

All we need to do is to get a pointer to the ring item and pass that to the decoder as a CRingItem. To do this we use the facts that:

• The CBufferDecoder for ring item data sources is a CRRingBufferDecoder.

• The CRingItemFactory can construct a CRingItem from a pointer to a raw ring item

Bool_t
CFrameworkEventProcessor::operator()(const Address_t pEvent,
			    CEvent& rEvent,
			    CAnalyzer& rAnalyzer,
			    CBufferDecoder& rDecoder
)
{
    ....
    CRingBufferDecoder& actualDecoder(dynamic_cast<CRingBufferDecoder&>(rDecoder);
    void* pRawRingItem = actualDecodrer.getItemPointer();
    CRingItem pRingItem = CRingItemDecoder::createRingItem(pRawRingItem);
    (*m_pEventDecoder)(pRingItem);
    delete pRingItem;
    ....
    
    return kfTRUE;
}
                

After casting the decoder to a ring item decoder, the decoder is used to get a pointer to the raw ring item. By raw ring item we mean an item like one described in DataFormat.h. Once we have that, the ring item factory can create a ring item object which can be passed to the decoder and then deleted.