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