CRingStateChangeItem

Name

CRingStateChangeItem -- Encapsulate a ring buffer state change item.

Synopsis


#include <CRingStateChangeItem>
         
 class CRingStateChangeItem {
}

            
  CRingStateChangeItem(uint16_t reason =  BEGIN_RUN);
              CRingStateChangeItem(uint16_t reason, uint32_t runNumber, uint32_t timeOffset, time_t timestamp, std::string title)
          throws CRangeError;
            
            
            
              CRingStateChangeItem(uint64_t eventTimestamp, uint32_t sourceId, uint32_t barrierType, uint16_t reason, uint32_t runNumber, uint32_t timeOffset, time_t  timestamp, std::string  title);
            
            
            
              CRingStateChangeItem(const CRingItem& item)
          throws std::bad_cast;
              CRingStateChangeItem(const CRingStateChangeItem& rhs);
            
  virtual ~CRingStateChangeItem();
            
  CRingStateChangeItem& operator=(const CRingStateChangeItem& rhs);
              const int operator==(const CRingStateChangeItem& rhs);
              const int operator!=(const CRingStateChangeItem& rhs);
              void setRunNumber(uint32_t run);
              const uint32_t getRunNumber();
              void setElapsedTime(uint32_t offset);
              const uint32_t getElapsedTime();
              void setTitle(std::string title)
          throws CRangeError;
              const std::string getTitle();
              void setTimestamp(time_t stamp);
              const time_t getTimestamp();
    
            
            
              virtual const std::string typeName();
              virtual const std::string toString();
            
            
	};
         

Description

Encapsulates a ring buffer item for the ring items that represent changes in state of a data taking run. These are specifically ring items of the type: BEGIN_RUN, END_RUN, PAUSE_RUN, and RESUME_RUN.

In a ring buffer, these items take the form of a StateChangeItem as defined in <DataFormat.h>.

The class can be used both to format state change items for later insertion into a ring, or to decode existing state change items.

Public member functions

CRingStateChangeItem(uint16_t reason = BEGIN_RUN);

Constructs a state change item with the type reason. The run number, and time offset will be set to zero. The timestamp will be set to the current time, and the title will be empty.

CRingStateChangeItem(uint16_tM reason, uint32_t runNumber, uint32_t timeOffset, time_t timestamp, std::string title) throws CRangeError;

Constructs a run state change item in a fully specified way. reason is the actual type of the item. runNumber will be stored in the item as the number of the run undergoing state change. timeOffset should be the time in the run at which the state change occured in seconds. This time should not include time spent in the paused state, and the begin run is always emitted at timeOffset zero. timestamp is an absolute time at which the transition occured. This can be gotten via the POSIX time(2) function. title is the title string.

The title string must be at most TITLE_MAXSIZE characters long. If it is longer than that, a CRangeError will be thrown.

CRingStateChangeItem(uint64_t eventTimestamp, uint32_t sourceId, uint32_t barrierType, uint16_t reason, uint32_t runNumber, uint32_t timeOffset, time_t timestamp, std::string title);

Constructs a ring state change item that has a full body header. The contents of the body header are determined by eventTimestamp, sourceId and barrierType.

CRingStateChangeItem(const CRingItem& item) throws std::bad_cast;

Attempts to construct a CRingStateChangeItem from a reference to an existing CRingItem; item. If item is not a value state change item, a std::bad_cast exception will be thrown.

CRingStateChangeItem(const CRingStateChangeItem& rhs);

Constructs an object that is a functional copy of rhs.

CRingStateChangeItem& operator=(const CRingStateChangeItem& rhs);

Provides assignment to CRingStateChangeItem objects from other CRingStateChangeItems. After assignment is done the object on the left side of the = is a functional equivalent of rhs.

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

Compares the object on the left hand side of the == for functional equivalence with the rhs object.

const int operator!=(const CRingStateChangeItem& rhs);

Compares the object for functional equivalence with rhs. Returns the logical inverse of the comparison.

void setRunNumber(uint32_t run);

Sets the run number of the item to run.

const uint32_t getRunNumber();

Returns the current value of the run number.

void setElapsedTime(uint32_t offset);

Set the elapsed time for the item to offset. This value is supposed to represent the number of active seconds into the run at which the state transition occured.

const uint32_t getElapsedTime();

Returns the object's current elapsed run time value.

void setTitle(std::string title) throws CRangeError;

Sets a new value for the title of the run. If the title is longer than TITLE_MAXSIZE characters, a CRangeError will be thrown.

const std::string getTitle();

Returns the value of the title string.

void setTimestamp(time_t stamp);

Sets the absolute time of the state transition to stamp. This is a value that might be gotten via the Unix time(2) function

const time_t getTimestamp();

Returns the value of the absolute run time.

virtual const std::string typeName();

Overrides the base class method. Returns a textual description of the type of the ring item (e.g. Begin Run).

virtual const std::string toString();

Overrides the base class method to produce a text string that describes the state change item.

Types and public data

The underlying item encapsulated by this class is a StateChangeItem which is defined in <DataFormat.h>.

Exceptions

std::bad_cast

Called if an attempt is made to construct from a CRingItem that is not a valid run state transition item.

CRangeError

Thrown if an attempt is made to provide a title string that is longer than allowed by run-state transition items. The maximum title string length is TITLE_MAXSIZE.

EXAMPLES

The example below creates a begin run and informs a ring about this.

Example 1. Creating a begin run state transition item


#include <DataFormat.h>
#include <CRingStateChange.h>

CRingStateChange item;
item.setTitle(string("This is the run title"));
item.setRunNumber(1234);

item.commitToRing(aring);