RingItemFactory (v12)

Creates a new ring item that is undifferentiated, that is it implements no type specific methods. type is put in the ring item header's type field. Storage capacity sufficient for a body of up to maxBody bytes of data are reserved though you'll need to communicate the size of the item (normally via the object's setBodyCursor and updateSize methods) to actually fill in the header's size field.

The returned value is a pointer to a v12::CRingItem object (cast to ::CRingItem). The caller is responsible for deleting the object when it is no longer needed (e.g. by initializing a smart pointer object with it).

Creates an undifferentiateded ring item that is parameterized for a body header. The ring item will be created with a body header whose fields will come from the timestamp, sourceId and optional barrierType arguments. barrierType defaults to 0 which means no barrier is triggered.

For a user to add a body header extension, prior to any actual body data being added, requires that they first use getBodyHeader to get a pointer to the body, then getBodyCursor to obtain a pointer past the end of the body cursor add the data and then adust the size field of the body header.

For example, suppose the application is to add a body header extension that will contain the experiment number which is stored in the constant EXPERIMENT_NUMBER:

std::uinque_ptr<::CRingItem> p(factory.makeRingItem(...)) // make ring item with body header.

v12::pBodyHeader pH = reinterpret_cast<v12::pBodyHeader>(p->getBodyHeader());
uint32_t* pCursor = reinterpret_cast<uint32_t*>(p->getBodyCursor);
*pCursor = EXPERIMENT_NUMBER;
pH->s_size += sizeof(uint32_t);
p->setBodyCursor(pCursor);      // For whomever is filling the item body.

                            

Makes a ring item by copying the contents of another ring item. Note that the results are not well defined if the rhs item comes from a different ring item format than this factory.

In practice this is not a problem unless you are writing a format converter.

Wraps a raw ring item in a v12::CRingItem object and returns a pointer to that object.

Reads a ring item from the ringbuffer ringbuf and wraps it in a new v12::CRingItem.

ringbuf must be attached to the ring buffer in consumer mode.

Reads a ring item from the entity open on the linux file descriptor fd and wraps it into a new v12::CRingItem.

Reads a ring item from the C++ istream referenced by in and wraps it in a v12::CRingItem.

Puts the wrapped ring item pointed to by pItem in the std::ostream referenced by out. The raw binary of the ring item is output which allows it to be read in using getRingItem at some later date.

The out stream must be open for write and in binary mode. Note any actual ring item type can be used for the pItem since they all ultimately descend from ::CRingItem.

The method, like most C++ stream I/O methods, returns a reference to out following the put.

Writes the ring item pointed to by pItem to the file descriptor fd

Writes the ring item pointed to by pItem to the ringbuffer referenced by ringbuf. ringbuf must be attached to the ring buffer in producer mode.

Creates a new abnormal end run item. Abnormal end run items flag event data taking that has ended without a proper end run request/indication.

If rhs references an abnormal end item, this will create a new copy of that item with the specific type, a pointer to v12::CAbnormalEndItem. If, however the type of rhs is not v12::ABNORMAL_ENDRUN and the size of the ring item is not sizeof(v12::AbnormalEndItem, a std::bad_cast exception is thrown.

This creates a new data format item.

If rhs references a data format item, this method will produce a duplicate item and return a pointer to it. If not a std::bad_cast is thrown.

Produces a pointer to a v12::CGlomParameters. This data type is used to encapsulate a informational ring item emitted by the event builder's glom stage. The ring item contains the coincidence interval: interval, The policy for assigning timestamps to output events and a flag, isBuilding which is true if glom is actually building events and false if it is just emitting single fragment events.

If rhs is a v12 glom parameters ring item, duplicates it as a v12::CGlomParameters item and returns a pointer to this item.

Creates and returns a pointer to a physics event item (v12::CPhysicsEventItem). The capacity of the item will be sufficient for the item to have a body of maxBody.

Makes a physics event with a body header filled in from the additional parameters. The body header timestamp is filled in from timestamp, the source id from source and the barrier type from barrier.

Given an undifferentiated ring item that encapsulates a physics event item in rhs, constructs an actual v12::CPhysicsEventItem returning a pointer to the constructed item. If the type of the item is not v12::PHYSICS_EVENT a std::bad_cast exception is thrown.

Note that if the item is from a different version of NSCLDAQ, the behavior of the resulting item is not well defined. Consider for example, if rhs is v10 ring item, That item has no word indicating it has no body header and therefore, the v12::CPhysicsEventItem class will misinterpret the shape of the underlying ring item.

Returns a ring fragment item with the timestamp, source id and barrier as described by the timestamp, source, and barrier parameters. The payload size and contents are as in payloadSize and payload.

If rhs is a ring fragment item returns a fragment item that is functionally equivalent to rhs. If rhs is not a fragment item, throws a std::bad_cast exception.

Makes a physics event count item in version 12 format. count must be the number of triggers handled by the readout system at timeoffset into the run. divisor is the number of ticks of timeoffset in one second.

stamp is the clock time at which the item is being created (should be during the run not during analysis). It can be generated by a call to the unix time service.

If rhs is an undifferentiated ring item that wraps a physics event count item, this method creates a new v12::CRingPhysicsEventCountItem that contains the same information as rhs.

Note that if rhs is not a v12::PHYSICS_EVENT_COUNT ring item, a std::bad_cast exception is thrown. The behavior of this generator method is not well defined if the ring item comes from another version of NSCLDAQ.

Create a scaler item for V12 that has storage reserved for numScalers scalers. The interval start and end time must be set at a later time. The scaler storage is initialized to zero and the clock time stamp is initialized to the time this method is called.

Creates a version 12 scaler item that is fully populated. startTime and stopTime along with timeOffsetDivisor describe the time interval relative to the start of the run over which the scaler counted. timeOffsetdivisor specifies the number of ticks in startTime and stopTime in one second. If omitted, it defaults to 1 meaning that those parameters are in units of seconds.

scalers is a vector of scaler values. THe actual meaning of these values depends on the state of the isIncremental flag. If isIncremental is true, the scalers represent additional counts over the counting interval. If false, the scalers represent cummulative counts since the beginning of the run.

The item is created with a body header that has a special timestamp that requests the event builder assign a timestamp from the last timestamped item. The source id is sid and barrier type 0.

If rhs is a scaler item a new v12::CRingScalerItem is made from the data in rhs. If rhs is not of type v12::PERIODIC_SCALERS a std::bad_cast exception is thrown.

Creates an item that contains text strings. type is the ring item type and must be one of v12::PACKET_TYPES or v12::MONITORED_VARIABLES. The strings themselves are taken from the vector theStrings.

The clock time is filled in from the time at which this method is called and the run time offset is initialized to 0

Same as the previous methods however the additional parameters serve to initialize other bits otf the ring item: offsetTime and divisor describe the offset into the run at which the item was emitted. The divisor parameter provides the number of offsetTime ticks in a second. If omitted it defaults to 1 which means that offsetTime is in units of seconds.

Given an undifferentiated ring item; rhs that encpasulates a valid text item creats a new v12::CRingTextItem from the data in rhs. If the item is not a valid v12 text item, a std::bad_cast exception is thrown.

Generates and returns a pointer to a v12::CUnknownFragment object. The parameters provided are used to initialize the object data: timestamp, sourceid and barrier provide the header information. size is the number of bytes of payload pointed to by pPayload that will be copied into the body of the item.

Note that CUnknownFragment objects are CRingFragmentItem objects with a type of v12::EVB_UNKNOWN_PAYLOAD

If rhs is an unknown fragment, produces a copy of it and wraps that in a v12::CUnknownFragment object returing a pointer to the resulting object.

Creates a new run state change item formatted for version 12. The itemType defines the new run state and must be one of v12::BEGIN_RUN, v12::PAUSE_RUN, v12::RESUME_RUN, or v12::END_RUN. If it is none of those, a std::bad_cast exception is thrown.

The remaining parameters define parameters of the run: runNumber is the unique number of the run. timeOffset is the offset into the run at which the state change occurerd. This must be in units of seconds. timestamp is the clock time at which the state transition happened. Finally, title is the title string associated with the run.

Note that all state change items associated with the same run should have the same title and run number. This is not enforced. The timeOffset for a v12::BEGIN_RUN item should always be 0, but this too is not enforced. Finally, the timestamp parameter can be the output of a call to the unix time function.

If rhs is an undifferentiated ring item that encapsualtes a valid v11 run state transition ring object, a new v12::CRingStateChangeItem is created encapsulating the same information. If rhs is not a valid v12 run state transition item, a std::bad_cast exception is thrown.