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