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