[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   19 May 2007
 * @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 "AliHLTMUONTracksBlockStruct.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<
		AliHLTMUONTracksBlockStruct,
		AliHLTMUONTrackStruct
	> AliHLTMUONTracksBlockReader;

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
1d8ae082	18	// $Id$
b3eef24e	19
	20	/**
	21	* @file AliHLTMUONDataBlockReader.h
	22	* @author Artur Szostak <artursz@iafrica.com>
1d8ae082	23	* @date 19 May 2007
b3eef24e	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"
90a74d7a	36	#include "AliHLTMUONMansoCandidatesBlockStruct.h"
a8982f78	37	#include "AliHLTMUONTracksBlockStruct.h"
90a74d7a	38	#include "AliHLTMUONSinglesDecisionBlockStruct.h"
90a74d7a	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:
1d970015	48	* \code
b3eef24e	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	* }
1d970015	70	* \endcode
b3eef24e	71	*/
	72	template <class DataBlockType, class DataElementType>
	73	class AliHLTMUONDataBlockReader
	74	{
	75	public:
b12fe461	76	typedef DataBlockType HeaderType;
b12fe461	77	typedef DataElementType ElementType;
b3eef24e	78
	79	/**
	80	* Constructor that sets the internal pointer to the start of the data
	81	* block and the total size of the block in bytes.
	82	* @param buffer The pointer to the first byte of the block in memory.
	83	* @param size The total size of the data block in bytes.
	84	*/
	85	AliHLTMUONDataBlockReader(const void* buffer, AliHLTUInt32_t size) :
	86	fSize(size),
	87	fBlock(reinterpret_cast<const DataBlockType*>(buffer)),
	88	fData(reinterpret_cast<const DataElementType*>(
	89	reinterpret_cast<const DataBlockType*>(buffer) + 1
	90	))
	91	{
	92	assert( buffer != NULL );
	93	}
d0665ed6	94
	95	/**
	96	* Copy constructor that performs a shallow copy.
	97	* Since this class does not take direct ownership of the buffer, never
	98	* allocates or deallocates memory, this can be allowed.
	99	*/
	100	AliHLTMUONDataBlockReader(const AliHLTMUONDataBlockReader& reader)
	101	{
	102	fSize = reader.fSize;
	103	fBlock = reader.fBlock;
	104	fData = reader.fData;
	105	}
	106
	107	/**
	108	* Assignment operator performs a shallow copy.
	109	* This is OK because this class does not take direct ownership of the
	110	* output memory buffer.
	111	*/
	112	AliHLTMUONDataBlockReader& operator = (const AliHLTMUONDataBlockReader& reader)
	113	{
	114	fSize = reader.fSize;
	115	fBlock = reader.fBlock;
	116	fData = reader.fData;
	117	return *this;
	118	}
b3eef24e	119
	120	/**
	121	* Checks that the size of the buffer storing the data block is correct.
	122	* Basic sanity checks are performed such as seeing if the data block
	123	* size corresponds to the number of reconstructed hits stored and that
	124	* the size of the buffer is at least sizeof(DataBlockType) bytes big.
	125	*/
	126	bool BufferSizeOk() const
	127	{
	128	// The block size must be at least sizeof(DataBlockType) bytes.
72836b63	129	// Do not try read the header otherwise, because we could get a
72836b63	130	// seg fault.
b3eef24e	131	if (fSize < sizeof(DataBlockType)) return false;
	132
	133	// Now check if the size of the data block corresponds to the
	134	// number of entries it claims to contain.
	135	AliHLTUInt32_t arraysize = fSize - sizeof(DataBlockType);
	136	return arraysize == Nentries() * sizeof(DataElementType);
	137	}
	138
	139	/**
	140	* Returns the common data block header.
	141	*/
90a74d7a	142	const AliHLTMUONDataBlockHeader& CommonBlockHeader() const
b3eef24e	143	{
	144	return fBlock->fHeader;
	145	}
90a74d7a	146
	147	/**
	148	* Returns the whole data block header.
	149	*/
	150	const DataBlockType& BlockHeader() const
	151	{
72836b63	152	return *fBlock;
90a74d7a	153	}
b3eef24e	154
	155	/**
	156	* Returns the total number of entries in the data block.
	157	*/
	158	AliHLTUInt32_t Nentries() const { return fBlock->fHeader.fNrecords; }
	159
	160	/**
	161	* Returns a pointer to the i'th entry.
	162	* If the index 'i' is out of bounds then NULL is returned.
	163	* This is a safe access method because it does bounds checking but is
	164	* a little slower than the array operator.
	165	* @param i The index number of the entry to be returned.
	166	* @return A pointer to the entry or NULL.
	167	*/
	168	const DataElementType* Entry(AliHLTUInt32_t i) const
	169	{
	170	return (i < Nentries()) ? &fData[i] : NULL;
	171	}
	172
	173	/**
	174	* Array operator for accessing the data entries directly.
	175	* The index variable 'i' is not checked (except in debug compilations)
	176	* so one should make sure they are within the valid range.
	177	*/
	178	const DataElementType& operator [] (AliHLTUInt32_t i) const
	179	{
	180	assert( i < Nentries() );
	181	return fData[i];
	182	}
	183
	184	/**
	185	* Returns a pointer to the array of elements in the data block.
	186	* Care must be taken not to read beyond the array limits given by
	187	* Nentries().
	188	*/
	189	const DataElementType* GetArray() const { return fData; }
	190
72836b63	191	/**
	192	* Calculates the number of bytes used for the data block in the buffer.
	193	* This value should be the same as what is returned by BufferSize()
	194	* unless too much buffer space was allocated.
	195	*/
	196	AliHLTUInt32_t BytesUsed() const
	197	{
23ad6161	198	assert( sizeof(DataElementType) == fBlock->fHeader.fRecordWidth);
72836b63	199	return sizeof(DataBlockType) + Nentries() * sizeof(DataElementType);
	200	}
	201
154cba94	202	AliHLTUInt32_t BufferSize() const { return fSize; }
b12fe461	203
b3eef24e	204	private:
	205
	206	AliHLTUInt32_t fSize; // Size of the data block in bytes.
	207	const DataBlockType* fBlock; // Pointer to the data block buffer.
	208	const DataElementType* fData; // Pointer to the data array.
	209	};
	210
	211
	212	// We now define the reader classes for the various data block types from the
	213	// template class AliHLTMUONDataBlockReader.
	214
	215	typedef AliHLTMUONDataBlockReader<
	216	AliHLTMUONTriggerRecordsBlockStruct,
	217	AliHLTMUONTriggerRecordStruct
	218	> AliHLTMUONTriggerRecordsBlockReader;
	219
	220	typedef AliHLTMUONDataBlockReader<
	221	AliHLTMUONTrigRecsDebugBlockStruct,
	222	AliHLTMUONTrigRecInfoStruct
	223	> AliHLTMUONTrigRecsDebugBlockReader;
	224
b3eef24e	225	typedef AliHLTMUONDataBlockReader<
	226	AliHLTMUONRecHitsBlockStruct,
	227	AliHLTMUONRecHitStruct
	228	> AliHLTMUONRecHitsBlockReader;
	229
	230	typedef AliHLTMUONDataBlockReader<
	231	AliHLTMUONClustersBlockStruct,
	232	AliHLTMUONClusterStruct
	233	> AliHLTMUONClustersBlockReader;
	234
	235	typedef AliHLTMUONDataBlockReader<
	236	AliHLTMUONChannelsBlockStruct,
	237	AliHLTMUONChannelStruct
	238	> AliHLTMUONChannelsBlockReader;
	239
90a74d7a	240	typedef AliHLTMUONDataBlockReader<
	241	AliHLTMUONMansoTracksBlockStruct,
	242	AliHLTMUONMansoTrackStruct
	243	> AliHLTMUONMansoTracksBlockReader;
	244
	245	typedef AliHLTMUONDataBlockReader<
	246	AliHLTMUONMansoCandidatesBlockStruct,
	247	AliHLTMUONMansoCandidateStruct
	248	> AliHLTMUONMansoCandidatesBlockReader;
	249
a8982f78	250	typedef AliHLTMUONDataBlockReader<
	251	AliHLTMUONTracksBlockStruct,
	252	AliHLTMUONTrackStruct
	253	> AliHLTMUONTracksBlockReader;
	254
90a74d7a	255	typedef AliHLTMUONDataBlockReader<
	256	AliHLTMUONSinglesDecisionBlockStruct,
	257	AliHLTMUONTrackDecisionStruct
	258	> AliHLTMUONSinglesDecisionBlockReader;
	259
	260	typedef AliHLTMUONDataBlockReader<
	261	AliHLTMUONPairsDecisionBlockStruct,
	262	AliHLTMUONPairDecisionStruct
	263	> AliHLTMUONPairsDecisionBlockReader;
	264
b3eef24e	265	#endif // ALIHLTMUONDATABLOCKREADER_H