A high performance decoder class for MUON trigger DDL data. More...

#include <AliMUONTriggerDDLDecoder.h>

Public Member Functions
	AliMUONTriggerDDLDecoder ()
	Default contructor. More...

const EventHandler &	GetHandler () const
	Constant method to return the event handler instance. More...

EventHandler &	GetHandler ()
	Returns the event handler instance. More...

bool	ExitOnError () const

void	ExitOnError (bool value)

bool	TryRecover () const

void	TryRecover (bool value)

bool	AutoDetectScalars () const

void	AutoDetectScalars (bool value)

UInt_t	MaxRegionals () const
	Returns the maximum regional structure count expected in the DDL payload. More...

void	MaxRegionals (UInt_t n)
	Sets the maximum regional structure count expected in the DDL payload. More...

UInt_t	RegionalsDecoded () const
	Returns the number of regional structures we actually attempted to decode. More...

UInt_t	MaxLocals () const

void	MaxLocals (UInt_t n)

bool	Decode (const void *buffer, UInt_t bufferSize, bool scalarEvent=false)
	This method decodes the DDL payload contained in the buffer. More...

Static Public Member Functions
static UInt_t	EndOfDarcWord ()
	Returns the end of DARC marker key. More...

static UInt_t	EndOfGlobalWord ()
	Returns the end of global header marker key. More...

static UInt_t	EndOfRegionalWord ()
	Returns the end of regional structure marker key. More...

static UInt_t	RegionalErrorWord ()
	Returns the regional error word. More...

static UInt_t	EndOfLocalWord ()
	Returns the end of local structure marker key. More...

static UInt_t	LocalDisableWord ()
	Returns the local card disable word. More...

static UInt_t	DarcDefaultType ()
	Returns value of default DARC type. More...

static UInt_t	DarcVadorhType ()
	Returns value of Vadorh DARC type. More...

Private Member Functions
void	DecodeBuffer (const UChar_t start, const UChar_t end, bool scalarEvent)

void	DecodeRegionalStructs (const UChar_t start, const UChar_t end, bool scalarEvent)

const UChar_t *	DecodeLocalStructs (const UChar_t start, const UChar_t end, bool scalarEvent)

const UChar_t *	FindKey (UInt_t key, const UChar_t start, const UChar_t end)

Private Attributes
bool	fExitOnError
	Indicates if we should exit on the very first error. More...

bool	fTryRecover
	Indicates if we should try recover from a corrupt structures. More...

bool	fAutoDetectScalars
	Flag to indicate if we should auto-detect if there are scalars in the data. More...

bool	fHadError
	Indicates if we had an error decoding the data. More...

UInt_t	fNoRegionals
	The number of regional card structures actually decoded. More...

UInt_t	fMaxRegionals
	Maximum number of regional card structures allowed in a DDL stream. More...

UInt_t	fMaxLocals
	Maximum number of local card structures per regional structure allowed in a DDL stream. More...

EventHandler	fHandler
	The event handler which deals with the generated parsing events. More...

Static Private Attributes
static const UInt_t	fgkEndOfDarc = 0xDEADFACE
	Indicates the end of the DARC header. More...

static const UInt_t	fgkEndOfGlobal = 0xDEADBEEF
	Indicates the end of the global header just after the DARC header. More...

static const UInt_t	fgkEndOfReg = 0xBEEFFACE
	Indicates the end of a regional card structure. More...

static const UInt_t	fgkErrorWord = 0xCAFEDEAD
	The error word when a regional board is missing. More...

static const UInt_t	fgkEndOfLocal = 0xCAFEFADE
	Indicates the end of a local card structure. More...

static const UInt_t	fgkDisableWord = 0x10CADEAD
	Word used to fill "empty" slots. More...

static const UInt_t	fgkDarcDefaultType = 0x6
	default type for DARC def. More...

static const UInt_t	fgkDarcVadorhType = 0x4
	default type for DARC vadorh More...

Detailed Description

template<class EventHandler>
class AliMUONTriggerDDLDecoder< EventHandler >

A high performance decoder class for MUON trigger DDL data.

This class implements a high performance decoder for decoding DDL payload data coming from the muon spectrometers trigger stations. It has been implemented using the event driven paradigm with templates, which allows us to minimise the number of method calls made in the inner loops of the algorithm and minimise the memory footprint. At least for optimised production compilations. The decoder class only contains the basic decoding and error checking logic. It calls methods such as OnNewBuffer, OnDarcHeader, OnNewRegionalStruct, OnLocalStruct etc in the event handler during the decoding to return the decoded data and headers. The event handler class is nothing more than a callback interface to deliver the next chunks of decoded data. To actually do something with the data, one needs to implement a custom event handler (callback) class by inheriting from AliMUONTriggerDDLDecoderEventHandler and overriding the callback methods like so:

class MyCustomHandler : public AliMUONTriggerDDLDecoderEventHandler
{
public:
   void OnLocalStruct(const AliMUONLocalInfoStruct* localStruct,
                      const AliMUONLocalScalarsStruct* scalars)
   {
     // I can do something with the data in 'localStruct' here.
     // and the 'scalars' if they are not NULL.
   }
};

Once the custom handler is written then the decoder is instantiated as shown below, to use your new custom handler. Also to start decoding one needs to call the Decode() method of the decoder.

AliMUONTriggerDDLDecoder<MyCustomHandler> myDecoder;

muDecoder.Decoder(buffer, bufferSize);

Note that this class was written as a template on purpose. To maximise the compilers chance to make optimisations and inline the code we must use a template. Depending on exactly what you do inside your handler, the decoder could be significantly slower if run time polymorphism was used, i.e. making the class AliMUONTriggerDDLDecoderEventHandler abstract and using virtual methods.

Definition at line 89 of file AliMUONTriggerDDLDecoder.h.

Constructor & Destructor Documentation

template<class EventHandler>

AliMUONTriggerDDLDecoder< EventHandler >::AliMUONTriggerDDLDecoder ( )

inline

Default contructor.

Definition at line 94 of file AliMUONTriggerDDLDecoder.h.

Member Function Documentation

template<class EventHandler>

bool AliMUONTriggerDDLDecoder< EventHandler >::AutoDetectScalars ( ) const

inline

Returns the flag indicating if we should check for the scalars of software triggers automatically or not.

Definition at line 127 of file AliMUONTriggerDDLDecoder.h.

template<class EventHandler>

void AliMUONTriggerDDLDecoder< EventHandler >::AutoDetectScalars ( bool value )

inline

Sets the flag indicating if we should check for the scalars of software triggers automatically or not. If set to true then the scalarEvent parameter of the Decode method is ignored.

Definition at line 132 of file AliMUONTriggerDDLDecoder.h.

template<class EventHandler>

static UInt_t AliMUONTriggerDDLDecoder< EventHandler >::DarcDefaultType ( )

inlinestatic

Returns value of default DARC type.

Definition at line 173 of file AliMUONTriggerDDLDecoder.h.

Referenced by AliMUONRawStreamTriggerHP::AliHeader::DarcIsDefaultType().

template<class EventHandler>

static UInt_t AliMUONTriggerDDLDecoder< EventHandler >::DarcVadorhType ( )

inlinestatic

Returns value of Vadorh DARC type.

Definition at line 176 of file AliMUONTriggerDDLDecoder.h.

Referenced by AliMUONRawStreamTriggerHP::AliHeader::DarcIsVadohrType().

template<class EventHandler >

bool AliMUONTriggerDDLDecoder< EventHandler >::Decode	(	const void *	buffer,
		UInt_t	bufferSize,
		bool	scalarEvent = `false`
	)

This method decodes the DDL payload contained in the buffer.

This method should be called to actually decode the DDL payload contained in a memory buffer. The payload should be in the muon trigger system DDL stream format otherwise it will be recognised as corrupt. As the decoder progresses it will make method calls to the event handler instance (which can be accessed with the GetHandler() method) to indicate the start of the DARC header, global header, new regional structures and local card structures.

If an error occurs during the parse, because the data is corrupt, then the OnError method is called indicating what the problem was. Decoding will stop at this point unless the fExitOnError flag is set to false. There is an optional flag fTryRecover which can enable logic which will attempt to recover from corruption of the data structures in the DDL payload, if they are found to be inconsistent (assumed corrupt). The recovery procedure simply involves trying to find in the DDL stream the location of the expected end of header/structure marker/key or the next expected key, and then continue decoding from there. This kind of recovery logic is (and should be) turned off by default and only enabled when trying to recover corrupted data.

Parameters

buffer	This is the pointer to the start of the memory buffer containing the DDL payload. Remember that this must be the start of the payload and not the DDL stream. That is, this pointer should be equal to: DDL start pointer + 8 * sizeof(UInt_t).
bufferSize	This is the pointer to the first byte just past the end of the block structure.
scalarEvent	Set to true if this DDL contains a scalar event and false if it is a normal physics event. If the fAutoDetectScalars flag is true then we ignore this parameter.

Returns: Returns false if there was any problem with decoding the data, and true otherwise. Note: the data may have been partially decoded even if false was returned, which would be indicated by at least one call to the event handler's OnLocalStruct or OnNewRegionalStruct methods.

Definition at line 230 of file AliMUONTriggerDDLDecoder.h.

template<class EventHandler >

void AliMUONTriggerDDLDecoder< EventHandler >::DecodeBuffer	(	const UChar_t *	start,
		const UChar_t *	end,
		bool	scalarEvent
	)

private

This method does the work to decode the buffer's payload data. It unpacks the DARC header, the global header, then calls the DecodeRegionalStructs() method to decode the regional structures. For the DARC and global headers the methods OnDarcHeader and OnGlobalHeader of the event handler object are called respectively.

Parameters

start	This is the pointer to the start of the buffer to decode.
end	This is the pointer to the first byte just past the end of the buffer.
scalarEvent	Set to true if this DDL contains a scalar event and false if it is a normal physics event.

fHadError is set to true if there were any errors decoding the buffer and the OnError method of the callback event handler is called for each error.

Definition at line 285 of file AliMUONTriggerDDLDecoder.h.

template<class EventHandler >

const UChar_t * AliMUONTriggerDDLDecoder< EventHandler >::DecodeLocalStructs	(	const UChar_t *	start,
		const UChar_t *	end,
		bool	scalarEvent
	)

private

This method decodes the local structures in the DDL data for a single regional structure. For each local trigger structure found, the OnLocalStruct method of the event handler is called.

Parameters

start	This is the pointer to the start of the regional structure payload (The pointer just past the regional header key).
end	This is the pointer to the first byte just past the end of the buffer.
scalarEvent	Set to true if this DDL contains a scalar event and false if it is a normal physics event.

Returns: The position in the buffer where this method stopped decoding.

fHadError is set to true if there were any errors decoding the buffer and the OnError method of the callback event handler is called for each error.

Definition at line 691 of file AliMUONTriggerDDLDecoder.h.

template<class EventHandler >

void AliMUONTriggerDDLDecoder< EventHandler >::DecodeRegionalStructs	(	const UChar_t *	start,
		const UChar_t *	end,
		bool	scalarEvent
	)

private

This method decodes the regional structures in the DDL data. For each regional header found, the OnNewRegionalStruct method of the event handler is called, to signal the start of each new regional structure. The DecodeLocalStructs() method is then called to decode the local trigger structures. Finally, a symmetrical call to OnEndOfRegionalStruct of the event handler is called to signal that the regional structure has been decoded.

Parameters

start	This is the pointer to the start of the buffer.
end	This is the pointer to the first byte just past the end of the buffer.
scalarEvent	Set to true if this DDL contains a scalar event and false if it is a normal physics event.

fHadError is set to true if there were any errors decoding the buffer and the OnError method of the callback event handler is called for each error.

Definition at line 536 of file AliMUONTriggerDDLDecoder.h.

template<class EventHandler>

static UInt_t AliMUONTriggerDDLDecoder< EventHandler >::EndOfDarcWord ( )

inlinestatic

Returns the end of DARC marker key.

Definition at line 155 of file AliMUONTriggerDDLDecoder.h.

template<class EventHandler>

static UInt_t AliMUONTriggerDDLDecoder< EventHandler >::EndOfGlobalWord ( )

inlinestatic

Returns the end of global header marker key.

Definition at line 158 of file AliMUONTriggerDDLDecoder.h.

template<class EventHandler>

static UInt_t AliMUONTriggerDDLDecoder< EventHandler >::EndOfLocalWord ( )

inlinestatic

Returns the end of local structure marker key.

Definition at line 167 of file AliMUONTriggerDDLDecoder.h.

template<class EventHandler>

static UInt_t AliMUONTriggerDDLDecoder< EventHandler >::EndOfRegionalWord ( )

inlinestatic

Returns the end of regional structure marker key.

Definition at line 161 of file AliMUONTriggerDDLDecoder.h.

template<class EventHandler>

bool AliMUONTriggerDDLDecoder< EventHandler >::ExitOnError ( ) const

inline

Returns the "exit on error" flag. i.e. should the decoder stop on the very first error found.

Definition at line 109 of file AliMUONTriggerDDLDecoder.h.

template<class EventHandler>

void AliMUONTriggerDDLDecoder< EventHandler >::ExitOnError ( bool value )

inline

Sets the "exit on error" flag. i.e. should the decoder stop on the very first error found.

Definition at line 113 of file AliMUONTriggerDDLDecoder.h.

template<class EventHandler >

const UChar_t * AliMUONTriggerDDLDecoder< EventHandler >::FindKey	(	UInt_t	key,
		const UChar_t *	start,
		const UChar_t *	end
	)

private

Searches for the first occurrence of the key value in the buffer marked by 'start' and 'end'. 'start' should point to the start of the buffer and 'end' should point to 'start + bufferSize'.

Parameters

key	The 32 bit word to look for.
start	The start location to begin the search at.
end	The pointer to the first byte just past end of the buffer to check.

Returns: The location of the first occurance of key in the buffer, otherwise NULL is returned if nothing was found.

Definition at line 848 of file AliMUONTriggerDDLDecoder.h.

template<class EventHandler>

const EventHandler& AliMUONTriggerDDLDecoder< EventHandler >::GetHandler ( ) const

inline

Constant method to return the event handler instance.

Definition at line 102 of file AliMUONTriggerDDLDecoder.h.

template<class EventHandler>

EventHandler& AliMUONTriggerDDLDecoder< EventHandler >::GetHandler ( )

inline

Returns the event handler instance.

Definition at line 105 of file AliMUONTriggerDDLDecoder.h.

template<class EventHandler>

static UInt_t AliMUONTriggerDDLDecoder< EventHandler >::LocalDisableWord ( )

inlinestatic

Returns the local card disable word.

Definition at line 170 of file AliMUONTriggerDDLDecoder.h.

template<class EventHandler>

UInt_t AliMUONTriggerDDLDecoder< EventHandler >::MaxLocals ( ) const

inline

Returns the maximum local structure count expected in any given regional card structure within the DDL payload.

Definition at line 145 of file AliMUONTriggerDDLDecoder.h.

template<class EventHandler>

void AliMUONTriggerDDLDecoder< EventHandler >::MaxLocals ( UInt_t n )

inline

Sets the maximum local structure count expected in any given regional card structure within the DDL payload.

Definition at line 149 of file AliMUONTriggerDDLDecoder.h.

template<class EventHandler>

UInt_t AliMUONTriggerDDLDecoder< EventHandler >::MaxRegionals ( ) const

inline

Returns the maximum regional structure count expected in the DDL payload.

Definition at line 135 of file AliMUONTriggerDDLDecoder.h.

template<class EventHandler>

void AliMUONTriggerDDLDecoder< EventHandler >::MaxRegionals ( UInt_t n )

inline

Sets the maximum regional structure count expected in the DDL payload.

Definition at line 138 of file AliMUONTriggerDDLDecoder.h.

template<class EventHandler>

static UInt_t AliMUONTriggerDDLDecoder< EventHandler >::RegionalErrorWord ( )

inlinestatic

Returns the regional error word.

Definition at line 164 of file AliMUONTriggerDDLDecoder.h.

template<class EventHandler>

UInt_t AliMUONTriggerDDLDecoder< EventHandler >::RegionalsDecoded ( ) const

inline

Returns the number of regional structures we actually attempted to decode.

Definition at line 141 of file AliMUONTriggerDDLDecoder.h.

template<class EventHandler>

bool AliMUONTriggerDDLDecoder< EventHandler >::TryRecover ( ) const

inline

Returns the "try to recover from errors" flag. i.e. should the decoder try to recover from errors found in the payload headers.

Definition at line 118 of file AliMUONTriggerDDLDecoder.h.

template<class EventHandler>

void AliMUONTriggerDDLDecoder< EventHandler >::TryRecover ( bool value )

inline

Sets the "try to recover from errors" flag. i.e. should the decoder try to recover from errors found in the payload headers.

Definition at line 123 of file AliMUONTriggerDDLDecoder.h.

Member Data Documentation

template<class EventHandler>

bool AliMUONTriggerDDLDecoder< EventHandler >::fAutoDetectScalars

private

Flag to indicate if we should auto-detect if there are scalars in the data.

Definition at line 182 of file AliMUONTriggerDDLDecoder.h.

Referenced by AliMUONTriggerDDLDecoder< AliMUONRawStreamTriggerHP::AliDecoderEventHandler >::AutoDetectScalars().

template<class EventHandler>

bool AliMUONTriggerDDLDecoder< EventHandler >::fExitOnError

private

Indicates if we should exit on the very first error.

Definition at line 180 of file AliMUONTriggerDDLDecoder.h.

Referenced by AliMUONTriggerDDLDecoder< AliMUONRawStreamTriggerHP::AliDecoderEventHandler >::ExitOnError().

template<class EventHandler>

const UInt_t AliMUONTriggerDDLDecoder< EventHandler >::fgkDarcDefaultType = 0x6

staticprivate

default type for DARC def.

Definition at line 203 of file AliMUONTriggerDDLDecoder.h.

Referenced by AliMUONTriggerDDLDecoder< AliMUONRawStreamTriggerHP::AliDecoderEventHandler >::DarcDefaultType().

template<class EventHandler>

const UInt_t AliMUONTriggerDDLDecoder< EventHandler >::fgkDarcVadorhType = 0x4

staticprivate

default type for DARC vadorh

Definition at line 204 of file AliMUONTriggerDDLDecoder.h.

Referenced by AliMUONTriggerDDLDecoder< AliMUONRawStreamTriggerHP::AliDecoderEventHandler >::DarcVadorhType().

template<class EventHandler>

const UInt_t AliMUONTriggerDDLDecoder< EventHandler >::fgkDisableWord = 0x10CADEAD

staticprivate

Word used to fill "empty" slots.

Definition at line 202 of file AliMUONTriggerDDLDecoder.h.

Referenced by AliMUONTriggerDDLDecoder< AliMUONRawStreamTriggerHP::AliDecoderEventHandler >::LocalDisableWord().

template<class EventHandler>

const UInt_t AliMUONTriggerDDLDecoder< EventHandler >::fgkEndOfDarc = 0xDEADFACE

staticprivate

Indicates the end of the DARC header.

Definition at line 197 of file AliMUONTriggerDDLDecoder.h.

Referenced by AliMUONTriggerDDLDecoder< AliMUONRawStreamTriggerHP::AliDecoderEventHandler >::EndOfDarcWord().

template<class EventHandler>

const UInt_t AliMUONTriggerDDLDecoder< EventHandler >::fgkEndOfGlobal = 0xDEADBEEF

staticprivate

Indicates the end of the global header just after the DARC header.

Definition at line 198 of file AliMUONTriggerDDLDecoder.h.

Referenced by AliMUONTriggerDDLDecoder< AliMUONRawStreamTriggerHP::AliDecoderEventHandler >::EndOfGlobalWord().

template<class EventHandler>

const UInt_t AliMUONTriggerDDLDecoder< EventHandler >::fgkEndOfLocal = 0xCAFEFADE

staticprivate

Indicates the end of a local card structure.

Definition at line 201 of file AliMUONTriggerDDLDecoder.h.

Referenced by AliMUONTriggerDDLDecoder< AliMUONRawStreamTriggerHP::AliDecoderEventHandler >::EndOfLocalWord().

template<class EventHandler>

const UInt_t AliMUONTriggerDDLDecoder< EventHandler >::fgkEndOfReg = 0xBEEFFACE

staticprivate

Indicates the end of a regional card structure.

Definition at line 199 of file AliMUONTriggerDDLDecoder.h.

Referenced by AliMUONTriggerDDLDecoder< AliMUONRawStreamTriggerHP::AliDecoderEventHandler >::EndOfRegionalWord().

template<class EventHandler>

const UInt_t AliMUONTriggerDDLDecoder< EventHandler >::fgkErrorWord = 0xCAFEDEAD

staticprivate

The error word when a regional board is missing.

Definition at line 200 of file AliMUONTriggerDDLDecoder.h.

Referenced by AliMUONTriggerDDLDecoder< AliMUONRawStreamTriggerHP::AliDecoderEventHandler >::RegionalErrorWord().

template<class EventHandler>

bool AliMUONTriggerDDLDecoder< EventHandler >::fHadError

private

Indicates if we had an error decoding the data.

Definition at line 183 of file AliMUONTriggerDDLDecoder.h.

template<class EventHandler>

EventHandler AliMUONTriggerDDLDecoder< EventHandler >::fHandler

private

The event handler which deals with the generated parsing events.

Definition at line 187 of file AliMUONTriggerDDLDecoder.h.

Referenced by AliMUONTriggerDDLDecoder< AliMUONRawStreamTriggerHP::AliDecoderEventHandler >::GetHandler().

template<class EventHandler>

UInt_t AliMUONTriggerDDLDecoder< EventHandler >::fMaxLocals

private

Maximum number of local card structures per regional structure allowed in a DDL stream.

Definition at line 186 of file AliMUONTriggerDDLDecoder.h.

Referenced by AliMUONTriggerDDLDecoder< AliMUONRawStreamTriggerHP::AliDecoderEventHandler >::MaxLocals().

template<class EventHandler>

UInt_t AliMUONTriggerDDLDecoder< EventHandler >::fMaxRegionals

private

Maximum number of regional card structures allowed in a DDL stream.

Definition at line 185 of file AliMUONTriggerDDLDecoder.h.

Referenced by AliMUONTriggerDDLDecoder< AliMUONRawStreamTriggerHP::AliDecoderEventHandler >::MaxRegionals().

template<class EventHandler>

UInt_t AliMUONTriggerDDLDecoder< EventHandler >::fNoRegionals

private

The number of regional card structures actually decoded.

Definition at line 184 of file AliMUONTriggerDDLDecoder.h.

Referenced by AliMUONTriggerDDLDecoder< AliMUONRawStreamTriggerHP::AliDecoderEventHandler >::RegionalsDecoded().

template<class EventHandler>

bool AliMUONTriggerDDLDecoder< EventHandler >::fTryRecover

private

Indicates if we should try recover from a corrupt structures.

Definition at line 181 of file AliMUONTriggerDDLDecoder.h.

Referenced by AliMUONTriggerDDLDecoder< AliMUONRawStreamTriggerHP::AliDecoderEventHandler >::TryRecover().

The documentation for this class was generated from the following file:

MUON/MUONraw/AliMUONTriggerDDLDecoder.h

Public Member Functions

Static Public Member Functions

Private Member Functions

Private Attributes

Static Private Attributes

Detailed Description

template<class EventHandler> class AliMUONTriggerDDLDecoder< EventHandler >

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation

template<class EventHandler>
class AliMUONTriggerDDLDecoder< EventHandler >