e4481510e570b365ebaed708cc2c16fa77d29daf
[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
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