47.3. Incorporating the headers and libraries into your applications.

NSCL DAQ provides a class library that allows you to encapsulate ring buffer data items in objects from which you can get/set data. Ring buffer item objects are intended both for producers and consumers of data. See the 3daq section of the reference material for detailed per class documentation.

Each class has a header file that is named the same as the class with a .h appended. Thus to incorporate the definitions for the CRingItem base class in your source code you would add the line:

Example 47-1. Including a ring item class


#include <CRingItem.h>
            

To your source files.

At compile time you would need to add a -I switch to tell the compiler where these headers are. If the environment variable DAQROOT points to the top level of the NSCLDAQ installation tree you might do this as shown below:

Example 47-2. Telling the compiler where to find Ring Item headers


g++ -c -I$DAQROOT/include mymodule.cpp
            

At link time you need to provide the location of the libraries as well as to specify the set of libraries that must be included. Note that as the example below shows, normally using the data format library implies you will need the data flow library as well:

Example 47-3. Linking the ring item format libraries


g++ -o myApplication src1.o src2.o ... -L$DAQROOT/lib \
        -ldataformat -lDataFlow -Wl,"-rpath=$DAQROOT/lib"
            

The following classes manage data formatting:

CRingItem

Base class for all the ring data item format classes. This class also has the static member getFromRing which accepts a ring object reference and a CRingSelectionPredicate reference, and returns a pointer to the next ring item that matches the predicate's match criteria.

CRingStateChangeItem

Represents a state change item. Given a reference to a CRingItem (e.g. one just gotten from CRingItem::getFromRing), one of the constructors constructs an equivalent ring state change object or throws a std::bad_cast exception if the item is not a valid state change.

CRingScalerItem

Represents a state change item. Given a reference to a CRingItem one of the constructors can produce a CRingScalerItem object or throw a std::bad_cast exception if the item was not actually a scaler item.

CRingTextItem

Encapsulates a text list item. As with all the above classes, a constructor exists that converts a CRingItem to a CRingTextItem or throws a std::bad_cast if that's not legal.

CGlomParameters

Encapsulates the glom parameter ring items. This ring item describes how the glom component of the event builder pipeline has been started.

CPhysicsEventItem

Encapsulates the data taken in response to a physics trigger.

CRingFragmentItem

Encapsulates items produced in the ordering phase of the event builder pipeline. Items of this type are believed to have other ring items as their payloads.

CRingPhysicsEventCountItem

Encapsulates an item that gives information about the number of triggers that have been processed by the system (or by a single event source) during the run so far. This both allows software to monitor trigger rates and allows you to determine the percentage of data you are sampling from an online ringbuffer in the event you are sampling data.

CUnknownFragment

Encapsulates an event fragment produced by the event builder ordering stage for which there's good reason to believe the payload is not a ring item.

47.3.1. Generic ring data sources

You may want a program to work equally well when pointed at a ring buffer and when pointed at a file of ring items, such as an event file created by the event logger.

A set of data source classes and a data source factory allow you to easily write program like this. The key point is that ring data sources are specified by uniform resource identifiers (URIs). The first part of a URI is called the 'protocol' and defines how a connection takes place. For online rings we have seen that the protocol is tcp: For offline event files, the protocol is file:.

The data format library provides a generic base class; CDataSource. Concrete subclasses include CRingDataSource and CFileDataSource provide data sources for online rings and offline files respectively. The factory class is CDataSourceFactory.

The data sources return generic ring items. These can be upcast into specific ring item types by using methods in the CRingItemFactory class.

Reference information on these classes is availabe at: CDataSource, CRingDataSource, CFileDataSource, CDataSourceFactory", and CRingItemFactory.