[u/mrichter/AliRoot.git] / HLT / MUON / AliHLTMUONDataBlockReader.h

#ifndef ALIHLTMUONDATABLOCKREADER_H
#define ALIHLTMUONDATABLOCKREADER_H
/**************************************************************************
 * Copyright(c) 1998-2007, ALICE Experiment at CERN, All rights reserved. *
 *                                                                        *
 * Author: The ALICE Off-line Project.                                    *
 * Contributors are mentioned in the code where appropriate.              *
 *                                                                        *
 * Permission to use, copy, modify and distribute this software and its   *
 * documentation strictly for non-commercial purposes is hereby granted   *
 * without fee, provided that the above copyright notice appears in all   *
 * copies and that both the copyright notice and this permission notice   *
 * appear in the supporting documentation. The authors make no claims     *
 * about the suitability of this software for any purpose. It is          *
 * provided "as is" without express or implied warranty.                  *
 **************************************************************************/

/* $Id$ */

/**
 * @file   AliHLTMUONDataBlockReader.h
 * @author Artur Szostak <artursz@iafrica.com>
 * @date   
 * @brief  Definition of a reader class for internal dimuon HLT raw data blocks.
 */

#include "AliHLTMUONDataTypes.h"
#include <cassert>

#include "AliHLTMUONTriggerRecordsBlockStruct.h"
#include "AliHLTMUONTrigRecsDebugBlockStruct.h"
#include "AliHLTMUONTriggerChannelsBlockStruct.h"
#include "AliHLTMUONRecHitsBlockStruct.h"
#include "AliHLTMUONClustersBlockStruct.h"
#include "AliHLTMUONChannelsBlockStruct.h"
#include "AliHLTMUONMansoTracksBlockStruct.h"
#include "AliHLTMUONMansoCandidatesBlockStruct.h"
#include "AliHLTMUONSinglesDecisionBlockStruct.h"
#include "AliHLTMUONPairsDecisionBlockStruct.h"

/**
 * A light weight class for reading the contents of an internal dimuon HLT
 * data block.
 * Suppose we are given a pointer 'buffer' to the buffer where a data block is
 * stored in memory and the size of the data block is given by the variable 'size'.
 * The data block is of type 'block_type' and the data block entries are of type
 * 'entries_type'. The data block can be accessed in the following way:
 *
 *   void* buffer = somebuffer;
 *   AliHLTUInt32_t size = somebuffer_size;
 *   
 *   // Initialise the data block reader.
 *   AliHLTMUONDataBlockReader<block_type, entries_type> block(buffer, size);
 *   
 *   // Check that the buffer has the expected size.
 *   if (not block.BufferSizeOk())
 *   {
 *      // handle error...
 *   }
 *   
 *   // Find the number of entries in the data block.
 *   AliHLTUInt32_t nentries = block.Nentries();
 *   
 *   // Loop over all entries in the data block.
 *   for (AliHLTUInt32_t i = 0; i < nentries; i++)
 *   {
 *      const entries_type& entry = block[i];
 *      // Do something with the entry...
 *   }
 */
template <class DataBlockType, class DataElementType>
class AliHLTMUONDataBlockReader
{
public:
	typedef DataBlockType HeaderType;
	typedef DataElementType ElementType;

	/**
	 * Constructor that sets the internal pointer to the start of the data
	 * block and the total size of the block in bytes.
	 * @param buffer  The pointer to the first byte of the block in memory.
	 * @param size    The total size of the data block in bytes.
	 */
	AliHLTMUONDataBlockReader(const void* buffer, AliHLTUInt32_t size) :
		fSize(size),
		fBlock(reinterpret_cast<const DataBlockType*>(buffer)),
		fData(reinterpret_cast<const DataElementType*>(
		       reinterpret_cast<const DataBlockType*>(buffer) + 1
		      ))
	{
		assert( buffer != NULL );
	}

	/**
	 * Checks that the size of the buffer storing the data block is correct.
	 * Basic sanity checks are performed such as seeing if the data block
	 * size corresponds to the number of reconstructed hits stored and that
	 * the size of the buffer is at least sizeof(DataBlockType) bytes big.
	 */
	bool BufferSizeOk() const
	{
		// The block size must be at least sizeof(DataBlockType) bytes.
		// Do not try read the header otherwise, because we could get a
		// seg fault.
		if (fSize < sizeof(DataBlockType)) return false;

		// Now check if the size of the data block corresponds to the
		// number of entries it claims to contain.
		AliHLTUInt32_t arraysize = fSize - sizeof(DataBlockType);
		return arraysize == Nentries() * sizeof(DataElementType);
	}
	
	/**
	 * Returns the common data block header.
	 */
	const AliHLTMUONDataBlockHeader& CommonBlockHeader() const
	{
		return fBlock->fHeader;
	}
	
	/**
	 * Returns the whole data block header.
	 */
	const DataBlockType& BlockHeader() const
	{
		return *fBlock;
	}

	/**
	 * Returns the total number of entries in the data block.
	 */
	AliHLTUInt32_t Nentries() const { return fBlock->fHeader.fNrecords; }

	/**
	 * Returns a pointer to the i'th entry.
	 * If the index 'i' is out of bounds then NULL is returned.
	 * This is a safe access method because it does bounds checking but is
	 * a little slower than the array operator.
	 * @param i  The index number of the entry to be returned.
	 * @return  A pointer to the entry or NULL.
	 */
	const DataElementType* Entry(AliHLTUInt32_t i) const
	{
		return (i < Nentries()) ? &fData[i] : NULL;
	}

	/**
	 * Array operator for accessing the data entries directly.
	 * The index variable 'i' is not checked (except in debug compilations)
	 * so one should make sure they are within the valid range.
	 */
	const DataElementType& operator [] (AliHLTUInt32_t i) const
	{
		assert( i < Nentries() );
		return fData[i];
	}

	/**
	 * Returns a pointer to the array of elements in the data block.
	 * Care must be taken not to read beyond the array limits given by
	 * Nentries().
	 */
	const DataElementType* GetArray() const { return fData; }

	/**
	 * Calculates the number of bytes used for the data block in the buffer.
	 * This value should be the same as what is returned by BufferSize()
	 * unless too much buffer space was allocated.
	 */
	AliHLTUInt32_t BytesUsed() const
	{
		assert( sizeof(DataElementType)	== fBlock->fHeader.fRecordWidth);
		return sizeof(DataBlockType) + Nentries() * sizeof(DataElementType);
	}

	AliHLTUInt32_t BufferSize() { return fSize; }
	
private:

	AliHLTUInt32_t fSize;   // Size of the data block in bytes.
	const DataBlockType* fBlock; // Pointer to the data block buffer.
	const DataElementType* fData; // Pointer to the data array.
};


// We now define the reader classes for the various data block types from the
// template class AliHLTMUONDataBlockReader.

typedef AliHLTMUONDataBlockReader<
		AliHLTMUONTriggerRecordsBlockStruct,
		AliHLTMUONTriggerRecordStruct
	> AliHLTMUONTriggerRecordsBlockReader;

typedef AliHLTMUONDataBlockReader<
		AliHLTMUONTrigRecsDebugBlockStruct,
		AliHLTMUONTrigRecInfoStruct
	> AliHLTMUONTrigRecsDebugBlockReader;

typedef AliHLTMUONDataBlockReader<
		AliHLTMUONTriggerChannelsBlockStruct,
		AliHLTMUONTriggerChannelStruct
	> AliHLTMUONTriggerChannelsBlockReader;

typedef AliHLTMUONDataBlockReader<
		AliHLTMUONRecHitsBlockStruct,
		AliHLTMUONRecHitStruct
	> AliHLTMUONRecHitsBlockReader;

typedef AliHLTMUONDataBlockReader<
		AliHLTMUONClustersBlockStruct,
		AliHLTMUONClusterStruct
	> AliHLTMUONClustersBlockReader;

typedef AliHLTMUONDataBlockReader<
		AliHLTMUONChannelsBlockStruct,
		AliHLTMUONChannelStruct
	> AliHLTMUONChannelsBlockReader;

typedef AliHLTMUONDataBlockReader<
		AliHLTMUONMansoTracksBlockStruct,
		AliHLTMUONMansoTrackStruct
	> AliHLTMUONMansoTracksBlockReader;

typedef AliHLTMUONDataBlockReader<
		AliHLTMUONMansoCandidatesBlockStruct,
		AliHLTMUONMansoCandidateStruct
	> AliHLTMUONMansoCandidatesBlockReader;

typedef AliHLTMUONDataBlockReader<
		AliHLTMUONSinglesDecisionBlockStruct,
		AliHLTMUONTrackDecisionStruct
	> AliHLTMUONSinglesDecisionBlockReader;

typedef AliHLTMUONDataBlockReader<
		AliHLTMUONPairsDecisionBlockStruct,
		AliHLTMUONPairDecisionStruct
	> AliHLTMUONPairsDecisionBlockReader;

#endif // ALIHLTMUONDATABLOCKREADER_H
Commit	Line	Data
b3eef24e	1	#ifndef ALIHLTMUONDATABLOCKREADER_H
	2	#define ALIHLTMUONDATABLOCKREADER_H
	3	/**************************************************************************
	4	* Copyright(c) 1998-2007, ALICE Experiment at CERN, All rights reserved. *
	5	* *
	6	* Author: The ALICE Off-line Project. *
	7	* Contributors are mentioned in the code where appropriate. *
	8	* *
	9	* Permission to use, copy, modify and distribute this software and its *
	10	* documentation strictly for non-commercial purposes is hereby granted *
	11	* without fee, provided that the above copyright notice appears in all *
	12	* copies and that both the copyright notice and this permission notice *
	13	* appear in the supporting documentation. The authors make no claims *
	14	* about the suitability of this software for any purpose. It is *
	15	* provided "as is" without express or implied warranty. *
	16	**************************************************************************/
	17
	18	/* $Id$ */
	19
	20	/**
	21	* @file AliHLTMUONDataBlockReader.h
	22	* @author Artur Szostak <artursz@iafrica.com>
	23	* @date
	24	* @brief Definition of a reader class for internal dimuon HLT raw data blocks.
	25	*/
	26
	27	#include "AliHLTMUONDataTypes.h"
	28	#include <cassert>
	29
	30	#include "AliHLTMUONTriggerRecordsBlockStruct.h"
	31	#include "AliHLTMUONTrigRecsDebugBlockStruct.h"
	32	#include "AliHLTMUONTriggerChannelsBlockStruct.h"
	33	#include "AliHLTMUONRecHitsBlockStruct.h"
	34	#include "AliHLTMUONClustersBlockStruct.h"
	35	#include "AliHLTMUONChannelsBlockStruct.h"
90a74d7a	36	#include "AliHLTMUONMansoTracksBlockStruct.h"
	37	#include "AliHLTMUONMansoCandidatesBlockStruct.h"
	38	#include "AliHLTMUONSinglesDecisionBlockStruct.h"
	39	#include "AliHLTMUONPairsDecisionBlockStruct.h"
b3eef24e	40
	41	/**
	42	* A light weight class for reading the contents of an internal dimuon HLT
	43	* data block.
	44	* Suppose we are given a pointer 'buffer' to the buffer where a data block is
	45	* stored in memory and the size of the data block is given by the variable 'size'.
	46	* The data block is of type 'block_type' and the data block entries are of type
	47	* 'entries_type'. The data block can be accessed in the following way:
	48	*
	49	* void* buffer = somebuffer;
	50	* AliHLTUInt32_t size = somebuffer_size;
	51	*
	52	* // Initialise the data block reader.
	53	* AliHLTMUONDataBlockReader<block_type, entries_type> block(buffer, size);
	54	*
	55	* // Check that the buffer has the expected size.
	56	* if (not block.BufferSizeOk())
	57	* {
	58	* // handle error...
	59	* }
	60	*
	61	* // Find the number of entries in the data block.
	62	* AliHLTUInt32_t nentries = block.Nentries();
	63	*
	64	* // Loop over all entries in the data block.
	65	* for (AliHLTUInt32_t i = 0; i < nentries; i++)
	66	* {
	67	* const entries_type& entry = block[i];
	68	* // Do something with the entry...
	69	* }
	70	*/
	71	template <class DataBlockType, class DataElementType>
	72	class AliHLTMUONDataBlockReader
	73	{
	74	public:
b12fe461	75	typedef DataBlockType HeaderType;
b12fe461	76	typedef DataElementType ElementType;
b3eef24e	77
	78	/**
	79	* Constructor that sets the internal pointer to the start of the data
	80	* block and the total size of the block in bytes.
	81	* @param buffer The pointer to the first byte of the block in memory.
	82	* @param size The total size of the data block in bytes.
	83	*/
	84	AliHLTMUONDataBlockReader(const void* buffer, AliHLTUInt32_t size) :
	85	fSize(size),
	86	fBlock(reinterpret_cast<const DataBlockType*>(buffer)),
	87	fData(reinterpret_cast<const DataElementType*>(
	88	reinterpret_cast<const DataBlockType*>(buffer) + 1
	89	))
	90	{
	91	assert( buffer != NULL );
	92	}
	93
	94	/**
	95	* Checks that the size of the buffer storing the data block is correct.
	96	* Basic sanity checks are performed such as seeing if the data block
	97	* size corresponds to the number of reconstructed hits stored and that
	98	* the size of the buffer is at least sizeof(DataBlockType) bytes big.
	99	*/
	100	bool BufferSizeOk() const
	101	{
	102	// The block size must be at least sizeof(DataBlockType) bytes.
72836b63	103	// Do not try read the header otherwise, because we could get a
72836b63	104	// seg fault.
b3eef24e	105	if (fSize < sizeof(DataBlockType)) return false;
	106
	107	// Now check if the size of the data block corresponds to the
	108	// number of entries it claims to contain.
	109	AliHLTUInt32_t arraysize = fSize - sizeof(DataBlockType);
	110	return arraysize == Nentries() * sizeof(DataElementType);
	111	}
	112
	113	/**
	114	* Returns the common data block header.
	115	*/
90a74d7a	116	const AliHLTMUONDataBlockHeader& CommonBlockHeader() const
b3eef24e	117	{
	118	return fBlock->fHeader;
	119	}
90a74d7a	120
	121	/**
	122	* Returns the whole data block header.
	123	*/
	124	const DataBlockType& BlockHeader() const
	125	{
72836b63	126	return *fBlock;
90a74d7a	127	}
b3eef24e	128
	129	/**
	130	* Returns the total number of entries in the data block.
	131	*/
	132	AliHLTUInt32_t Nentries() const { return fBlock->fHeader.fNrecords; }
	133
	134	/**
	135	* Returns a pointer to the i'th entry.
	136	* If the index 'i' is out of bounds then NULL is returned.
	137	* This is a safe access method because it does bounds checking but is
	138	* a little slower than the array operator.
	139	* @param i The index number of the entry to be returned.
	140	* @return A pointer to the entry or NULL.
	141	*/
	142	const DataElementType* Entry(AliHLTUInt32_t i) const
	143	{
	144	return (i < Nentries()) ? &fData[i] : NULL;
	145	}
	146
	147	/**
	148	* Array operator for accessing the data entries directly.
	149	* The index variable 'i' is not checked (except in debug compilations)
	150	* so one should make sure they are within the valid range.
	151	*/
	152	const DataElementType& operator [] (AliHLTUInt32_t i) const
	153	{
	154	assert( i < Nentries() );
	155	return fData[i];
	156	}
	157
	158	/**
	159	* Returns a pointer to the array of elements in the data block.
	160	* Care must be taken not to read beyond the array limits given by
	161	* Nentries().
	162	*/
	163	const DataElementType* GetArray() const { return fData; }
	164
72836b63	165	/**
	166	* Calculates the number of bytes used for the data block in the buffer.
	167	* This value should be the same as what is returned by BufferSize()
	168	* unless too much buffer space was allocated.
	169	*/
	170	AliHLTUInt32_t BytesUsed() const
	171	{
	172	assert( sizeof(DataElementType) == fBlock->fHeader.fRecordWidth);
	173	return sizeof(DataBlockType) + Nentries() * sizeof(DataElementType);
	174	}
	175
b12fe461	176	AliHLTUInt32_t BufferSize() { return fSize; }
b12fe461	177
b3eef24e	178	private:
	179
	180	AliHLTUInt32_t fSize; // Size of the data block in bytes.
	181	const DataBlockType* fBlock; // Pointer to the data block buffer.
	182	const DataElementType* fData; // Pointer to the data array.
	183	};
	184
	185
	186	// We now define the reader classes for the various data block types from the
	187	// template class AliHLTMUONDataBlockReader.
	188
	189	typedef AliHLTMUONDataBlockReader<
	190	AliHLTMUONTriggerRecordsBlockStruct,
	191	AliHLTMUONTriggerRecordStruct
	192	> AliHLTMUONTriggerRecordsBlockReader;
	193
	194	typedef AliHLTMUONDataBlockReader<
	195	AliHLTMUONTrigRecsDebugBlockStruct,
	196	AliHLTMUONTrigRecInfoStruct
	197	> AliHLTMUONTrigRecsDebugBlockReader;
	198
	199	typedef AliHLTMUONDataBlockReader<
	200	AliHLTMUONTriggerChannelsBlockStruct,
	201	AliHLTMUONTriggerChannelStruct
	202	> AliHLTMUONTriggerChannelsBlockReader;
	203
	204	typedef AliHLTMUONDataBlockReader<
	205	AliHLTMUONRecHitsBlockStruct,
	206	AliHLTMUONRecHitStruct
	207	> AliHLTMUONRecHitsBlockReader;
	208
	209	typedef AliHLTMUONDataBlockReader<
	210	AliHLTMUONClustersBlockStruct,
	211	AliHLTMUONClusterStruct
	212	> AliHLTMUONClustersBlockReader;
	213
	214	typedef AliHLTMUONDataBlockReader<
	215	AliHLTMUONChannelsBlockStruct,
	216	AliHLTMUONChannelStruct
	217	> AliHLTMUONChannelsBlockReader;
	218
90a74d7a	219	typedef AliHLTMUONDataBlockReader<
	220	AliHLTMUONMansoTracksBlockStruct,
	221	AliHLTMUONMansoTrackStruct
	222	> AliHLTMUONMansoTracksBlockReader;
	223
	224	typedef AliHLTMUONDataBlockReader<
	225	AliHLTMUONMansoCandidatesBlockStruct,
	226	AliHLTMUONMansoCandidateStruct
	227	> AliHLTMUONMansoCandidatesBlockReader;
	228
	229	typedef AliHLTMUONDataBlockReader<
	230	AliHLTMUONSinglesDecisionBlockStruct,
	231	AliHLTMUONTrackDecisionStruct
	232	> AliHLTMUONSinglesDecisionBlockReader;
	233
	234	typedef AliHLTMUONDataBlockReader<
	235	AliHLTMUONPairsDecisionBlockStruct,
	236	AliHLTMUONPairDecisionStruct
	237	> AliHLTMUONPairsDecisionBlockReader;
	238
b3eef24e	239	#endif // ALIHLTMUONDATABLOCKREADER_H