HLT/MUON/AliHLTMUONDataBlockReader.h

   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   19 May 2007
  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 "AliHLTMUONRecHitsBlockStruct.h"
  33 #include "AliHLTMUONClustersBlockStruct.h"
  34 #include "AliHLTMUONChannelsBlockStruct.h"
  35 #include "AliHLTMUONMansoTracksBlockStruct.h"
  36 #include "AliHLTMUONMansoCandidatesBlockStruct.h"
  37 #include "AliHLTMUONTracksBlockStruct.h"
  38 #include "AliHLTMUONSinglesDecisionBlockStruct.h"
  39 #include "AliHLTMUONPairsDecisionBlockStruct.h"
  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  * \code
  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  * \endcode
  71  */
  72 template <class DataBlockType, class DataElementType>
  73 class AliHLTMUONDataBlockReader
  74 {
  75 public:
  76         typedef DataBlockType HeaderType;
  77         typedef DataElementType ElementType;
  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         }
  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         }
 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.
 129                 // Do not try read the header otherwise, because we could get a
 130                 // seg fault.
 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          */
 142         const AliHLTMUONDataBlockHeader& CommonBlockHeader() const
 143         {
 144                 return fBlock->fHeader;
 145         }
 146
 147         /**
 148          * Returns the whole data block header.
 149          */
 150         const DataBlockType& BlockHeader() const
 151         {
 152                 return *fBlock;
 153         }
 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
 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         {
 198                 assert( sizeof(DataElementType) == fBlock->fHeader.fRecordWidth);
 199                 return sizeof(DataBlockType) + Nentries() * sizeof(DataElementType);
 200         }
 201
 202         AliHLTUInt32_t BufferSize() const { return fSize; }
 203
 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
 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
 240 typedef AliHLTMUONDataBlockReader<
 241                 AliHLTMUONMansoTracksBlockStruct,
 242                 AliHLTMUONMansoTrackStruct
 243         > AliHLTMUONMansoTracksBlockReader;
 244
 245 typedef AliHLTMUONDataBlockReader<
 246                 AliHLTMUONMansoCandidatesBlockStruct,
 247                 AliHLTMUONMansoCandidateStruct
 248         > AliHLTMUONMansoCandidatesBlockReader;
 249
 250 typedef AliHLTMUONDataBlockReader<
 251                 AliHLTMUONTracksBlockStruct,
 252                 AliHLTMUONTrackStruct
 253         > AliHLTMUONTracksBlockReader;
 254
 255 typedef AliHLTMUONDataBlockReader<
 256                 AliHLTMUONSinglesDecisionBlockStruct,
 257                 AliHLTMUONTrackDecisionStruct
 258         > AliHLTMUONSinglesDecisionBlockReader;
 259
 260 typedef AliHLTMUONDataBlockReader<
 261                 AliHLTMUONPairsDecisionBlockStruct,
 262                 AliHLTMUONPairDecisionStruct
 263         > AliHLTMUONPairsDecisionBlockReader;
 264
 265 #endif // ALIHLTMUONDATABLOCKREADER_H