Enhanced doxygen documentation
[u/mrichter/AliRoot.git] / 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=1, int bStop=1);
212
213   /**
214    * Init all tasks from the list.
215    * The @ref AliHLTTask::Init method is called for each task, the components
216    * will be created.
217    * @return neg error code if failed
218    */
219   int InitTasks();
220
221   /**
222    * Init the stopwatches for all tasks.
223    * @param pStopwatches    object array of stopwatches, for types
224    *                        @see AliHLTComponent::AliHLTStopwatchType
225    * @return neg error code if failed
226    */
227   int InitBenchmarking(TObjArray* pStopwatches);
228
229   /**
230    * Stop 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 PauseBenchmarking(TObjArray* pStopwatches) const;
236
237   /**
238    * Continue 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 ResumeBenchmarking(TObjArray* pStopwatches) const;
244
245   /**
246    * Print benchmarking summary.
247    * Optionak: clean up stop watches.
248    * @param pStopwatches    object array of stopwatches
249    * @param bClean          delete stop watches if 1
250    * @return neg error code if failed
251    */
252   int PrintBenchmarking(TObjArray* pStopwatches, int bClean=0) const;
253
254   /**
255    * Start task list.
256    * The @ref AliHLTTask::StartRun method is called for each task, the
257    * components will be prepared for event processing.
258    * @return neg error code if failed
259    */
260   int StartTasks();
261
262   /**
263    * Process task list.
264    * The @ref AliHLTTask::ProcessTask method is called for each task.
265    * @return neg error code if failed
266    */
267   int ProcessTasks(Int_t eventNo);
268
269   /**
270    * Stop task list.
271    * The @ref AliHLTTask::EndRun method is called for each task, the components
272    * will be cleaned after event processing.
273    * @return neg error code if failed
274    */
275   int StopTasks();
276
277   /**
278    * Send a control event trough the chain.
279    * All data sources in the chain are switched to publish a control event like
280    * SOR or EOR. The event is propagated in the same way as a normal event.
281    * @param dt       type of the event
282    */
283   int SendControlEvent(AliHLTComponentDataType dt);
284
285   /**
286    * De-init all tasks from the list.
287    * The @ref AliHLTTask::Deinit method is called for each task, the components
288    * will be deleted.
289    * @return neg error code if failed
290    */
291   int DeinitTasks();
292
293   /**
294    * Cleanup all internal objects from HLTOUT processing.
295    */
296   int CleanHLTOUT();
297
298   /**
299    * The memory allocation function for components.
300    * This function is part of the running environment of the components.
301    */
302   static void* AllocMemory( void* param, unsigned long size );
303
304   /**
305    * AliRoot embedded reconstruction.
306    * Main entry point to execute the HLT reconstruction from AliRoot. Called
307    * either by the AliHLTReconstructor plugin during AliRoot reconstruction
308    * of raw data, or AliHLTSimulation during simulation of data.
309    *
310    * The two cases are distinguished by the availablility of the run loader
311    * and raw reader.
312    * - AliRoot simulation: run loader is available and is propagated to the
313    *   module agents (AliHLTModuleAgent) to generate the corresponding
314    *   configurations and chains, and to the AliHLTOfflineSource components.
315    * - AliRoot reconstruction: raw reader is available and is propagated to
316    *   the agents and AliHLTOfflineSource components.
317    *
318    * The system remains started after the processing and just waits for the
319    * next event. A specific call with nofEvents==0 is needed to execute the
320    * stop sequence.
321    *
322    * The 'runLoader' and 'rawReader' parameters are set to all active
323    * AliHLTOfflineDataSource's and the HLT chain is processed for the given
324    * number of events. If the rawReader is NULL, reconstruction is done on
325    * simulated data, from real data if a RawReader is specified.
326    * @param nofEvents     number of events
327    * @param runLoader     the AliRoot runloader
328    * @param rawReader     the AliRoot RawReader
329    * @return number of reconstructed events, neg. error code if failed 
330    */
331   int Reconstruct(int nofEvents, AliRunLoader* runLoader, 
332                   AliRawReader* rawReader=NULL);
333
334   /**
335    * Fill ESD for one event.
336    * To be called by the AliHLTReconstructor plugin during the event loop
337    * and FillESD method of the AliRoot reconstruction.
338    *
339    * The method is most likely deprecated as the scheme has been slightly
340    * changed. The ESD is filled by the HLTOUT handlers u=implemented by the
341    * HLT modules rather than by components within the reconstruction chain.
342    * Still, HLT reconstruction chains can be run during the AliRoot
343    * reconstruction, data produced by such chains is automatically added
344    * to the HLTOUT stream in order to be equivalent to the online HLT.
345    * The HLTOUT is processed during AliReconstruction at the end of the
346    * HLT event processing, literally during the FillESD method of the AliRoot
347    * reconstruction interface. The HLT module must implement HLTOUT handlers
348    * and provide those through the module agent.
349    *
350    * This method is called on event basis, and thus must copy the previously
351    * reconstructed data of the event from the 'ESD' recorder. The FillESD
352    * method of all active AliHLTOfflineDataSink's is called.
353    * @param eventNo       current event no (Note: this event number is just a
354    *                      processing counter and is not related to the nature/
355    *                      origin of the event
356    * @param runLoader     the AliRoot runloader
357    * @param esd           an AliESDEvent instance
358    * @return neg. error code if failed 
359    */
360   int FillESD(int eventNo, AliRunLoader* runLoader, AliESDEvent* esd);
361
362   /**
363    * Process the HLTOUT data.
364    */
365   int ProcessHLTOUT(AliHLTOUT* pHLTOUT, AliESDEvent* esd);
366
367   /**
368    * Process all kChain-type data blocks of the HLTOUT data.
369    * The function is involed from ProcessHLTOUT as the first step in
370    * the processing.
371    */
372   int ProcessHLTOUTkChain(AliHLTOUT* pHLTOUT);
373
374   /**
375    * Load component libraries.
376    * @param libs          string of blank separated library names
377    * @return neg. error code if failed 
378    */
379   int LoadComponentLibraries(const char* libs);
380
381   /**
382    * Find a symbol in a dynamically loaded library.
383    * @param library      library
384    * @param symbol       the symbol to find
385    * @return void pointer to function
386    */
387   void* FindDynamicSymbol(const char* library, const char* symbol);
388
389   /**
390    * Prepare the HLT system for running.
391    * - module agents are requested to register configurations
392    * - task lists are built from the top configurations of the modules
393    *
394    * @param rawReader    instance of the raw reader or NULL
395    * @param runloader    optional instance of the run loader
396    * @return neg. error code if failed <br>
397    *         -EBUSY      system is in kRunning state <br>
398    */
399   int Configure(AliRawReader* rawReader, AliRunLoader* runloader=NULL);
400
401   /**
402    * Old method kept for backward compatibilty.
403    *
404    * @param runloader    optional instance of the run loader
405    * @return neg. error code if failed <br>
406    *         -EBUSY      system is in kRunning state <br>
407    */
408   int Configure(AliRunLoader* runloader=NULL);
409
410   /**
411    * Scan options and load component libraries.
412    * The options consist of blank separated tokens. Libraries can be just
413    * specified by their name. Further options
414    * <!-- NOTE: ignore the \li. <i> and </i>: it's just doxygen formatting -->
415    * \li loglevel=<i>level</i> <br>
416    *     logging level for this processing
417    * \li frameworklog=<i>level</i> <br>
418    *     logging level for framework classes
419    * \li alilog=off
420    *     disable redirection of log messages to AliLog class
421    * \li config=<i>macro</i>
422    *     configuration macro
423    * \li chains=<i>configuration</i>
424    *     comma separated list of configurations to be run during local
425    *     reconstruction
426    * \li libmode=<i>static,dynamic(default)</i>
427    *     libraries are persistent if loaded in mode <i>static</i>, i.e. they
428    *     can't be unloaded
429    */
430   int ScanOptions(const char* options);
431
432   /**
433    * Reset the HLT system.
434    * Reset is not possible while the system is in running state.
435    * @param bForce       force the reset
436    * @return neg. error code if failed <br>
437    *         -EBUSY      system is in kRunning state <br>
438    */
439   int Reset(int bForce=0);
440
441   /**
442    * Load the configurations specified by the module agents.
443    * The runLoader is passed to the agent and allows configuration
444    * selection.
445    * @param rawReader    instance of the raw reader or NULL
446    * @param runloader    optional instance of the run loader
447    * @return neg. error code if failed 
448    */
449   int LoadConfigurations(AliRawReader* rawReader, AliRunLoader* runloader=NULL);
450
451   /**
452    * Get the top configurations of all agents and build the task lists.
453    * @param rawReader    instance of the raw reader or NULL
454    * @param runloader    optional instance of the run loader
455    * @return neg. error code if failed 
456    */
457   int BuildTaskListsFromReconstructionChains(AliRawReader* rawReader, 
458                                              AliRunLoader* runloader=NULL);
459
460   enum AliHLTSystemState {
461     kUninitialized       = 0x0,
462     kLibrariesLoaded     = 0x1,
463     kConfigurationLoaded = 0x2,
464     kTaskListCreated     = 0x4,
465     kReady               = 0x7,
466     kStarted             = 0x8,
467     kRunning             = 0x10,
468     kError               = 0x1000
469   };
470
471   /**
472    * Check status of the system.
473    * @param flag          AliHLTSystemState value to check for
474    * @return 1 if set, 0 if not
475    */
476   int CheckStatus(int flag);
477
478   /**
479    * Get the current status.
480    * @return status flags of @ref AliHLTSystemState
481    */
482   int GetStatusFlags();
483
484   /**
485    * Set logging level for framework classes.
486    * This sets the local logging level of this instance and all subsequent
487    * framework classes to \em level.
488    * @param level     local logging level for the framework classes
489    */
490   void SetFrameworkLog(AliHLTComponentLogSeverity level);
491
492  protected:
493  
494  private:
495   /** copy constructor prohibited */
496   AliHLTSystem(const AliHLTSystem&);
497   /** assignment operator prohibited */
498   AliHLTSystem& operator=(const AliHLTSystem&);
499
500   /**
501    * Set status flags.
502    */
503   int SetStatusFlags(int flags);
504
505   /**
506    * clear status flags.
507    */
508   int ClearStatusFlags(int flags);
509
510 /*   TList fConfList; */
511 /*   int fbListChanged; */
512
513   /** list of tasks */
514   TList fTaskList;                                                 // see above
515
516   /** the number of instances of AliHLTSystem */
517   static int fgNofInstances;                                       // see above
518
519   /** state of the object */
520   int fState;                                                      // see above
521
522   /** chains to be run during reconstruction */
523   TString fChains;                                                 //!transient
524
525   /** array of stopwatches */
526   TObjArray* fStopwatches;                                         //!transient
527
528   /** number of events processed in total */                        
529   int fEventCount;                                                 //!transient
530
531   /** number of events processed successfully */
532   int fGoodEvents;                                                 //!transient
533
534   /** array of default libraries */
535   static const char* fgkHLTDefaultLibs[];                          //!transient
536
537   /** active kChain handlers (AliHLTOUT::AliHLTOUTHandlerListEntryVector*) */
538   void* fpChainHandlers;                                           //!transient
539
540   /** active kEsd handlers (AliHLTOUT::AliHLTOUTHandlerListEntryVector*) */
541   void* fpEsdHandlers;                                             //!transient
542
543   /** active kProprietary handlers (AliHLTOUT::AliHLTOUTHandlerListEntryVector*) */
544   void* fpProprietaryHandlers;                                     //!transient
545
546   /** active HLTOUT task for the reconstruction */
547   AliHLTOUTTask* fpHLTOUTTask;                                     //!transient
548
549   /** special task to publish the control events */
550   AliHLTControlTask* fpControlTask;                                //!transient
551
552   /** name of this system instance */
553   TString fName;                                                   //!transient
554
555   ClassDef(AliHLTSystem, 12);
556 };
557
558 #endif