HLT/MUON/AliHLTMUONUtils.h

   1 #ifndef ALIHLTMUONUTILS_H
   2 #define ALIHLTMUONUTILS_H
   3 /* Copyright(c) 1998-2007, ALICE Experiment at CERN, All rights reserved. *
   4  * See cxx source for full Copyright notice                               */
   5
   6 /* $Id$ */
   7
   8 /**
   9  * @file   AliHLTMUONUtils.h
  10  * @author Artur Szostak <artursz@iafrica.com>
  11  * @date
  12  * @brief  Class containing various dimuon HLT utility routines and macros.
  13  */
  14
  15 #include "AliHLTMUONDataTypes.h"
  16
  17 // Forward declare structures.
  18 extern "C" {
  19 struct AliHLTMUONTriggerRecordStruct;
  20 struct AliHLTMUONTriggerRecordsBlockStruct;
  21 struct AliHLTMUONTrigRecsDebugBlockStruct;
  22 struct AliHLTMUONTriggerChannelsBlockStruct;
  23 struct AliHLTMUONRecHitsBlockStruct;
  24 struct AliHLTMUONClustersBlockStruct;
  25 struct AliHLTMUONChannelsBlockStruct;
  26 struct AliHLTMUONMansoTrackStruct;
  27 struct AliHLTMUONMansoTracksBlockStruct;
  28 struct AliHLTMUONMansoCandidatesBlockStruct;
  29 struct AliHLTMUONTrackDecisionStruct;
  30 struct AliHLTMUONSinglesDecisionBlockStruct;
  31 struct AliHLTMUONPairDecisionStruct;
  32 struct AliHLTMUONPairsDecisionBlockStruct;
  33 } // extern "C"
  34
  35 /**
  36  * AliHLTMUONUtils contains arbitrary utility methods to be used in various
  37  * parts of the dimuon HLT system.
  38  * These include methods to perform basic sanity checks on the integrity of
  39  * data blocks.
  40  */
  41 class AliHLTMUONUtils
  42 {
  43 public:
  44         /**
  45          * This packs the given parameters into the bits of a word appropriate
  46          * for AliHLTMUONTriggerRecordStruct::fFlags.
  47          * @param sign    The particle sign.
  48          * @param hitset  Flags to indicate if the corresponding fHits[i] elements
  49          *                was set/filled.
  50          * @return  Returns the 32 bit packed word.
  51          */
  52         static AliHLTUInt32_t PackTriggerRecordFlags(
  53                         AliHLTMUONParticleSign sign, bool hitset[4]
  54                 );
  55
  56         /**
  57          * This unpacks the AliHLTMUONTriggerRecordStruct::fFlags bits into
  58          * its component fields.
  59          * @param flags  The flags from an AliHLTMUONTriggerRecordStruct structure.
  60          * @param sign    Sets this to the particle sign.
  61          * @param hitset  Sets the array elements to indicate if the corresponding
  62          *                fHits[i] element was set/filled.
  63          */
  64         static void UnpackTriggerRecordFlags(
  65                         AliHLTUInt32_t flags, // [in]
  66                         AliHLTMUONParticleSign& sign, // [out]
  67                         bool hitset[4] // [out]
  68                 );
  69
  70         /**
  71          * This packs the given parameters into the bits of a word appropriate
  72          * for AliHLTMUONMansoTrackStruct::fFlags.
  73          * @param sign    The particle sign.
  74          * @param hitset  Flags to indicate if the corresponding fHits[i] elements
  75          *                was set/filled.
  76          * @return  Returns the 32 bit packed word.
  77          */
  78         static AliHLTUInt32_t PackMansoTrackFlags(
  79                         AliHLTMUONParticleSign sign, bool hitset[4]
  80                 )
  81         {
  82                 return PackTriggerRecordFlags(sign, hitset);
  83         }
  84
  85         /**
  86          * This unpacks the AliHLTMUONMansoTrackStruct::fFlags bits into
  87          * its component fields.
  88          * @param flags  The flags from an AliHLTMUONMansoTrackStruct structure.
  89          * @param sign    Sets this to the particle sign.
  90          * @param hitset  Sets the array elements to indicate if the corresponding
  91          *                fHits[i] element was set/filled.
  92          */
  93         static void UnpackMansoTrackFlags(
  94                         AliHLTUInt32_t flags, // [in]
  95                         AliHLTMUONParticleSign& sign, // [out]
  96                         bool hitset[4] // [out]
  97                 )
  98         {
  99                 UnpackTriggerRecordFlags(flags, sign, hitset);
 100         }
 101
 102         /**
 103          * This packs the given parameters into the bits of a word appropriate
 104          * for AliHLTMUONTrackDecisionStruct::fTriggerBits.
 105          * @param highPt  Has the track passed the high pt cut.
 106          * @param lowPt   Has the track passed the low pt cut.
 107          * @return  Returns the 32 bit packed word.
 108          */
 109         static AliHLTUInt32_t PackTrackDecisionBits(bool highPt, bool lowPt);
 110
 111         /**
 112          * This unpacks the AliHLTMUONTrackDecisionStruct::fTriggerBits bits into
 113          * its component fields.
 114          * @param bits  The trigger bits from an AliHLTMUONTrackDecisionStruct
 115          *              structure.
 116          * @param highPt Sets this to the value of the high pt cut bit.
 117          * @param lowPt  Sets this to the value of the low pt cut bit.
 118          */
 119         static void UnpackTrackDecisionBits(
 120                         AliHLTUInt32_t bits, // [in]
 121                         bool& highPt, // [out]
 122                         bool& lowPt // [out]
 123                 );
 124
 125         /**
 126          * This packs the given parameters into the bits of a word appropriate
 127          * for AliHLTMUONPairDecisionStruct::fTriggerBits.
 128          *
 129          * @param highMass Has the track pair passed the high invariant mass cut.
 130          * @param lowMass  Has the track pair passed the low invariant mass cut.
 131          * @param unlike   Does the track pair have unlike signs.
 132          * @param highPtCount The number of tracks that passed the high pt cut
 133          *                    in the pair.
 134          * @param lowPtCount  The number of tracks that passed the low pt cut
 135          *                    in the pair.
 136          * @return  Returns the 32 bit packed word.
 137          *
 138          * Note: Must have highPtCount + lowPtCount <= 2 and unlike == true if
 139          * highMass or lowMass is true.
 140          */
 141         static AliHLTUInt32_t PackPairDecisionBits(
 142                         bool highMass, bool lowMass, bool unlike,
 143                         AliHLTUInt8_t highPtCount, AliHLTUInt8_t lowPtCount
 144                 );
 145
 146         /**
 147          * This unpacks the AliHLTMUONPairDecisionStruct::fTriggerBits bits into
 148          * its component fields.
 149          * @param bits  The trigger bits from an AliHLTMUONPairDecisionStruct
 150          *              structure.
 151          * @param highMass Sets this to the value of the high invariant mass cut bit.
 152          * @param lowMass  Sets this to the value of the low invariant mass cut bit.
 153          * @param unlike   Sets this if the pair is unlike sign.
 154          * @param highPtCount Sets this to the high pt count bits.
 155          * @param lowPtCount  Sets this to the low pt count bits.
 156          */
 157         static void UnpackPairDecisionBits(
 158                         AliHLTUInt32_t bits, // [in]
 159                         bool& highMass, // [out]
 160                         bool& lowMass, // [out]
 161                         bool& unlike, // [out]
 162                         AliHLTUInt8_t& highPtCount, // [out]
 163                         AliHLTUInt8_t& lowPtCount // [out]
 164                 );
 165
 166         /**
 167          * These codes indicate the reason why a data block failed its
 168          * validity check.
 169          */
 170         enum WhyNotValid
 171         {
 172                 kNoReason,
 173                 kHeaderContainsWrongType,
 174                 kHeaderContainsWrongRecordWidth,
 175         };
 176
 177         /**
 178          * Methods used to check if the header information corresponds to the
 179          * supposed type of the data block.
 180          * If the 'reason' parameter is not NULL then these methods will fill the
 181          * memory pointed to by reason with a code describing of why the header
 182          * is not valid, if and only if a problem is found with the data.
 183          */
 184         static bool HeaderOk(const AliHLTMUONTriggerRecordsBlockStruct& block, WhyNotValid* reason = NULL);
 185         static bool HeaderOk(const AliHLTMUONTrigRecsDebugBlockStruct& block);
 186         static bool HeaderOk(const AliHLTMUONTriggerChannelsBlockStruct& block);
 187         static bool HeaderOk(const AliHLTMUONRecHitsBlockStruct& block);
 188         static bool HeaderOk(const AliHLTMUONClustersBlockStruct& block);
 189         static bool HeaderOk(const AliHLTMUONChannelsBlockStruct& block);
 190         static bool HeaderOk(const AliHLTMUONMansoTracksBlockStruct& block);
 191         static bool HeaderOk(const AliHLTMUONMansoCandidatesBlockStruct& block);
 192         static bool HeaderOk(const AliHLTMUONSinglesDecisionBlockStruct& block);
 193         static bool HeaderOk(const AliHLTMUONPairsDecisionBlockStruct& block);
 194
 195         /**
 196          * Methods used to check more extensively if the integrity of various
 197          * types of data blocks are Ok and returns true in that case.
 198          * These can be slow and should generally only be used for debugging.
 199          */
 200         static bool IntegrityOk(const AliHLTMUONTriggerRecordStruct& tr);
 201         static bool IntegrityOk(const AliHLTMUONTriggerRecordsBlockStruct& block);
 202         static bool IntegrityOk(const AliHLTMUONTrigRecsDebugBlockStruct& block);
 203         static bool IntegrityOk(const AliHLTMUONTriggerChannelsBlockStruct& block);
 204         static bool IntegrityOk(const AliHLTMUONRecHitsBlockStruct& block);
 205         static bool IntegrityOk(const AliHLTMUONClustersBlockStruct& block);
 206         static bool IntegrityOk(const AliHLTMUONChannelsBlockStruct& block);
 207         static bool IntegrityOk(const AliHLTMUONMansoTrackStruct& track);
 208         static bool IntegrityOk(const AliHLTMUONMansoTracksBlockStruct& block);
 209         static bool IntegrityOk(const AliHLTMUONMansoCandidatesBlockStruct& block);
 210         static bool IntegrityOk(const AliHLTMUONTrackDecisionStruct& decision);
 211         static bool IntegrityOk(const AliHLTMUONSinglesDecisionBlockStruct& block);
 212         static bool IntegrityOk(const AliHLTMUONPairDecisionStruct& decision);
 213         static bool IntegrityOk(const AliHLTMUONPairsDecisionBlockStruct& block);
 214
 215 private:
 216         // Should never have to create or destroy this object.
 217         AliHLTMUONUtils();
 218         ~AliHLTMUONUtils();
 219 };
 220
 221 //_____________________________________________________________________________
 222
 223 // Since c++ is missing a finally "keyword" we define one. Its usage is identical
 224 // to a try..finally statement in Java etc.. however, since it is officialy a macro
 225 // one must use the ( ) brackets instead of { }
 226 // If the compiler supports __finally use it otherwise make our own.
 227 #if defined(__BORLANDC__)
 228 #       define finally(str) __finally{str}
 229 #else
 230 #       define finally(code) \
 231                 catch(...) \
 232                 { \
 233                         code \
 234                         throw; \
 235                 }; \
 236                 code
 237 #endif // __BORLANDC__
 238
 239 // If we do not already have them, then define logical operators that are easier
 240 // to read. 'and' = &&, 'or' = ||, 'not' = !
 241 #if ! defined(__GNUC__) && ! defined(__CINT__)
 242 // TODO: Should use iso646.h
 243 #       define and &&
 244 #       define or ||
 245 #       define not !
 246 #endif // __GNUC__ | __CINT__
 247
 248
 249 // Here we define the DebugTrace(message) macro for easy embedding of debug
 250 // information into the dimuon HLT code. Its usage is meant to be for generating
 251 // traces of the program which are only useful during full scale debugging.
 252 // Log messages should use the standard HLT logging mechanisms.
 253 // The output is only generated in programs compiled with the DEBUG directive
 254 // defined. Here is a usage example:
 255 //
 256 //  // statements...
 257 //  DebugTrace("some debug information.");
 258 //  // statements...
 259 //
 260 // One can also use C++ ostream operators and manipulators like so:
 261 //
 262 //  // statements...
 263 //  int x, y;
 264 //  DebugTrace("x = " << x << " and y = 0x" << std::hex << y );
 265 //  // statements...
 266 //
 267 #ifdef DEBUG
 268 #       include <ostream>
 269 #       define DebugTrace(message) {std::cout << message << std::endl;}
 270 #else // DEBUG
 271 #       define DebugTrace(message)
 272 #endif // DEBUG
 273
 274
 275 #endif // ALIHLTMUONUTILS_H