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

#ifndef ALIHLTMUONDATABLOCKWRITER_H
#define ALIHLTMUONDATABLOCKWRITER_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   AliHLTMUONDataBlockWriter.h
 * @author Artur Szostak <artursz@iafrica.com>
 * @date   
 * @brief  Definition of a writer 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 writing an internal dimuon HLT data block.
 * Suppose we are given a pointer 'buffer' to some empty memory buffer where we
 * can store our new data block and the size of the data block is given by the
 * variable 'size'. The data block is of type 'block_type', the data block entries
 * are of type 'entries_type' and the data block type code is 'type_code'.
 * The data block can be written in the following way:
 *
 *   void* buffer = somebuffer;
 *   AliHLTUInt32_t size = somebuffer_size;
 *   
 *   // Initialise the data block writer.
 *   AliHLTMUONDataBlockWriter<block_type, entries_type, type_code>
 *   block(buffer, size);
 *   
 *   // Initialise the block header
 *   if (not block.InitHeader())
 *   {
 *      // handle error and exit...
 *   }
 *   
 *   // Tell the writer how many entries we are going to use.
 *   if (not block.SetNumberOfEntries(somevalue))
 *   {
 *      // handle error and exit...
 *   }
 *
 *   // Add all the entries to the data block.
 *   for (AliHLTUInt32_t i = 0; i < block.Nentries(); i++)
 *   {
 *      entries_type& entry = block[i];
 *      // fill the new entry...
 *      entry.somefield = somevalue;
 *   }
 *
 * The slightly slower but safer method is to do the following:
 *
 *   AliHLTMUONDataBlockWriter<block_type, entries_type, type_code>
 *   block(buffer, size);
 *   if (not block.InitHeader())
 *   {
 *      // handle error and exit...
 *   }
 *   
 *   // For each new entry add it to the data block.
 *   while (HaveMoreEntries())
 *   {
 *      entries_type* entry = block.AddEntry();
 *      // fill the new entry...
 *      entry->somefield = somevalue;
 *   }
 */
template <
	class DataBlockType,
	class DataElementType,
	AliHLTMUONDataBlockType blockTypeCode
>
class AliHLTMUONDataBlockWriter
{
public:

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

	/**
	 * Initialises the common data block header by setting the type and record
	 * width fields. If the buffer size was to small to create the header then
	 * this method returns false, otherwise true on success.
	 */
	bool InitCommonHeader() const
	{
		// The block size must be at least sizeof(DataBlockType) bytes.
		if (fSize < sizeof(DataBlockType)) return false;

		// Now fill the fields in the header.
		fBlock->fHeader.fType = blockTypeCode;
		fBlock->fHeader.fRecordWidth = sizeof(DataElementType);
		fBlock->fHeader.fNrecords = 0;
		return true;
	}
	
	/**
	 * Returns the common data block header.
	 */
	const AliHLTMUONDataBlockHeader& CommonBlockHeader() const
	{
		return fBlock->fHeader;
	}
	
	/**
	 * Returns the whole data block header.
	 */
	DataBlockType& BlockHeader()
	{
		return fBlock;
	}
	
	const DataBlockType& BlockHeader() const
	{
		return fBlock;
	}
	
	/**
	 * Returns a pointer to the next location where a data entry can be
	 * written and increments the number of entries.
	 * If the buffer is already full then NULL is returned and the number of
	 * entries is not changed.
	 */
	DataElementType* AddEntry() const
	{
		if ( (Nentries() + 1) * sizeof(DataElementType) > fMaxArraySize )
			return NULL;
		DataElementType* newentry = &fData[fBlock->fHeader.fNrecords];
		fBlock->fHeader.fNrecords++;
		return newentry;
	}
	
	/**
	 * Sets the number of entries that will be filled into the buffer.
	 * If the number of entries is to many to fit into the buffer then this
	 * method returns false, otherwise true.
	 */
	bool SetNumberOfEntries(AliHLTUInt32_t n) const
	{
		if (n * sizeof(DataElementType) > fMaxArraySize) return false;
		fBlock->fHeader.fNrecords = n;
	}

	/**
	 * Returns the total number of entries already added to 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 operators.
	 * @param i  The index number of the entry to be returned.
	 * @return  A pointer to the entry or NULL.
	 */
	DataElementType* Entry(AliHLTUInt32_t i)
	{
		return (i < Nentries()) ? &fData[i] : 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.
	 */
	DataElementType& operator [] (AliHLTUInt32_t i)
	{
		assert( i < Nentries() );
		return fData[i];
	}
	
	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().
	 */
	DataElementType* GetArray() { return fData; }
	const DataElementType* GetArray() const { return fData; }
	
	/**
	 * Calculates the number of bytes used for the data block in the buffer.
	 * This value will only make sense if a call to InitHeader() was made
	 * and it returned true.
	 */
	AliHLTUInt32_t BytesUsed() const
	{
		assert( Nentries() * sizeof(DataElementType)
			== Nentries() * fBlock->fHeader.fRecordWidth
		);
		
		return sizeof(DataBlockType) + Nentries() * sizeof(DataElementType);
	}
	
	/**
	 * Calculates the maximum number of entries that will fit into the
	 * memory buffer.
	 */
	AliHLTUInt32_t MaxNumberOfEntries() const
	{
		return fMaxArraySize / sizeof(DataElementType);
	}
	
private:

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


// We now define the writer classes for the various data block types from the
// template class AliHLTMUONDataBlockWriter.

typedef AliHLTMUONDataBlockWriter<
		AliHLTMUONTriggerRecordsBlockStruct,
		AliHLTMUONTriggerRecordStruct,
		kTriggerRecordsDataBlock
	> AliHLTMUONTriggerRecordsBlockWriter;

typedef AliHLTMUONDataBlockWriter<
		AliHLTMUONTrigRecsDebugBlockStruct,
		AliHLTMUONTrigRecInfoStruct,
		kTrigRecsDebugDataBlock
	> AliHLTMUONTrigRecsDebugBlockWriter;

typedef AliHLTMUONDataBlockWriter<
		AliHLTMUONTriggerChannelsBlockStruct,
		AliHLTMUONTriggerChannelStruct,
		kTriggerChannelsDataBlock
	> AliHLTMUONTriggerChannelsBlockWriter;

typedef AliHLTMUONDataBlockWriter<
		AliHLTMUONRecHitsBlockStruct,
		AliHLTMUONRecHitStruct,
		kRecHitsDataBlock
	> AliHLTMUONRecHitsBlockWriter;

typedef AliHLTMUONDataBlockWriter<
		AliHLTMUONClustersBlockStruct,
		AliHLTMUONClusterStruct,
		kClustersDataBlock
	> AliHLTMUONClustersBlockWriter;

typedef AliHLTMUONDataBlockWriter<
		AliHLTMUONChannelsBlockStruct,
		AliHLTMUONChannelStruct,
		kChannelsDataBlock
	> AliHLTMUONChannelsBlockWriter;

typedef AliHLTMUONDataBlockWriter<
		AliHLTMUONMansoTracksBlockStruct,
		AliHLTMUONMansoTrackStruct,
		kMansoTracksDataBlock
	> AliHLTMUONMansoTracksBlockWriter;

typedef AliHLTMUONDataBlockWriter<
		AliHLTMUONMansoCandidatesBlockStruct,
		AliHLTMUONMansoCandidateStruct,
		kMansoCandidatesDataBlock
	> AliHLTMUONMansoCandidatesBlockWriter;
	
typedef AliHLTMUONDataBlockWriter<
		AliHLTMUONSinglesDecisionBlockStruct,
		AliHLTMUONTrackDecisionStruct,
		kSinglesDecisionDataBlock
	> AliHLTMUONSinglesDecisionBlockWriter;
	
typedef AliHLTMUONDataBlockWriter<
		AliHLTMUONPairsDecisionBlockStruct,
		AliHLTMUONPairDecisionBlockStruct,
		kPairsDecisionDataBlock
	> AliHLTMUONPairsDecisionBlockWriter;

#endif // ALIHLTMUONDATABLOCKWRITER_H
Commit	Line	Data
b3eef24e	1	#ifndef ALIHLTMUONDATABLOCKWRITER_H
	2	#define ALIHLTMUONDATABLOCKWRITER_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 AliHLTMUONDataBlockWriter.h
	22	* @author Artur Szostak <artursz@iafrica.com>
	23	* @date
	24	* @brief Definition of a writer 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 writing an internal dimuon HLT data block.
	43	* Suppose we are given a pointer 'buffer' to some empty memory buffer where we
	44	* can store our new data block and the size of the data block is given by the
	45	* variable 'size'. The data block is of type 'block_type', the data block entries
	46	* are of type 'entries_type' and the data block type code is 'type_code'.
	47	* The data block can be written in the following way:
	48	*
	49	* void* buffer = somebuffer;
	50	* AliHLTUInt32_t size = somebuffer_size;
	51	*
	52	* // Initialise the data block writer.
	53	* AliHLTMUONDataBlockWriter<block_type, entries_type, type_code>
	54	* block(buffer, size);
	55	*
	56	* // Initialise the block header
	57	* if (not block.InitHeader())
	58	* {
	59	* // handle error and exit...
	60	* }
	61	*
	62	* // Tell the writer how many entries we are going to use.
	63	* if (not block.SetNumberOfEntries(somevalue))
	64	* {
	65	* // handle error and exit...
	66	* }
	67	*
	68	* // Add all the entries to the data block.
	69	* for (AliHLTUInt32_t i = 0; i < block.Nentries(); i++)
	70	* {
	71	* entries_type& entry = block[i];
	72	* // fill the new entry...
	73	* entry.somefield = somevalue;
	74	* }
	75	*
	76	* The slightly slower but safer method is to do the following:
	77	*
	78	* AliHLTMUONDataBlockWriter<block_type, entries_type, type_code>
	79	* block(buffer, size);
	80	* if (not block.InitHeader())
	81	* {
	82	* // handle error and exit...
	83	* }
	84	*
	85	* // For each new entry add it to the data block.
	86	* while (HaveMoreEntries())
	87	* {
	88	* entries_type* entry = block.AddEntry();
	89	* // fill the new entry...
	90	* entry->somefield = somevalue;
	91	* }
	92	*/
	93	template <
	94	class DataBlockType,
	95	class DataElementType,
	96	AliHLTMUONDataBlockType blockTypeCode
	97	>
	98	class AliHLTMUONDataBlockWriter
	99	{
	100	public:
	101
	102	/**
	103	* Constructor that sets the internal pointer to the start of the buffer
104	* space to write to and the total size of the buffer in bytes.
105	* @param buffer The pointer to the first byte of the memory buffer.
106	* @param size The total size of the buffer in bytes.
107	*/
108	AliHLTMUONDataBlockWriter(void* buffer, AliHLTUInt32_t size) :
109	fSize(size),
110	fMaxArraySize(size - sizeof(DataBlockType)),
111	fBlock(reinterpret_cast<DataBlockType*>(buffer)),
112	fData(reinterpret_cast<DataElementType*>(
113	reinterpret_cast<DataBlockType*>(buffer) + 1
114	))
115	{
116	assert( buffer != NULL );
117	}
118
119	/**
90a74d7a	120	* Initialises the common data block header by setting the type and record
	121	* width fields. If the buffer size was to small to create the header then
	122	* this method returns false, otherwise true on success.
b3eef24e	123	*/
90a74d7a	124	bool InitCommonHeader() const
b3eef24e	125	{
	126	// The block size must be at least sizeof(DataBlockType) bytes.
	127	if (fSize < sizeof(DataBlockType)) return false;
	128
	129	// Now fill the fields in the header.
	130	fBlock->fHeader.fType = blockTypeCode;
	131	fBlock->fHeader.fRecordWidth = sizeof(DataElementType);
	132	fBlock->fHeader.fNrecords = 0;
	133	return true;
	134	}
	135
	136	/**
90a74d7a	137	* Returns the common data block header.
b3eef24e	138	*/
90a74d7a	139	const AliHLTMUONDataBlockHeader& CommonBlockHeader() const
b3eef24e	140	{
	141	return fBlock->fHeader;
	142	}
	143
90a74d7a	144	/**
	145	* Returns the whole data block header.
	146	*/
	147	DataBlockType& BlockHeader()
	148	{
	149	return fBlock;
	150	}
	151
	152	const DataBlockType& BlockHeader() const
	153	{
	154	return fBlock;
	155	}
	156
b3eef24e	157	/**
	158	* Returns a pointer to the next location where a data entry can be
	159	* written and increments the number of entries.
	160	* If the buffer is already full then NULL is returned and the number of
	161	* entries is not changed.
	162	*/
	163	DataElementType* AddEntry() const
	164	{
	165	if ( (Nentries() + 1) * sizeof(DataElementType) > fMaxArraySize )
	166	return NULL;
	167	DataElementType* newentry = &fData[fBlock->fHeader.fNrecords];
	168	fBlock->fHeader.fNrecords++;
	169	return newentry;
	170	}
	171
	172	/**
	173	* Sets the number of entries that will be filled into the buffer.
	174	* If the number of entries is to many to fit into the buffer then this
	175	* method returns false, otherwise true.
	176	*/
	177	bool SetNumberOfEntries(AliHLTUInt32_t n) const
	178	{
	179	if (n * sizeof(DataElementType) > fMaxArraySize) return false;
	180	fBlock->fHeader.fNrecords = n;
	181	}
	182
	183	/**
	184	* Returns the total number of entries already added to the data block.
	185	*/
	186	AliHLTUInt32_t Nentries() const { return fBlock->fHeader.fNrecords; }
	187
	188	/**
	189	* Returns a pointer to the i'th entry.
	190	* If the index 'i' is out of bounds then NULL is returned.
	191	* This is a safe access method because it does bounds checking but is
	192	* a little slower than the array operators.
	193	* @param i The index number of the entry to be returned.
	194	* @return A pointer to the entry or NULL.
	195	*/
	196	DataElementType* Entry(AliHLTUInt32_t i)
	197	{
	198	return (i < Nentries()) ? &fData[i] : NULL;
	199	}
	200
	201	const DataElementType* Entry(AliHLTUInt32_t i) const
	202	{
	203	return (i < Nentries()) ? &fData[i] : NULL;
	204	}
	205
	206	/**
	207	* Array operator for accessing the data entries directly.
	208	* The index variable 'i' is not checked (except in debug compilations)
	209	* so one should make sure they are within the valid range.
	210	*/
	211	DataElementType& operator [] (AliHLTUInt32_t i)
	212	{
	213	assert( i < Nentries() );
	214	return fData[i];
	215	}
	216
	217	const DataElementType& operator [] (AliHLTUInt32_t i) const
	218	{
	219	assert( i < Nentries() );
	220	return fData[i];
221	}
222
223	/**
224	* Returns a pointer to the array of elements in the data block.
225	* Care must be taken not to read beyond the array limits given by
226	* Nentries().
227	*/
228	DataElementType* GetArray() { return fData; }
229	const DataElementType* GetArray() const { return fData; }
230
231	/**
232	* Calculates the number of bytes used for the data block in the buffer.
233	* This value will only make sense if a call to InitHeader() was made
234	* and it returned true.
235	*/
236	AliHLTUInt32_t BytesUsed() const
237	{
238	assert( Nentries() * sizeof(DataElementType)
239	== Nentries() * fBlock->fHeader.fRecordWidth
240	);
241
242	return sizeof(DataBlockType) + Nentries() * sizeof(DataElementType);
243	}
244
245	/**
246	* Calculates the maximum number of entries that will fit into the
247	* memory buffer.
248	*/
249	AliHLTUInt32_t MaxNumberOfEntries() const
250	{
251	return fMaxArraySize / sizeof(DataElementType);
252	}
253
254	private:
255
256	AliHLTUInt32_t fSize; // Size of the buffer in bytes.
257	AliHLTUInt32_t fMaxArraySize; // Maximum size of the fData array in bytes.
258	DataBlockType* fBlock; // Pointer to the start of the data block.
259	DataElementType* fData; // Pointer to the start of the data array.
260	};
261
262
263	// We now define the writer classes for the various data block types from the
264	// template class AliHLTMUONDataBlockWriter.
265
266	typedef AliHLTMUONDataBlockWriter<
267	AliHLTMUONTriggerRecordsBlockStruct,
268	AliHLTMUONTriggerRecordStruct,
269	kTriggerRecordsDataBlock
270	> AliHLTMUONTriggerRecordsBlockWriter;
271
272	typedef AliHLTMUONDataBlockWriter<
273	AliHLTMUONTrigRecsDebugBlockStruct,
274	AliHLTMUONTrigRecInfoStruct,
275	kTrigRecsDebugDataBlock
276	> AliHLTMUONTrigRecsDebugBlockWriter;
277
278	typedef AliHLTMUONDataBlockWriter<
279	AliHLTMUONTriggerChannelsBlockStruct,
280	AliHLTMUONTriggerChannelStruct,
281	kTriggerChannelsDataBlock
282	> AliHLTMUONTriggerChannelsBlockWriter;
283
284	typedef AliHLTMUONDataBlockWriter<
285	AliHLTMUONRecHitsBlockStruct,
286	AliHLTMUONRecHitStruct,
287	kRecHitsDataBlock
288	> AliHLTMUONRecHitsBlockWriter;
289
290	typedef AliHLTMUONDataBlockWriter<
291	AliHLTMUONClustersBlockStruct,
292	AliHLTMUONClusterStruct,
293	kClustersDataBlock
294	> AliHLTMUONClustersBlockWriter;
295
296	typedef AliHLTMUONDataBlockWriter<
297	AliHLTMUONChannelsBlockStruct,
298	AliHLTMUONChannelStruct,
299	kChannelsDataBlock
300	> AliHLTMUONChannelsBlockWriter;
301
90a74d7a	302	typedef AliHLTMUONDataBlockWriter<
	303	AliHLTMUONMansoTracksBlockStruct,
	304	AliHLTMUONMansoTrackStruct,
	305	kMansoTracksDataBlock
	306	> AliHLTMUONMansoTracksBlockWriter;
	307
	308	typedef AliHLTMUONDataBlockWriter<
	309	AliHLTMUONMansoCandidatesBlockStruct,
	310	AliHLTMUONMansoCandidateStruct,
	311	kMansoCandidatesDataBlock
	312	> AliHLTMUONMansoCandidatesBlockWriter;
	313
	314	typedef AliHLTMUONDataBlockWriter<
	315	AliHLTMUONSinglesDecisionBlockStruct,
	316	AliHLTMUONTrackDecisionStruct,
	317	kSinglesDecisionDataBlock
	318	> AliHLTMUONSinglesDecisionBlockWriter;
	319
	320	typedef AliHLTMUONDataBlockWriter<
	321	AliHLTMUONPairsDecisionBlockStruct,
	322	AliHLTMUONPairDecisionBlockStruct,
	323	kPairsDecisionDataBlock
	324	> AliHLTMUONPairsDecisionBlockWriter;
	325
b3eef24e	326	#endif // ALIHLTMUONDATABLOCKWRITER_H