HLT/MUON/AliHLTMUONProcessor.h

   1 #ifndef ALIHLTMUONPROCESSOR_H
   2 #define ALIHLTMUONPROCESSOR_H
   3 /* This file is property of and copyright by the ALICE HLT Project        *
   4  * ALICE Experiment at CERN, All rights reserved.                         *
   5  * See cxx source for full Copyright notice                               */
   6
   7 /* $Id: $ */
   8
   9 ///
  10 /// @file   AliHLTMUONProcessor.h
  11 /// @author Artur Szostak <artursz@iafrica.com>
  12 /// @date   19 May 2008
  13 /// @brief  Declaration of a common processor component abstract interface for dHLT components.
  14 ///
  15
  16 #include "AliHLTProcessor.h"
  17 #include "AliHLTMUONDataBlockReader.h"
  18 #include "AliHLTMUONUtils.h"
  19
  20 class TMap;
  21 class AliMUONRecoParam;
  22
  23 /**
  24  * @class AliHLTMUONProcessor
  25  * This component class is an abstract base class for dHLT components.
  26  * Some common methods useful to all dHLT specific components are implemented
  27  * by this class.
  28  *
  29  * @ingroup alihlt_dimuon_component
  30  */
  31 class AliHLTMUONProcessor : public AliHLTProcessor
  32 {
  33 public:
  34         /// Default constructor.
  35         AliHLTMUONProcessor();
  36
  37         /// Default destructor.
  38         virtual ~AliHLTMUONProcessor() {}
  39
  40 protected:
  41
  42         /**
  43          * This method parses the common arguments for dHLT processing components
  44          * and initialises the common internal state.
  45          * Deriving classes can use the ArgumentAlreadyHandled method to check if
  46          * the parent class has processed a particular argument. The following is
  47          * an example of this:
  48          *
  49          * \code
  50          * int DerivedClass::DoInit(int argc, const char** argv)
  51          * {
  52          *   int result = AliHLTMUONProcessor::DoInit(argc, argv);
  53          *   if (result != 0) return result;
  54          *   for (int i = 0; i < argc; i++)
  55          *   {
  56          *     if (ArgumentAlreadyHandled(i, argv[i])) continue;
  57          *     // ... handle custom arguments here ...
  58          *   }
  59          * }
  60          * \endcode
  61          */
  62         virtual int DoInit(int argc, const char** argv);
  63
  64         /**
  65          * This method can be used by the derivind child class to check if a particular
  66          * argument in argv was already processed.
  67          * \note This assumes that the deriving class called the DoInit method of the
  68          * parent class in its own DoInit method.
  69          */
  70         virtual bool ArgumentAlreadyHandled(int& i, const char* argi) const;
  71
  72         /**
  73          * This method returns the command line arguments that should not be parsed
  74          * by this class. This method can be used by child classes that derive from
  75          * AliHLTMUONProcessor, to indicate which arguments should not be handled by
  76          * the AliHLTMUONProcessor::DoInit method. Default return value is false.
  77          */
  78         virtual bool IgnoreArgument(const char* /*arg*/) const { return false; }
  79
  80         /**
  81          * Returns true if the component was told to delay initialisation from
  82          * CDB until the first start of run event. This gets set by the -delaysetup
  83          * flag which is processed in AliHLTMUONProcessor::DoInit.
  84          */
  85         bool DelaySetup() const { return fDelaySetup; }
  86
  87         /**
  88          * This method should be called when a derived component has handled a
  89          * delayed setup requested on the command line with -delaysetup and indicated
  90          * by the flag returned by the DelaySetup method.
  91          */
  92         void DoneDelayedSetup() { fDelaySetup = false; }
  93
  94         /**
  95          * Returns true if the component has the flag set indicating to dump raw
  96          * data when an error occurs. The DumpEvent method should be used by the
  97          * deriving components to actually dump data at the appropriate point.
  98          * \note This facility is intended for debugging.
  99          */
 100         bool DumpDataOnError() const { return fDumpDataOnError; }
 101
 102         /**
 103          * Returns the path where the dump files will be written to by the Dump*
 104          * methods. Defaults to the current working directory.
 105          * \note This facility is intended for debugging.
 106          */
 107         const char* DumpPath() const { return fDumpPath; }
 108
 109         /**
 110          * Method to check the block structure and log appropriate error messages.
 111          * If a problem is found with the data block then an appropriate HLT error
 112          * message is logged and the method returns false.
 113          * \param block  The lightweight block reader whose data block should be checked.
 114          * \param name  A string containing a descriptive name of the data block
 115          *          type. This name is used in the logged error messages.
 116          * \param checkHeader  Indicates if the common data block header should be checked.
 117          * \returns  true if the structure of the block looks OK and false otherwise.
 118          * \note  The BlockType should be a class deriving from AliHLTMUONDataBlockReader.
 119          */
 120         template <class BlockType>
 121         bool BlockStructureOk(
 122                         const BlockType& block, const char* name,
 123                         bool checkHeader = true
 124                 ) const;
 125
 126         /// Checks the structure of a trigger records data block.
 127         bool BlockStructureOk(
 128                         const AliHLTMUONTriggerRecordsBlockReader& block,
 129                         bool checkHeader = true
 130                 ) const
 131         {
 132                 return BlockStructureOk(block, "trigger records", checkHeader);
 133         }
 134
 135         /// Checks the structure of a trigger records debug information data block.
 136         bool BlockStructureOk(
 137                         const AliHLTMUONTrigRecsDebugBlockReader& block,
 138                         bool checkHeader = true
 139                 ) const
 140         {
 141                 return BlockStructureOk(block, "trigger records debug information", checkHeader);
 142         }
 143
 144         /// Checks the structure of a reconstructed hits data block.
 145         bool BlockStructureOk(
 146                         const AliHLTMUONRecHitsBlockReader& block,
 147                         bool checkHeader = true
 148                 ) const
 149         {
 150                 return BlockStructureOk(block, "reconstructed hits", checkHeader);
 151         }
 152
 153         /// Checks the structure of a clusters data block.
 154         bool BlockStructureOk(
 155                         const AliHLTMUONClustersBlockReader& block,
 156                         bool checkHeader = true
 157                 ) const
 158         {
 159                 return BlockStructureOk(block, "clusters", checkHeader);
 160         }
 161
 162         /// Checks the structure of a ADC channels data block.
 163         bool BlockStructureOk(
 164                         const AliHLTMUONChannelsBlockReader& block,
 165                         bool checkHeader = true
 166                 ) const
 167         {
 168                 return BlockStructureOk(block, "channels", checkHeader);
 169         }
 170
 171         /// Checks the structure of a Manso tracks data block.
 172         bool BlockStructureOk(
 173                         const AliHLTMUONMansoTracksBlockReader& block,
 174                         bool checkHeader = true
 175                 ) const
 176         {
 177                 return BlockStructureOk(block, "Manso tracks", checkHeader);
 178         }
 179
 180         /// Checks the structure of a Manso track candidates data block.
 181         bool BlockStructureOk(
 182                         const AliHLTMUONMansoCandidatesBlockReader& block,
 183                         bool checkHeader = true
 184                 ) const
 185         {
 186                 return BlockStructureOk(block, "Manso track candidates", checkHeader);
 187         }
 188
 189         /// Checks the structure of a single track trigger decision data block.
 190         bool BlockStructureOk(
 191                         const AliHLTMUONSinglesDecisionBlockReader& block,
 192                         bool checkHeader = true
 193                 ) const
 194         {
 195                 return BlockStructureOk(block, "singles decision", checkHeader);
 196         }
 197
 198         /// Checks the structure of a track pairs trigger decision data block.
 199         bool BlockStructureOk(
 200                         const AliHLTMUONPairsDecisionBlockReader& block,
 201                         bool checkHeader = true
 202                 ) const
 203         {
 204                 return BlockStructureOk(block, "pairs decision", checkHeader);
 205         }
 206
 207         /**
 208          * Sets the CDB path and run number to read from.
 209          * \param cdbPath  The CDB path to use. If set to NULL and the path has
 210          *      not been set in the CDB manager then the default path
 211          *      "local://$ALICE_ROOT/OCDB" is used if the 'useDefault' flag is also true.
 212          * \param run  The run number to use. If set to -1 and the run number has
 213          *      not been set in the CDB manager then a value of zero is used if
 214          *      the 'useDefault' flag is also true.
 215          * \param useDefault  If set to true then a default CDB path and/or run number
 216          *      is used if they have not been set and 'cdbPath' == NULL or
 217          *      'run' == -1. (false by default).
 218          * \return Zero if the object could be loaded. Otherwise an error code,
 219          *      compatible with the HLT framework, is returned.
 220          */
 221         int SetCDBPathAndRunNo(
 222                         const char* cdbPath, Int_t run, bool useDefault = false
 223                 ) const;
 224
 225         /**
 226          * Fetches the DDL and detector element store objects for MUON mapping.
 227          * \return Zero if the objects could be loaded. Otherwise an error code,
 228          *      which is compatible with the HLT framework, is returned.
 229          * \note AliMpDDLStore::Instance() and AliMpDEStore::Instance() must be used
 230          *      to fetch the objects after this method returns a code equal to zero.
 231          */
 232         int FetchMappingStores() const;
 233
 234         /**
 235          * Fetches a TMap object from the CDB.
 236          * [in] \param pathToEntry  The relative path to the entry in the CDB to fetch.
 237          * [out] \param map  This will be filled with the TMap object found if
 238          *      a successful status code is returned. Otherwise it will be unchanged.
 239          * \return Zero if the object could be found. Otherwise an error code,
 240          *      which is compatible with the HLT framework, is returned.
 241          */
 242         int FetchTMapFromCDB(const char* pathToEntry, TMap*& map) const;
 243
 244         /**
 245          * Tries to find the string value associated with a certain parameter in a TMap.
 246          * [in] \param map  The TMap object to search in.
 247          * [in] \param paramName  The name of the parameter to search for.
 248          * [out] \param value  Will be filled with the object found.
 249          * [in] \param prettyName  Should be the name of the parameter which will
 250          *      be used when printing error messages. If this is set to NULL then
 251          *      the paramName will be used instead (default is NULL).
 252          * \return Zero if the object could be found. Otherwise an error code,
 253          *      which is compatible with the HLT framework, is returned.
 254          */
 255         int GetValueFromTMap(
 256                         TMap* map, const char* paramName, TString& value,
 257                         const char* pathToEntry = NULL, const char* prettyName = NULL
 258                 ) const;
 259
 260         /**
 261          * Tries to find a certain parameter in the TMap object and convert it to
 262          * an integer value.
 263          * [in] \param map  The TMap object to search in.
 264          * [in] \param paramName  The name of the parameter to search for.
 265          * [out] \param value  Will be filled with the integer value for the parameter,
 266          *       if it was found and it was an integer value.
 267          * [in] \param prettyName  Should be the name of the parameter which will
 268          *      be used when printing error messages. If this is set to NULL then
 269          *      the paramName will be used instead (default is NULL).
 270          * \return Zero if the object could be found and is valid. Otherwise an
 271          *       error code, which is compatible with the HLT framework, is returned.
 272          */
 273         int GetIntFromTMap(
 274                         TMap* map, const char* paramName, Int_t& value,
 275                         const char* pathToEntry = NULL, const char* prettyName = NULL
 276                 ) const;
 277
 278         /**
 279          * Tries to find a certain parameter in the TMap object and convert it to
 280          * a positive integer value.
 281          * [in] \param map  The TMap object to search in.
 282          * [in] \param paramName  The name of the parameter to search for.
 283          * [out] \param value  Will be filled with the integer value for the parameter,
 284          *       if it was found and it was a positive integer value.
 285          * [in] \param prettyName  Should be the name of the parameter which will
 286          *      be used when printing error messages. If this is set to NULL then
 287          *      the paramName will be used instead (default is NULL).
 288          * \return Zero if the object could be found and is valid. Otherwise an
 289          *       error code, which is compatible with the HLT framework, is returned.
 290          */
 291         int GetPositiveIntFromTMap(
 292                         TMap* map, const char* paramName, Int_t& value,
 293                         const char* pathToEntry = NULL, const char* prettyName = NULL
 294                 ) const;
 295
 296         /**
 297          * Tries to find a certain parameter in the TMap object and convert it to
 298          * an floating point value.
 299          * [in] \param map  The TMap object to search in.
 300          * [in] \param paramName  The name of the parameter to search for.
 301          * [out] \param value  Will be filled with the floating point value for the
 302          *       parameter, if it was found and it was a floating point value.
 303          * [in] \param prettyName  Should be the name of the parameter which will
 304          *      be used when printing error messages. If this is set to NULL then
 305          *      the paramName will be used instead (default is NULL).
 306          * \return Zero if the object could be found and is valid. Otherwise an
 307          *       error code, which is compatible with the HLT framework, is returned.
 308          */
 309         int GetFloatFromTMap(
 310                         TMap* map, const char* paramName, Double_t& value,
 311                         const char* pathToEntry = NULL, const char* prettyName = NULL
 312                 ) const;
 313
 314         /**
 315          * Tries to find a certain parameter in the TMap object and convert it to
 316          * an positive floating point value.
 317          * [in] \param map  The TMap object to search in.
 318          * [in] \param paramName  The name of the parameter to search for.
 319          * [out] \param value  Will be filled with the floating point value for the
 320          *       parameter, if it was found and it was a positive floating point value.
 321          * [in] \param prettyName  Should be the name of the parameter which will
 322          *      be used when printing error messages. If this is set to NULL then
 323          *      the paramName will be used instead (default is NULL).
 324          * \return Zero if the object could be found and is valid. Otherwise an
 325          *       error code, which is compatible with the HLT framework, is returned.
 326          */
 327         int GetPositiveFloatFromTMap(
 328                         TMap* map, const char* paramName, Double_t& value,
 329                         const char* pathToEntry = NULL, const char* prettyName = NULL
 330                 ) const;
 331
 332         /**
 333          * Fetches the reconstruction parameters object from the CDB for MUON.
 334          * [out] \param params  This will be filled with the reconstruction
 335          *      parameters object found if a successful status code is returned.
 336          *      Otherwise it will be unchanged.
 337          * \return Zero if the object could be found. Otherwise an error code,
 338          *      which is compatible with the HLT framework, is returned.
 339          */
 340         int LoadRecoParamsFromCDB(AliMUONRecoParam*& params) const;
 341
 342         /**
 343          * Dumps the data contained in a buffer to file as is.
 344          */
 345         void DumpBuffer(
 346                         const void* buffer, AliHLTUInt32_t size,
 347                         const char* filename
 348                 ) const;
 349
 350         /**
 351          * Dumps the data block to file.
 352          */
 353         void DumpBlock(
 354                         const AliHLTComponentBlockData* block,
 355                         const char* fileNamePrefix
 356                 ) const;
 357
 358         /**
 359          * Dumps the event information to files in the dump path given by the
 360          * method DumpPath, which can be set by the command line argument -dumppath.
 361          */
 362         void DumpEvent(
 363                         const AliHLTComponentEventData& evtData,
 364                         const AliHLTComponentBlockData* blocks,
 365                         AliHLTComponentTriggerData& trigData,
 366                         AliHLTUInt8_t* outputPtr,
 367                         AliHLTUInt32_t& size,
 368                         AliHLTComponentBlockDataList& outputBlocks
 369                 ) const;
 370
 371         /**
 372          * Dumps the event information to files in the dump path given by the
 373          * method DumpPath, which can be set by the command line argument -dumppath.
 374          */
 375         void DumpEvent(
 376                         const AliHLTComponentEventData& evtData,
 377                         AliHLTComponentTriggerData& trigData
 378                 ) const;
 379
 380 private:
 381
 382         // Do not allow copying of this class.
 383         /// Not implemented.
 384         AliHLTMUONProcessor(const AliHLTMUONProcessor& /*obj*/);
 385         /// Not implemented.
 386         AliHLTMUONProcessor& operator = (const AliHLTMUONProcessor& /*obj*/);
 387
 388         bool fWarnForUnexpecedBlock;  ///< Flag indicating if we should log a warning if we got a block of an unexpected type.
 389         bool fDelaySetup;  ///< Indicates if the component should delay loading and initialising from the CDB to the start of run event.
 390         bool fDumpDataOnError; ///< Flag indicating if we should dump data when an error occurs in the reconstruction class.
 391         const char* fDumpPath; ///< This is the path prefix to use to dump event data too when an error occurs.
 392
 393         ClassDef(AliHLTMUONProcessor, 0)  // Abstract base class for dHLT specific components.
 394 };
 395
 396 //______________________________________________________________________________
 397
 398 template <class BlockType>
 399 bool AliHLTMUONProcessor::BlockStructureOk(
 400                 const BlockType& block, const char* name, bool checkHeader
 401         ) const
 402 {
 403         /// Performs basic checks to see if the input data block structure is OK,
 404         /// that it is not corrupt, too short etc...
 405
 406         if (not block.BufferSizeOk())
 407         {
 408                 size_t headerSize = sizeof(typename BlockType::HeaderType);
 409                 if (block.BufferSize() < headerSize)
 410                 {
 411                         HLTError("Received a %s data block with a size of %d bytes,"
 412                                 " which is smaller than the minimum valid header size of %d bytes."
 413                                 " The block must be corrupt.",
 414                                 name, block.BufferSize(), headerSize
 415                         );
 416                         return false;
 417                 }
 418
 419                 size_t expectedWidth = sizeof(typename BlockType::ElementType);
 420                 if (block.CommonBlockHeader().fRecordWidth != expectedWidth)
 421                 {
 422                         HLTError("Received a %s data block with a record"
 423                                 " width of %d bytes, but the expected value is %d bytes."
 424                                 " The block might be corrupt.",
 425                                 name,
 426                                 block.CommonBlockHeader().fRecordWidth,
 427                                 expectedWidth
 428                         );
 429                         return false;
 430                 }
 431
 432                 HLTError("Received a %s data block with a size of %d bytes,"
 433                         " but the block header claims the block should be %d bytes."
 434                         " The block might be corrupt.",
 435                         name, block.BufferSize(), block.BytesUsed()
 436                 );
 437                 return false;
 438         }
 439
 440         if (checkHeader)
 441         {
 442                 AliHLTMUONUtils::WhyNotValid reason;
 443                 if (not AliHLTMUONUtils::HeaderOk(block.BlockHeader(), &reason))
 444                 {
 445                         HLTError("Received a %s data block which might be corrupt. %s",
 446                                 name, AliHLTMUONUtils::FailureReasonToMessage(reason)
 447                         );
 448                         return false;
 449                 }
 450         }
 451
 452         return true;
 453 }
 454
 455 #endif // ALIHLTMUONPROCESSOR_H