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