EBF_evts.h File Reference

EBF evts, Interface. This provides an iterator like facility for a vector of events. More...

#include <EDS/EBF_evt.h>
#include <EDS/io/EBF_evt.ih>
#include <EDS/io/EBF_pkts.h>

Classes

struct _EBF_evts_es

The iterator control structure. More...

union _EBF_evts_u

The iterator control structure. More...

Typedefs

typedef struct _EBF_evts_es EBF_evts_es

Typedef for struct _EBF_evts_es.

typedef union _EBF_evts_u EBF_evts_u

Typedef for struct _EBF_evts.

typedef EBF_evts_es EBF_evts

Opaque type for the events vector.

Functions

static __inline EBF_evt * EBF__evtsEvt (EBF_evts evts)

Retrieves the next event.

static __inline int EBF__evtsSize (EBF_evts evts)

Retrieves the length in bytes of the events vector.

static __inline EBF_evts EBF__evtsNext (EBF_evts evts)

Pushes the event iterator to the next event.

static __inline EBF_evts EBF__evtsAdvance (EBF_evts evts, int nbytes)

Advances the specified event iterator forward by the specified number of bytes.

static __inline EBF_pkts EBF__evtsToPkts (EBF_evts pkts)

Converts a vector of events to a vector of packets.

static __inline EBF_evts EBF__evtsFromPkts (EBF_pkts pkts)

Converts a vector of packets to a vector of events.

int EBF_evtsCount (EBF_evts evts)

Counts the number of events.

EBF_evts EBF_evtsLimit (EBF_evts evts, int nevts)

Limits the events to the specified number of events.

EBF_evts EBF_evtsSkip (EBF_evts evts, int skip)

Returns an events vector with the specified number of events skipped.

EBF_evts EBF_evtsSetup (EBF_evts evts, int skip, int limit)

Skips and limits the number of events.

EBF_evts EBF_evtsMcSeek (EBF_evts evts, unsigned int mcNumber)

Advances the evts to the event with Monte Carlo number mcNumber.

EBF_evts EBF_evtsSeqSeek (EBF_evts evts, unsigned int seqNumber)

Advances the evts to the event with trigger event sequence number seqNumber.

Detailed Description

EBF evts, Interface. This provides an iterator like facility for a vector of events.

Author:: JJRussell - russell@slac.stanford.edu

    CVS $Id: EBF_evts.h,v 1.4 2011/08/04 19:46:11 russell Exp $

Overview: This facility provides an iterator like facility for a vector of events. The vector of events is described by the EBF_evts structure. It contains two 2-bit values

A pointer to the first event in the vector
The size, in bytes, of all the remaining events in the vector

When all the events are exhausted, the empty events vector will be returned. The empty events vector is defined as the vector with

Its event pointer pointing just past the last event
Its remaining size being precisely 0.

Operations: The following operations all return, as an immediate value, a new event vector, with the first event pointing at the desired event. If the desired event does not exist in the specified events vector, the empty events vector is returned.

: The operations are

EBF_evtsLimit, limits the event descriptor to no more than the specified number of events. This is useful if the size of the specficed number of events needs to be known apriori to processing the events.
EBF_evtsSkip, skips the requested number of events
EBF_evtsSetup Skips and limits the events vector
EBF_evtsMcSeek, seeks out the event with the specifed GLEAM Monte Carlo event number
EBF_evtsSeqSeek, seeks out the event with the specified trigger sequence number.

: All these operations, but EBF_evtsSeqSeek, are straight-forward. Because the trigger events sequence number is only 17-bits, it may not be unique. In an effort to make this number unique, the routine will manufacture the additional carry bits. The carry bit will be incremented everytime trigger event sequence number is less than the previous event sequence number. This definition is unique if and only if

No such rollover occurs within the events vector
One all specifies the same events vector.

Counting function: In addition, a function, EBF_evtsCount, is provided to count the number of events in the events vector.

Typedef Documentation

unsigned long long int EBF_evts

Opaque type for the events vector.

: The user should never directly access the internals of the EBF_evts data structure. Rather he should use EBF__evtsEvt and EBF_evtsSize to get a pointer the current event and the remaining size. Note that the size is the size of the event vector not the size of the current event; there is another accessor taking the event pointer as an argument for that function. The size is mainly used to determine when the vector is exhausted.

: So why did one go through all this, in other words, why not just expose the structure. Well, first, this is more modular, hiding the implementation details, but more importantly, at least in the online world, expressing the events vector as a 64-bit quantity allows it to be passed into and returned from functions as an immediate value without copying it into temporary memory.

Function Documentation

static __inline EBF_evts EBF__evtsAdvance	(	EBF_evts	evts,
		int	nbytes
	)			`[static]`

Advances the specified event iterator forward by the specified number of bytes.

Returns:: The new state of the event iterator

Parameters:

	evts	The current state of the event iteractor
	nbytes	The number of bytes to advance the event iterator

Warning:: This routine makes no check that the new iterator actually points to a new event. If the size goes either negative or the specified esize does not point one to an event, it is let the buyer beware.

: This routine should be used if the event size in bytes has already been extracted.

References _EBF_evts_u::es, _EBF_evts_es::evt, and _EBF_evts_es::size.

static __inline EBF_evt * EBF__evtsEvt ( EBF_evts evts ) [static]

Retrieves the next event.

Returns:: Pointer to the current event

Parameters:

evts

The current state of the event interactor

References _EBF_evts_u::es, and _EBF_evts_es::evt.

static __inline EBF_evts EBF__evtsFromPkts ( EBF_pkts pkts ) [static]

Converts a vector of packets to a vector of events.

Returns:: The vector of events

Parameters:

pkts

The packets vector to convert

Warning:: While it is true that every event is a packet, there is no guarantee that the first packet in the packets vector begins an event. It is the user responsiblity to position the packets vector.

References _EBF_evts_u::es, and _EBF_evts_u::ps.

Referenced by EBF_streamProcess().

static __inline EBF_evts EBF__evtsNext ( EBF_evts evts ) [static]

Pushes the event iterator to the next event.

Returns:: The new state of the event iterator

Parameters:

evts

The current state of the event interactor

References EBF__evtSize(), _EBF_evts_u::es, _EBF_evts_es::evt, and _EBF_evts_es::size.

Referenced by EBF_evtsCount(), EBF_evtsLimit(), EBF_evtsMcSeek(), EBF_evtsSeqSeek(), and EBF_evtsSkip().

static __inline int EBF__evtsSize ( EBF_evts evts ) [static]

Retrieves the length in bytes of the events vector.

Returns:: Length, in bytes of the events vector

Parameters:

evts

The current state of the event interactor

: This function is mainly used to tell when the events vector is exhausted, i.e. length = 0.

References _EBF_evts_u::es, and _EBF_evts_es::size.

static __inline EBF_pkts EBF__evtsToPkts ( EBF_evts evts ) [static]

Converts a vector of events to a vector of packets.

Returns:: The vector of packets

Parameters:

evts

The events vector to convert

References _EBF_evts_u::es, and _EBF_evts_u::ps.

Referenced by EBF_streamProcess().

int EBF_evtsCount ( EBF_evts evts )

Counts the number of events.

Returns:: The number of events in evts

Parameters:

evts

The vector of events to count

References EBF__evtsNext(), _EBF_evts_u::es, and _EBF_evts_es::size.

EBF_evts EBF_evtsLimit	(	EBF_evts	evts,
		int	limit
	)

Limits the events to the specified number of events.

Returns:: The number of events in evts

Parameters:

	evts	The vector of events to limit
	limit	The number of events to limit the vector of events to

: This limits the events vector to the specified number of events. If nevts is specified as -1, this is taken as a flag to not limit the events vector and the events vector is returned as is.

References EBF__evtsNext(), _EBF_evts_u::es, and _EBF_evts_es::size.

Referenced by EBF_evtsSetup().

EBF_evts EBF_evtsMcSeek	(	EBF_evts	evts,
		unsigned int	mcNumber
	)

Advances the evts to the event with Monte Carlo number mcNumber.

Returns:: New event vector

Parameters:

	evts	The target vector of events
	mcNumber	The Monte Carlo event number to seek

: This function advances the evts vector to the event with the requested Monte Carlo event number. If no such event exists, the empty event vector (no events left size == 0) is returned.

References EBF__evtsNext(), _EBF_evts_u::es, _EBF_evts_es::evt, _EBF_evt::hdr, _EBF_evts_es::size, and _EBF_pktHdr::undef.

EBF_evts EBF_evtsSeqSeek	(	EBF_evts	evts,
		unsigned int	seqNumber
	)

Advances the evts to the event with trigger event sequence number seqNumber.

Returns:: New event vector

Parameters:

	evts	The target vector of events
	seqNumber	The trigger event sequence number

: This function advances the evts vector to the event with the requested event sequence number. If no such event exists, the empty event vector (no events left size == 0) is returned.

Warning:: Technically the trigger event sequence number is only 17 bits in length. If the events vector contains more than 2**17 events, this routine will manufacture the additional bits whenever the trigger event sequence number rolls-over. This is process is unique only if one always starts at the beginning of the events file. If it is started another place, such on a previously returned events vector, it will not be.

References _EBF_evt::ctb, EBF__evtsNext(), EBF_ESW_SEQ, _EBF_evts_u::es, _EBF_ctbHdr::esw, _EBF_evts_es::evt, _EBF_ctb::hdr, _EBF_evts_es::size, and _EBF_esw::ui.

EBF_evts EBF_evtsSetup	(	EBF_evts	evts,
		int	skip,
		int	limit
	)

Skips and limits the number of events.

Returns:: New event vector

Parameters:

	evts	Pointer to the vector of events to be skipped and limited
	skip	The number of events to skip
	limit	The number of events to limit the vector of events to

References EBF_evtsLimit(), and EBF_evtsSkip().

Referenced by EBF_streamProcess().

EBF_evts EBF_evtsSkip	(	EBF_evts	evts,
		int	skip
	)

Returns an events vector with the specified number of events skipped.

Returns:: New event vector

Parameters:

	evts	The base vector of events
	skip	The number of events to skip

References EBF__evtsNext(), _EBF_evts_u::es, and _EBF_evts_es::size.

Referenced by EBF_evtsSetup().


Classes
struct	_EBF_evts_es
	The iterator control structure. More...
union	_EBF_evts_u
	The iterator control structure. More...
Typedefs
typedef struct _EBF_evts_es	EBF_evts_es
	Typedef for struct _EBF_evts_es.
typedef union _EBF_evts_u	EBF_evts_u
	Typedef for struct _EBF_evts.
typedef EBF_evts_es	EBF_evts
	Opaque type for the events vector.
Functions
static __inline EBF_evt *	EBF__evtsEvt (EBF_evts evts)
	Retrieves the next event.
static __inline int	EBF__evtsSize (EBF_evts evts)
	Retrieves the length in bytes of the events vector.
static __inline EBF_evts	EBF__evtsNext (EBF_evts evts)
	Pushes the event iterator to the next event.
static __inline EBF_evts	EBF__evtsAdvance (EBF_evts evts, int nbytes)
	Advances the specified event iterator forward by the specified number of bytes.
static __inline EBF_pkts	EBF__evtsToPkts (EBF_evts pkts)
	Converts a vector of events to a vector of packets.
static __inline EBF_evts	EBF__evtsFromPkts (EBF_pkts pkts)
	Converts a vector of packets to a vector of events.
int	EBF_evtsCount (EBF_evts evts)
	Counts the number of events.
EBF_evts	EBF_evtsLimit (EBF_evts evts, int nevts)
	Limits the events to the specified number of events.
EBF_evts	EBF_evtsSkip (EBF_evts evts, int skip)
	Returns an events vector with the specified number of events skipped.
EBF_evts	EBF_evtsSetup (EBF_evts evts, int skip, int limit)
	Skips and limits the number of events.
EBF_evts	EBF_evtsMcSeek (EBF_evts evts, unsigned int mcNumber)
	Advances the evts to the event with Monte Carlo number mcNumber.
EBF_evts	EBF_evtsSeqSeek (EBF_evts evts, unsigned int seqNumber)
	Advances the evts to the event with trigger event sequence number seqNumber.