HLT/BASE/AliHLTSystem.h

   1 //-*- Mode: C++ -*-
   2 // @(#) $Id$
   3
   4 #ifndef ALIHLTSYSTEM_H
   5 #define ALIHLTSYSTEM_H
   6 //* This file is property of and copyright by the ALICE HLT Project        *
   7 //* ALICE Experiment at CERN, All rights reserved.                         *
   8 //* See cxx source for full Copyright notice                               *
   9
  10 /** @file   AliHLTSystem.h
  11     @author Matthias Richter
  12     @date
  13     @brief  Global HLT module management and AliRoot integration.
  14     @note   The class is used in Offline (AliRoot) context
  15 */
  16
  17 /**
  18  * @defgroup alihlt_system HLT integration into AliRoot
  19  * This section describes the HLT integration into AliRoot.
  20  */
  21
  22 #include "AliHLTLogging.h"
  23 #include <TList.h>
  24 #include <TString.h>
  25
  26 class AliHLTComponentHandler;
  27 class AliHLTConfiguration;
  28 class AliHLTConfigurationHandler;
  29 class AliHLTTask;
  30 class AliHLTOUT;
  31 class AliRunLoader;
  32 class AliRawReader;
  33 class AliESDEvent;
  34 class TObjArray;
  35 class TStopwatch;
  36
  37 /**
  38  * @class AliHLTSystem
  39  * Main class for the HLT integration into AliRoot.
  40  * The class handles a list of configurations. Configurations are translated
  41  * into task lists which can be executed.
  42  *
  43  * @note This class is only used for the @ref alihlt_system.
  44  *
  45  * @ingroup alihlt_system
  46  */
  47 class AliHLTSystem : public AliHLTLogging {
  48  public:
  49   /** default constructor */
  50   AliHLTSystem(AliHLTComponentLogSeverity loglevel=kHLTLogDefault);
  51   /** destructor */
  52   virtual ~AliHLTSystem();
  53
  54   /**
  55    * Pointer to an instance of @ref AliHLTComponentHandler.
  56    */
  57   AliHLTComponentHandler* fpComponentHandler;                      //! transient
  58
  59   /**
  60    * Pointer to an instance of @ref AliHLTConfigurationHandler.
  61    */
  62   AliHLTConfigurationHandler* fpConfigurationHandler;              //! transient
  63
  64   /**
  65    * Add a configuration to the end of the list.
  66    * @param pConf    pointer to configuration to add
  67    */
  68   int AddConfiguration(AliHLTConfiguration* pConf);
  69
  70   /**
  71    * Insert a configuration to the end of the list after the specified
  72    * configuration.
  73    * @param pConf    pointer to configuration to insert
  74    * @param pPrec    pointer to configuration to insert the new one after
  75    */
  76   int InsertConfiguration(AliHLTConfiguration* pConf, AliHLTConfiguration* pPrec);
  77
  78   /**
  79    * Remove a configuration from the list.
  80    * @param pConf    pointer to configuration to delete
  81    */
  82   int DeleteConfiguration(AliHLTConfiguration* pConf);
  83
  84   /**
  85    * Build a task list
  86    * This method is used to build the tasks from the 'master' configuration
  87    * objects which are added to the HLT system handler. This is an iterative
  88    * process since the task might depend upon other configurations. For each
  89    * configuration object which has not yet been converted into a task, the
  90    * method will be called iteratively. Finally, after building all tasks which
  91    * the current one depends on have been created, the task is inserted to the
  92    * list of tasks with the InsertTask method.
  93    * @param pConf    configuration name/id
  94    */
  95   int BuildTaskList(const char* pConf);
  96
  97   /**
  98    * Build task list from a configuration object.
  99    * This method is kept for backward compatibility. Use the version
 100    * with the configuration name.
 101    * @param pConf    pointer to configuration to build the task list from
 102    */
 103   int BuildTaskList(AliHLTConfiguration* pConf);
 104
 105   /**
 106    * Clean the list of tasks and delete all the task objects.
 107    */
 108   int CleanTaskList();
 109
 110   /**
 111    * Insert a task to the task list.
 112    * The method first checks whether all dependencies are resolved (i.e. exist
 113    * already in the task list). During this iteration the cross links between
 114    * the tasks are set as well. If all dependencies are resolved, the task is
 115    * added at the end of the list.
 116    * @param pTask    pointer to task to add
 117    */
 118   int InsertTask(AliHLTTask* pTask);
 119
 120   /**
 121    * Find a task with an id.
 122    * @param id       CONFIGURATION id (not a COMPONENT id!)
 123    */
 124   AliHLTTask* FindTask(const char* id);
 125
 126   /**
 127    * Print the task list.
 128    */
 129   void PrintTaskList();
 130
 131   /**
 132    * Run the task list.
 133    * The method checks whether the task list has already been build. If not,
 134    * or the configuration list has been changed, the @ref BuildTaskList
 135    * method is called.                                                    <br>
 136    * All tasks of the list will be subsequently processed for each event.
 137    * The system can remain started if the \em bStop parameter is 0. In that
 138    * case the system just waits for the next event. A specific call with
 139    * nofEvents==0 is needed to execute the stop sequence.
 140    * @param iNofEvents number of events
 141    * @param bStop      stop the chain after processing
 142    * @return number of reconstructed events, neg error code if failed
 143    */
 144   int Run(Int_t iNofEvents=1, int bStop=1);
 145
 146   /**
 147    * Init all tasks from the list.
 148    * The @ref AliHLTTask::Init method is called for each task, the components
 149    * will be created.
 150    * @return neg error code if failed
 151    */
 152   int InitTasks();
 153
 154   /**
 155    * Init the stopwatches for all tasks.
 156    * @param pStopwatches    object array of stopwatches, for types
 157    *                        @see AliHLTComponent::AliHLTStopwatchType
 158    * @return neg error code if failed
 159    */
 160   int InitBenchmarking(TObjArray* pStopwatches);
 161
 162   /**
 163    * Stop the stopwatches for all tasks.
 164    * @param pStopwatches    object array of stopwatches, for types
 165    *                        @see AliHLTComponent::AliHLTStopwatchType
 166    * @return neg error code if failed
 167    */
 168   int PauseBenchmarking(TObjArray* pStopwatches) const;
 169
 170   /**
 171    * Continue the stopwatches for all tasks.
 172    * @param pStopwatches    object array of stopwatches, for types
 173    *                        @see AliHLTComponent::AliHLTStopwatchType
 174    * @return neg error code if failed
 175    */
 176   int ResumeBenchmarking(TObjArray* pStopwatches) const;
 177
 178   /**
 179    * Print benchmarking summary.
 180    * Optionak: clean up stop watches.
 181    * @param pStopwatches    object array of stopwatches
 182    * @param bClean          delete stop watches if 1
 183    * @return neg error code if failed
 184    */
 185   int PrintBenchmarking(TObjArray* pStopwatches, int bClean=0) const;
 186
 187   /**
 188    * Start task list.
 189    * The @ref AliHLTTask::StartRun method is called for each task, the
 190    * components will be prepared for event processing.
 191    * @return neg error code if failed
 192    */
 193   int StartTasks();
 194
 195   /**
 196    * Process task list.
 197    * The @ref AliHLTTask::ProcessTask method is called for each task.
 198    * @return neg error code if failed
 199    */
 200   int ProcessTasks(Int_t eventNo);
 201
 202   /**
 203    * Stop task list.
 204    * The @ref AliHLTTask::EndRun method is called for each task, the components
 205    * will be cleaned after event processing.
 206    * @return neg error code if failed
 207    */
 208   int StopTasks();
 209
 210   /**
 211    * Send a control event trough the chain.
 212    * All data sources in the chain are switched to publish a control event like
 213    * SOR or EOR. The event is propagated in the same way as a normal event.
 214    * @param dt       type of the event
 215    */
 216   int SendControlEvent(AliHLTComponentDataType dt);
 217
 218   /**
 219    * De-init all tasks from the list.
 220    * The @ref AliHLTTask::Deinit method is called for each task, the components
 221    * will be deleted.
 222    * @return neg error code if failed
 223    */
 224   int DeinitTasks();
 225
 226   /**
 227    * The memory allocation function for components.
 228    * This function is part of the running environment of the components.
 229    */
 230   static void* AllocMemory( void* param, unsigned long size );
 231
 232   /**
 233    * AliRoot embedded reconstruction.
 234    * Main entry point to execute the HLT reconstruction from AliRoot. Called
 235    * either by the AliHLTReconstructor plugin during AliRoot reconstruction
 236    * of raw data, or AliHLTSimulation during simulation of data.
 237    *
 238    * The two cases are distinguished by the availablility of the run loader
 239    * and raw reader.
 240    * - AliRoot simulation: run loader is available and is propagated to the
 241    *   module agents (AliHLTModuleAgent) to generate the corresponding
 242    *   configurations and chains, and to the AliHLTOfflineSource components.
 243    * - AliRoot reconstruction: raw reader is available and is propagated to
 244    *   the agents and AliHLTOfflineSource components.
 245    *
 246    * The system remains started after the processing and just waits for the
 247    * next event. A specific call with nofEvents==0 is needed to execute the
 248    * stop sequence.
 249    *
 250    * The 'runLoader' and 'rawReader' parameters are set to all active
 251    * AliHLTOfflineDataSource's and the HLT chain is processed for the given
 252    * number of events. If the rawReader is NULL, reconstruction is done on
 253    * simulated data, from real data if a RawReader is specified.
 254    * @param nofEvents     number of events
 255    * @param runLoader     the AliRoot runloader
 256    * @param rawReader     the AliRoot RawReader
 257    * @return number of reconstructed events, neg. error code if failed
 258    */
 259   int Reconstruct(int nofEvents, AliRunLoader* runLoader,
 260                   AliRawReader* rawReader=NULL);
 261
 262   /**
 263    * Fill ESD for one event.
 264    * To be called by the AliHLTReconstructor plugin during the event loop
 265    * and FillESD method of the AliRoot reconstruction.
 266    *
 267    * The method is most likely deprecated as the scheme has been slightly
 268    * changed. The ESD is filled by the HLTOUT handlers u=implemented by the
 269    * HLT modules rather than by components within the reconstruction chain.
 270    * Still, HLT reconstruction chains can be run during the AliRoot
 271    * reconstruction, data produced by such chains is automatically added
 272    * to the HLTOUT stream in order to be equivalent to the online HLT.
 273    * The HLTOUT is processed during AliReconstruction at the end of the
 274    * HLT event processing, literally during the FillESD method of the AliRoot
 275    * reconstruction interface. The HLT module must implement HLTOUT handlers
 276    * and provide those through the module agent.
 277    *
 278    * This method is called on event basis, and thus must copy the previously
 279    * reconstructed data of the event from the 'ESD' recorder. The FillESD
 280    * method of all active AliHLTOfflineDataSink's is called.
 281    * @param eventNo       current event no (Note: this event number is just a
 282    *                      processing counter and is not related to the nature/
 283    *                      origin of the event
 284    * @param runLoader     the AliRoot runloader
 285    * @param esd           an AliESDEvent instance
 286    * @return neg. error code if failed
 287    */
 288   int FillESD(int eventNo, AliRunLoader* runLoader, AliESDEvent* esd);
 289
 290   /**
 291    * Process the HLTOUT data.
 292    */
 293   int ProcessHLTOUT(AliHLTOUT* pHLTOUT, AliESDEvent* esd);
 294
 295   /**
 296    * Process all kChain-type data blocks of the HLTOUT data.
 297    * The function is involed from ProcessHLTOUT as the first step in
 298    * the processing.
 299    */
 300   int ProcessHLTOUTkChain(AliHLTOUT* pHLTOUT);
 301
 302   /**
 303    * Load component libraries.
 304    * @param libs          string of blank separated library names
 305    * @return neg. error code if failed
 306    */
 307   int LoadComponentLibraries(const char* libs);
 308
 309   /**
 310    * Find a symbol in a dynamically loaded library.
 311    * @param library      library
 312    * @param symbol       the symbol to find
 313    * @return void pointer to function
 314    */
 315   void* FindDynamicSymbol(const char* library, const char* symbol);
 316
 317   /**
 318    * Prepare the HLT system for running.
 319    * - module agents are requested to register configurations
 320    * - task lists are built from the top configurations of the modules
 321    *
 322    * @param rawReader    instance of the raw reader or NULL
 323    * @param runloader    optional instance of the run loader
 324    * @return neg. error code if failed <br>
 325    *         -EBUSY      system is in kRunning state <br>
 326    */
 327   int Configure(AliRawReader* rawReader, AliRunLoader* runloader=NULL);
 328
 329   /**
 330    * Old method kept for backward compatibilty.
 331    *
 332    * @param runloader    optional instance of the run loader
 333    * @return neg. error code if failed <br>
 334    *         -EBUSY      system is in kRunning state <br>
 335    */
 336   int Configure(AliRunLoader* runloader=NULL);
 337
 338   /**
 339    * Scan options.
 340    * Known options
 341    * <!-- NOTE: ignore the \li. <i> and </i>: it's just doxygen formatting -->
 342    * \li loglevel=<i>level</i> <br>
 343    *     logging level for this processing
 344    * \li frameworklog=<i>level</i> <br>
 345    *     logging level for framework classes
 346    * \li alilog=off
 347    *     disable redirection of log messages to AliLog class
 348    * \li config=<i>macro</i>
 349    *     configuration macro
 350    * \li chains=<i>configuration</i>
 351    *     comma separated list of configurations to be run during local
 352    *     reconstruction
 353    * \li libmode=<i>static,dynamic(default)</i>
 354    *     libraries are persistent if loaded in mode <i>static</i>, i.e. they
 355    *     can't be unloaded
 356    */
 357   int ScanOptions(const char* options);
 358
 359   /**
 360    * Reset the HLT system.
 361    * Reset is not possible while the system is in running state.
 362    * @param bForce       force the reset
 363    * @return neg. error code if failed <br>
 364    *         -EBUSY      system is in kRunning state <br>
 365    */
 366   int Reset(int bForce=0);
 367
 368   /**
 369    * Load the configurations specified by the module agents.
 370    * The runLoader is passed to the agent and allows configuration
 371    * selection.
 372    * @param rawReader    instance of the raw reader or NULL
 373    * @param runloader    optional instance of the run loader
 374    * @return neg. error code if failed
 375    */
 376   int LoadConfigurations(AliRawReader* rawReader, AliRunLoader* runloader=NULL);
 377
 378   /**
 379    * Get the top configurations of all agents and build the task lists.
 380    * @param rawReader    instance of the raw reader or NULL
 381    * @param runloader    optional instance of the run loader
 382    * @return neg. error code if failed
 383    */
 384   int BuildTaskListsFromReconstructionChains(AliRawReader* rawReader,
 385                                              AliRunLoader* runloader=NULL);
 386
 387   enum AliHLTSystemState {
 388     kUninitialized       = 0x0,
 389     kLibrariesLoaded     = 0x1,
 390     kConfigurationLoaded = 0x2,
 391     kTaskListCreated     = 0x4,
 392     kReady               = 0x7,
 393     kStarted             = 0x8,
 394     kRunning             = 0x10,
 395     kError               = 0x1000
 396   };
 397
 398   /**
 399    * Check status of the system.
 400    * @param flag          AliHLTSystemState value to check for
 401    * @return 1 if set, 0 if not
 402    */
 403   int CheckStatus(int flag);
 404
 405   /**
 406    * Get the current status.
 407    * @return status flags of @ref AliHLTSystemState
 408    */
 409   int GetStatusFlags();
 410
 411   /**
 412    * Set logging level for framework classes.
 413    * This sets the local logging level of this instance and all subsequent
 414    * framework classes to \em level.
 415    * @param level     local logging level for the framework classes
 416    */
 417   void SetFrameworkLog(AliHLTComponentLogSeverity level);
 418
 419  protected:
 420
 421  private:
 422   /** copy constructor prohibited */
 423   AliHLTSystem(const AliHLTSystem&);
 424   /** assignment operator prohibited */
 425   AliHLTSystem& operator=(const AliHLTSystem&);
 426
 427   /**
 428    * Set status flags.
 429    */
 430   int SetStatusFlags(int flags);
 431
 432   /**
 433    * clear status flags.
 434    */
 435   int ClearStatusFlags(int flags);
 436
 437 /*   TList fConfList; */
 438 /*   int fbListChanged; */
 439
 440   /** list of tasks */
 441   TList fTaskList;                                                 // see above
 442
 443   /** the number of instances of AliHLTSystem */
 444   static int fgNofInstances;                                       // see above
 445
 446   /** state of the object */
 447   int fState;                                                      // see above
 448
 449   /** chains to be run during reconstruction */
 450   TString fChains;                                                 //!transient
 451
 452   /** array of stopwatches */
 453   TObjArray* fStopwatches;                                         //!transient
 454
 455   /** number of events processed in total */
 456   int fEventCount;                                                 //!transient
 457
 458   /** number of events processed successfully */
 459   int fGoodEvents;                                                 //!transient
 460
 461   /** array of default libraries */
 462   static const char* fgkHLTDefaultLibs[];                          //!transient
 463
 464   ClassDef(AliHLTSystem, 7);
 465 };
 466
 467 #endif