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, const 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, const 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          * This packs the given parameters into the 32bit Pub/Sub specification
 168          * word in the data block descriptor.
 169          *
 170          * @param ddl  The list of DDLs forming part of the readout. ddl[0]
 171          *             indicates DDL number 2560, ddl[1] is for DDL 2561 and so
 172          *             on up to ddl[19]. ddl[20] and ddl[21] will be for the
 173          *             trigger DDLs 2816 and 2817 respectively.
 174          * @return  Returns the 32 bit packed specification word.
 175          */
 176         static AliHLTUInt32_t PackSpecBits(
 177                         const bool ddl[22]
 178                 );
 179
 180         /**
 181          * This unpacks the AliHLTMUONPairDecisionStruct::fTriggerBits bits into
 182          * its component fields.
 183          * @param bits  The Pub/Sub specification word from a data block descriptor.
 184          * @param ddl  The output list of DDLs forming part of the readout. ddl[0]
 185          *             indicates DDL number 2560, ddl[1] is for DDL 2561 and so
 186          *             on up to ddl[19]. ddl[20] and ddl[21] will be for the
 187          *             trigger DDLs 2816 and 2817 respectively.
 188          */
 189         static void UnpackSpecBits(
 190                         AliHLTUInt32_t bits, // [in]
 191                         bool ddl[22] // [out]
 192                 );
 193
 194         /**
 195          * These codes indicate the reason why a data block failed its
 196          * validity check.
 197          */
 198         enum WhyNotValid
 199         {
 200                 kNoReason,
 201                 kHeaderContainsWrongType,
 202                 kHeaderContainsWrongRecordWidth,
 203         };
 204
 205         /**
 206          * Methods used to check if the header information corresponds to the
 207          * supposed type of the data block.
 208          * If the 'reason' parameter is not NULL then these methods will fill the
 209          * memory pointed to by reason with a code describing of why the header
 210          * is not valid, if and only if a problem is found with the data.
 211          */
 212         static bool HeaderOk(const AliHLTMUONTriggerRecordsBlockStruct& block, WhyNotValid* reason = NULL);
 213         static bool HeaderOk(const AliHLTMUONTrigRecsDebugBlockStruct& block);
 214         static bool HeaderOk(const AliHLTMUONTriggerChannelsBlockStruct& block);
 215         static bool HeaderOk(const AliHLTMUONRecHitsBlockStruct& block);
 216         static bool HeaderOk(const AliHLTMUONClustersBlockStruct& block);
 217         static bool HeaderOk(const AliHLTMUONChannelsBlockStruct& block);
 218         static bool HeaderOk(const AliHLTMUONMansoTracksBlockStruct& block);
 219         static bool HeaderOk(const AliHLTMUONMansoCandidatesBlockStruct& block);
 220         static bool HeaderOk(const AliHLTMUONSinglesDecisionBlockStruct& block);
 221         static bool HeaderOk(const AliHLTMUONPairsDecisionBlockStruct& block);
 222
 223         /**
 224          * Methods used to check more extensively if the integrity of various
 225          * types of data blocks are Ok and returns true in that case.
 226          * These can be slow and should generally only be used for debugging.
 227          */
 228         static bool IntegrityOk(const AliHLTMUONTriggerRecordStruct& tr);
 229         static bool IntegrityOk(const AliHLTMUONTriggerRecordsBlockStruct& block);
 230         static bool IntegrityOk(const AliHLTMUONTrigRecsDebugBlockStruct& block);
 231         static bool IntegrityOk(const AliHLTMUONTriggerChannelsBlockStruct& block);
 232         static bool IntegrityOk(const AliHLTMUONRecHitsBlockStruct& block);
 233         static bool IntegrityOk(const AliHLTMUONClustersBlockStruct& block);
 234         static bool IntegrityOk(const AliHLTMUONChannelsBlockStruct& block);
 235         static bool IntegrityOk(const AliHLTMUONMansoTrackStruct& track);
 236         static bool IntegrityOk(const AliHLTMUONMansoTracksBlockStruct& block);
 237         static bool IntegrityOk(const AliHLTMUONMansoCandidatesBlockStruct& block);
 238         static bool IntegrityOk(const AliHLTMUONTrackDecisionStruct& decision);
 239         static bool IntegrityOk(const AliHLTMUONSinglesDecisionBlockStruct& block);
 240         static bool IntegrityOk(const AliHLTMUONPairDecisionStruct& decision);
 241         static bool IntegrityOk(const AliHLTMUONPairsDecisionBlockStruct& block);
 242
 243 private:
 244         // Should never have to create or destroy this object.
 245         AliHLTMUONUtils();
 246         ~AliHLTMUONUtils();
 247 };
 248
 249 //_____________________________________________________________________________
 250
 251 // Since c++ is missing a finally "keyword" we define one. Its usage is identical
 252 // to a try..finally statement in Java etc.. however, since it is officialy a macro
 253 // one must use the ( ) brackets instead of { }
 254 // If the compiler supports __finally use it otherwise make our own.
 255 #if defined(__BORLANDC__)
 256 #       define finally(str) __finally{str}
 257 #else
 258 #       define finally(code) \
 259                 catch(...) \
 260                 { \
 261                         code \
 262                         throw; \
 263                 }; \
 264                 code
 265 #endif // __BORLANDC__
 266
 267 // If we do not already have them, then define logical operators that are easier
 268 // to read. 'and' = &&, 'or' = ||, 'not' = !
 269 #if ! defined(__GNUC__) && ! defined(__CINT__)
 270 // TODO: Should use iso646.h
 271 #       define and &&
 272 #       define or ||
 273 #       define not !
 274 #endif // __GNUC__ | __CINT__
 275
 276
 277 // Here we define the DebugTrace(message) macro for easy embedding of debug
 278 // information into the dimuon HLT code. Its usage is meant to be for generating
 279 // traces of the program which are only useful during full scale debugging.
 280 // Log messages should use the standard HLT logging mechanisms.
 281 // The output is only generated in programs compiled with the DEBUG directive
 282 // defined. Here is a usage example:
 283 //
 284 //  // statements...
 285 //  DebugTrace("some debug information.");
 286 //  // statements...
 287 //
 288 // One can also use C++ ostream operators and manipulators like so:
 289 //
 290 //  // statements...
 291 //  int x, y;
 292 //  DebugTrace("x = " << x << " and y = 0x" << std::hex << y );
 293 //  // statements...
 294 //
 295 #ifdef DEBUG
 296 #       include <iostream>
 297 #       define DebugTrace(message) {std::cout << message << std::endl;}
 298 #else // DEBUG
 299 #       define DebugTrace(message)
 300 #endif // DEBUG
 301
 302
 303 #endif // ALIHLTMUONUTILS_H