NSCL DAQ Software Documentation
PrevNext

CRingScalerItem

Name

CRingScalerItem -- Encapsulate ring buffer scaler items.

Synopsis


#include <CRingScaleritem.h>
         

            CRingScalerItem
            CRingScalerItem::m_ScalerFormatMask(32)
            
  CRingScalerItem(size_t numScalers);
              CRingScalerItem(uint32_t startTime, uint32_t stopTime, time_t timestamp, std::vector<uint32_t> scalers);
            
            
              CRingScalerItem(uint64_t  eventTimestamp, uint32_t  source, uint32_t barrier, uint32_t startTime, uint32_t stopTime, time_t timestamp, std::vector<uint32_t> scalers, uint32_t timeDivisor = 1);
            
            
              CRingScalerItem(const CRingItem& rhs)
          throws std::bad_cast;
              CRingScalerItem(const CRingScalerItem& rhs);
            
  virtual ~CRingScalerItem();
            
  CRingScalerItem& operator=(const CRingScalerItem& rhs);
              const int operator==(const CRingScalerItem& rhs);
              int operator!=(const CRingScalerItem& rhsconst );
              void setStartTime(uint32_t startTime);
              const uint32_t getStartTime();
              const float computeStartTime();
              void setEndTime(uint32_t endTime);
              const uint32_t getEndTime();
              const float computeEndTime();
              const uint32_t getTimeDivisor();
              void setTimestamp(time_t stamp);
              const time_t getTimestamp();
              void setScaler(uint32_t channel, uint32_t value)
          throws CRangeError;
              const uint32_t getScaler(uint32_t channel)
          throws CRangeError;
            
              const std::vector<uint32_t> getScalers();
              const uint32_t getScalerCount();
              const uint32_t getOriginalSourceId();
     // Since NSCLDAQ-12.0
            
            
              virtual const std::string typeName();
              virtual const  std::string toString();

Description

CRingScalerItem encapsulates scaler items that either have been gotten from a ring or are being formatted to be inserted into a ring.

Public member functions

CRingScalerItem(size_t numScalers);

Constructor for a ring scaler item that will hold numScalers incremental scaler values. The interval start and stop times are set to zero and the timestamp to the current time. Scaler values are not initialized (specifically don't assume they are zero).

CRingScalerItem(uint32_t startTime, uint32_t stopTime, time_t timestamp, std::vector<uint32_t> scalers);

Full constructor for a scaler ring item. startTime is the number of seconds of active run time at the start of the interval measured by these scalers, and stopTime the end. timestamp is the absolute time of the end of the measurement interval (or more accurately, the time at which the scaler item was formatted). sclaers are a vector of scaler values.

CRingScalerItem(uint64_t eventTimestamp, uint32_t source, uint32_t barrier, uint32_t startTime, uint32_t stopTime, time_t timestamp, std::vector<uint32_t> scalers, uint32_t timeDivisor = 1);

Constructs a ring scaler item with a full body header described by the eventTimestamp, source and barrier parameters. If the optional timeDivisor parameter is supplied, it will set the time divisor that is used to provide sub-second granularity to the interval start and end times.

CRingScalerItem(const CRingItem& rhs) throws std::bad_cast;

Constructs a scaler item from an existing ring item rhs. If rsh's type is not INCREMENTAL_SCALERS, a std::bad_cast exception is thrown.

CRingScalerItem(const CRingScalerItem& rhs);

Constructs a functional duplicate of the scaler item rhs (copy construction).

CRingScalerItem& operator=(const CRingScalerItem& rhs);

Assigns to this object from rhs. The object will become a functional equivalent of rhs. If later compared to rhs equality will be true.

const int operator==(const CRingScalerItem& rhs);

Compares rhs with the object for functional equivalency.

int operator!=(const CRingScalerItem& rhsconst );

Compares the item for functional equivalency and returns the logical inverse of the result.

void setStartTime(uint32_t startTime);

Sets the interval start time offset to startTime. This is supposed to be the time into the run at which this set of scalers started counting. Inactive run time is not counted.

const uint32_t getStartTime();

Returns the counting interval start time.

const float computeStartTime();

Computes the counting interval start time in seconds. The method getStartTime gets the start time in "tick" units. To convert this time to seconds, the ticks must be divided by the time divisor. This convenience method performs that computation.

void setEndTime(uint32_t endTime);

Sets the interval end time to endTime. This is supposed to be the number of seconds in to the run at which the scalers for this item were read and cleared. Note that only active seconds are acounted.

const uint32_t getEndTime();

Returns the time offset into the run at which the scalers were read. For a properly formatted item, this value should be larger than that returned by getStartTime.

const uint32_t getTimeDivisor();

NSCLDAQ-11.0 introduced subsecond precision for run offset times. This is accomplished by allowing the time offsets to be provided in arbitrary tick units along with a divisor that, when dividing those ticks in a floating point division produces seconds.

getTimeDivisor returns this timing divisor. Note that ordinarily, just to get run offset times in seconds, just use the computeStartTime and computeEndTime methods..

const float computeEndTime();

Returns the interval end time in units of seconds. The method getEndTime returns the end time in counter tick units. To convert those units to seconds they must be divided by the time divisor. This convenience method performs that computation.

void setTimestamp(time_t stamp);

Sets the timestamp for the item. This should be the time at which the buffer was formatted. It is a time_t as described in documentation of the unix time function.

const time_t getTimestamp();

Returns the timestamp for an item. This is supopsed to be compatible for the argument to e.g. ctime in the byte order of the creating system.

void setScaler(uint32_t channel, uint32_t value) throws CRangeError;

Sets the value of scaler number channel to value. If channel is larger than the number of scalers the item was constructed with, CRangError is thrown.

const uint32_t getScaler(uint32_t channel) throws CRangeError;

Returns the value of the scaler channel channel. If the channel is too large a CRangeError is thrown.

const std::vector<uint32_t> getScalers();

Returns a vector that consists of the values of all of the incremental scalers in the item.

const uint32_t getScalerCount();

Returns the number of scalers in the item.

const uint32_t getOriginalSourceId();

The Source id of the ring item in the body header can be re-written by the event building pipeline. Since the original sourceid (the one supplied to construct the ring item) is important for determining the actual meaning of the scaler data in analysis, that source id is stored, as well in the scaler body. This method returns that value.

This method is an NSCLDAQ-12.0 addition.

virtual const std::string typeName();

Provides a textual string that describes the scaler item type. This overrides the base class method with code that returns the string Scaler:.

virtual const std::string toString();

Overrides the base class method with code that returns a formatted dump of the scaler values and scaler rates over the period in which the scalers were acquired. Note that the rate is only produced for incremental scalers.

The public static variable CRingScalerItem::m_ScalerFormatMask is bitwise anded with each scaler item after the scaler items are fetched from the ring item prior to output. This allows a clean formatting of scaler counters that have fewer than 32 bits but have garbage in their top bits.

Types and public data

See the ScalerItem type in <DataFormat.h>.

Exceptions

std::bad_cast

This is thrown in the event an attempt is made to construct a CRingScalerItem object from a CRingItem whose type is not INCREMENTAL_SCALERS.

CRangeError

Thrown in the event an effort is made to access a scaler channel that does not exist.

EXAMPLES

In the following example, an item is gotten from a ring buffer. If it is a scaler item, it is used to construct a new scaler item. ring is assumed to be a CRingBuffer object or a reference to one.

Example 1. Constructing a scaler item from an item gotten from a ring


#include <DataFormat.h>
#include <CRingItem.h>
#include <CRingScalerItem>
...

CAllButPredicate  all;                                        (1)
CRingItem*        pItem = CRingItem::getFromRing(ring, all);  (2)

if (pItem->type() == INCREMENTAL_SCALERS) {                   (3)
   CRingScalerItem scalers(*pItem);                           (4)
   ...
}
else {
...
}
delete pItem;                                                (5)
(1)
This predicate accepts all ring buffer item types without sampling. The CAllButPredicate accepts all ring types without sampling except those explicitly defined.
(2)
Gets the next item from the ring, regardless of type.
(3)
Before constructing a CRingScalerItem object, it's important to ensure the object is atually a scaler item. Without this check it would be necessary to wrap this code in a try/catch block for std::bad_cast.
(4)
If the item is a scaler item, it is converted into a CScalerItem and processed.
(5)
Regardless, the original CRingItem object must be deleted.
PrevHomeNext
CRingItemUpCRingStateChangeItem