HLT/BASE/AliHLTSystem.h

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