[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 "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:
 * \code
 *   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...
 *   }
 * \endcode
 */
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 );
	}
	
	/**
	 * Copy constructor that performs a shallow copy.
	 * Since this class does not take direct ownership of the buffer, never
	 * allocates or deallocates memory, this can be allowed.
	 */
	AliHLTMUONDataBlockReader(const AliHLTMUONDataBlockReader& reader)
	{
		fSize = reader.fSize;
		fBlock = reader.fBlock;
		fData = reader.fData;
	}
	
	/**
	 * Assignment operator performs a shallow copy.
	 * This is OK because this class does not take direct ownership of the
	 * output memory buffer.
	 */
	AliHLTMUONDataBlockReader& operator = (const AliHLTMUONDataBlockReader& reader)
	{
		fSize = reader.fSize;
		fBlock = reader.fBlock;
		fData = reader.fData;
		return *this;
	}

	/**
	 * 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() const { 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<
		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"
b3eef24e	32	#include "AliHLTMUONRecHitsBlockStruct.h"
	33	#include "AliHLTMUONClustersBlockStruct.h"
	34	#include "AliHLTMUONChannelsBlockStruct.h"
90a74d7a	35	#include "AliHLTMUONMansoTracksBlockStruct.h"
	36	#include "AliHLTMUONMansoCandidatesBlockStruct.h"
	37	#include "AliHLTMUONSinglesDecisionBlockStruct.h"
	38	#include "AliHLTMUONPairsDecisionBlockStruct.h"
b3eef24e	39
	40	/**
	41	* A light weight class for reading the contents of an internal dimuon HLT
	42	* data block.
	43	* Suppose we are given a pointer 'buffer' to the buffer where a data block is
	44	* stored in memory and the size of the data block is given by the variable 'size'.
	45	* The data block is of type 'block_type' and the data block entries are of type
	46	* 'entries_type'. The data block can be accessed in the following way:
1d970015	47	* \code
b3eef24e	48	* void* buffer = somebuffer;
	49	* AliHLTUInt32_t size = somebuffer_size;
	50	*
	51	* // Initialise the data block reader.
	52	* AliHLTMUONDataBlockReader<block_type, entries_type> block(buffer, size);
	53	*
	54	* // Check that the buffer has the expected size.
	55	* if (not block.BufferSizeOk())
	56	* {
	57	* // handle error...
	58	* }
	59	*
	60	* // Find the number of entries in the data block.
	61	* AliHLTUInt32_t nentries = block.Nentries();
	62	*
	63	* // Loop over all entries in the data block.
	64	* for (AliHLTUInt32_t i = 0; i < nentries; i++)
	65	* {
	66	* const entries_type& entry = block[i];
	67	* // Do something with the entry...
	68	* }
1d970015	69	* \endcode
b3eef24e	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	}
d0665ed6	93
	94	/**
	95	* Copy constructor that performs a shallow copy.
	96	* Since this class does not take direct ownership of the buffer, never
	97	* allocates or deallocates memory, this can be allowed.
	98	*/
	99	AliHLTMUONDataBlockReader(const AliHLTMUONDataBlockReader& reader)
	100	{
	101	fSize = reader.fSize;
	102	fBlock = reader.fBlock;
	103	fData = reader.fData;
	104	}
	105
	106	/**
	107	* Assignment operator performs a shallow copy.
	108	* This is OK because this class does not take direct ownership of the
	109	* output memory buffer.
	110	*/
	111	AliHLTMUONDataBlockReader& operator = (const AliHLTMUONDataBlockReader& reader)
	112	{
	113	fSize = reader.fSize;
	114	fBlock = reader.fBlock;
	115	fData = reader.fData;
	116	return *this;
	117	}
b3eef24e	118
	119	/**
	120	* Checks that the size of the buffer storing the data block is correct.
	121	* Basic sanity checks are performed such as seeing if the data block
	122	* size corresponds to the number of reconstructed hits stored and that
	123	* the size of the buffer is at least sizeof(DataBlockType) bytes big.
	124	*/
	125	bool BufferSizeOk() const
	126	{
	127	// The block size must be at least sizeof(DataBlockType) bytes.
72836b63	128	// Do not try read the header otherwise, because we could get a
72836b63	129	// seg fault.
b3eef24e	130	if (fSize < sizeof(DataBlockType)) return false;
	131
	132	// Now check if the size of the data block corresponds to the
	133	// number of entries it claims to contain.
	134	AliHLTUInt32_t arraysize = fSize - sizeof(DataBlockType);
	135	return arraysize == Nentries() * sizeof(DataElementType);
	136	}
	137
	138	/**
	139	* Returns the common data block header.
	140	*/
90a74d7a	141	const AliHLTMUONDataBlockHeader& CommonBlockHeader() const
b3eef24e	142	{
	143	return fBlock->fHeader;
	144	}
90a74d7a	145
	146	/**
	147	* Returns the whole data block header.
	148	*/
	149	const DataBlockType& BlockHeader() const
	150	{
72836b63	151	return *fBlock;
90a74d7a	152	}
b3eef24e	153
	154	/**
	155	* Returns the total number of entries in the data block.
	156	*/
	157	AliHLTUInt32_t Nentries() const { return fBlock->fHeader.fNrecords; }
	158
	159	/**
	160	* Returns a pointer to the i'th entry.
	161	* If the index 'i' is out of bounds then NULL is returned.
	162	* This is a safe access method because it does bounds checking but is
	163	* a little slower than the array operator.
	164	* @param i The index number of the entry to be returned.
	165	* @return A pointer to the entry or NULL.
	166	*/
	167	const DataElementType* Entry(AliHLTUInt32_t i) const
	168	{
	169	return (i < Nentries()) ? &fData[i] : NULL;
	170	}
	171
	172	/**
	173	* Array operator for accessing the data entries directly.
	174	* The index variable 'i' is not checked (except in debug compilations)
	175	* so one should make sure they are within the valid range.
	176	*/
	177	const DataElementType& operator [] (AliHLTUInt32_t i) const
	178	{
	179	assert( i < Nentries() );
	180	return fData[i];
	181	}
	182
	183	/**
	184	* Returns a pointer to the array of elements in the data block.
	185	* Care must be taken not to read beyond the array limits given by
	186	* Nentries().
	187	*/
	188	const DataElementType* GetArray() const { return fData; }
	189
72836b63	190	/**
	191	* Calculates the number of bytes used for the data block in the buffer.
	192	* This value should be the same as what is returned by BufferSize()
	193	* unless too much buffer space was allocated.
	194	*/
	195	AliHLTUInt32_t BytesUsed() const
	196	{
23ad6161	197	assert( sizeof(DataElementType) == fBlock->fHeader.fRecordWidth);
72836b63	198	return sizeof(DataBlockType) + Nentries() * sizeof(DataElementType);
	199	}
	200
154cba94	201	AliHLTUInt32_t BufferSize() const { return fSize; }
b12fe461	202
b3eef24e	203	private:
	204
	205	AliHLTUInt32_t fSize; // Size of the data block in bytes.
	206	const DataBlockType* fBlock; // Pointer to the data block buffer.
	207	const DataElementType* fData; // Pointer to the data array.
	208	};
	209
	210
	211	// We now define the reader classes for the various data block types from the
	212	// template class AliHLTMUONDataBlockReader.
	213
	214	typedef AliHLTMUONDataBlockReader<
	215	AliHLTMUONTriggerRecordsBlockStruct,
	216	AliHLTMUONTriggerRecordStruct
	217	> AliHLTMUONTriggerRecordsBlockReader;
	218
	219	typedef AliHLTMUONDataBlockReader<
	220	AliHLTMUONTrigRecsDebugBlockStruct,
	221	AliHLTMUONTrigRecInfoStruct
	222	> AliHLTMUONTrigRecsDebugBlockReader;
	223
b3eef24e	224	typedef AliHLTMUONDataBlockReader<
	225	AliHLTMUONRecHitsBlockStruct,
	226	AliHLTMUONRecHitStruct
	227	> AliHLTMUONRecHitsBlockReader;
	228
	229	typedef AliHLTMUONDataBlockReader<
	230	AliHLTMUONClustersBlockStruct,
	231	AliHLTMUONClusterStruct
	232	> AliHLTMUONClustersBlockReader;
	233
	234	typedef AliHLTMUONDataBlockReader<
	235	AliHLTMUONChannelsBlockStruct,
	236	AliHLTMUONChannelStruct
	237	> AliHLTMUONChannelsBlockReader;
	238
90a74d7a	239	typedef AliHLTMUONDataBlockReader<
	240	AliHLTMUONMansoTracksBlockStruct,
	241	AliHLTMUONMansoTrackStruct
	242	> AliHLTMUONMansoTracksBlockReader;
	243
	244	typedef AliHLTMUONDataBlockReader<
	245	AliHLTMUONMansoCandidatesBlockStruct,
	246	AliHLTMUONMansoCandidateStruct
	247	> AliHLTMUONMansoCandidatesBlockReader;
	248
	249	typedef AliHLTMUONDataBlockReader<
	250	AliHLTMUONSinglesDecisionBlockStruct,
	251	AliHLTMUONTrackDecisionStruct
	252	> AliHLTMUONSinglesDecisionBlockReader;
	253
	254	typedef AliHLTMUONDataBlockReader<
	255	AliHLTMUONPairsDecisionBlockStruct,
	256	AliHLTMUONPairDecisionStruct
	257	> AliHLTMUONPairsDecisionBlockReader;
	258
b3eef24e	259	#endif // ALIHLTMUONDATABLOCKREADER_H