]> git.uio.no Git - u/mrichter/AliRoot.git/blob - HLT/BASE/AliHLTSystem.h
coveritiy
[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   2007
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  * In either case an HLT chain described by means of AliHLTConfiguration
29  * builds the core of any HLT application. Special components exist, which 
30  * emulate the behavior 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  * @note This class is only used for the @ref alihlt_system.
97  *
98  * @section alihltsystem_overview Main functionality
99  * The class implements the main binding functionality to run HLT
100  * embedded in AliRoot:
101  * - creates handlers for HLT components (AliHLTComponentHandler)
102  * and configurations (AliHLTConfigurationHandler).
103  * - implements the creation of a task list from configurations
104  * - runs the tasks of the task list
105  * - implements the interface to AliHLTReconstructor and AliHLTSimulation
106  * - manages the registered module agents (AliHLTModuleAgent) 
107  *
108  * @section alihltsystem_functions Main functions
109  * The following list gives the most important functions, see documentation
110  * of functions for details.
111  * - ScanOptions(const char*) initialize the system from arguments
112  * - BuildTaskList(const char*) build task list for a reconstruction chain
113  * - Run() processing loop for task list
114  * - Reconstruct() interface to AliHLTReconstructor
115  * - ProcessHLTOUT() process an HLTOUT colection
116  *
117  * @section alihltsystem_initialization Initialization
118  * AliHLTSystem is initialized with a list of component libraries which determine
119  * the actual functionality. See ScanOptions() for description of options.
120  *
121  * @section alihltsystem_usage Usage
122  * The class AliHLTPluginBase handles the global instance of AliHLTSystem,
123  * the instance is created and fetched like 
124  * <pre>
125  * // setup the HLT system
126  * AliHLTSystem* pHLT=AliHLTPluginBase::GetInstance();
127  * </pre>
128  *
129  * @ingroup alihlt_system
130  */
131 class AliHLTSystem : public AliHLTLogging {
132  public:
133   /** default constructor */
134   AliHLTSystem(AliHLTComponentLogSeverity loglevel=kHLTLogDefault,
135                const char* name="",
136                AliHLTComponentHandler* pCompHandler=NULL,
137                AliHLTConfigurationHandler* pConfHandler=NULL
138                );
139   /** destructor */
140   virtual ~AliHLTSystem();
141
142   /**
143    * Build a task list 
144    * This method is used to build the list of tasks from the configuration
145    * id of a single 'master' configuration.
146    *
147    * Configuration entries might depend upon other configurations. For each
148    * configuration which has not yet been converted into an AliHLTTask, the
149    * method will be called iteratively. Finally, after building all tasks
150    * providing the input for the current one, the task is inserted to the
151    * list of tasks with the InsertTask() method.
152    *
153    * The function can be called multiple times in order to add more than one
154    * chain to the system.
155    *
156    * @param pConf    configuration name/id
157    */
158   int BuildTaskList(const char* pConf);
159
160   /**
161    * Clean the list of tasks and delete all the task objects.
162    */
163   int CleanTaskList();
164
165   /**
166    * Insert a task to the task list.
167    * The method first checks whether all dependencies are resolved (i.e. exist 
168    * already in the task list). During this iteration the cross links between
169    * the tasks are set as well. If all dependencies are resolved, the task is
170    * added at the end of the list.
171    * @param pTask    pointer to task to add
172    */
173   int InsertTask(AliHLTTask* pTask);
174
175   /**
176    * Add HLTOUT task to the end of the task list.
177    * If one of the specified chains has output, an AliHLTOUTTask is
178    * added which controls the output. All other chains are removed from the
179    * AliHLTOUTTask input.
180    * @return 0 if no task has been added, 1 if task has been added
181    */
182   int AddHLTOUTTask(const char* chains);
183
184   AliHLTOUTTask* GetHLTOUTTask() const {return fpHLTOUTTask;}
185   AliHLTComponentHandler* GetComponentHandler() const {return fpComponentHandler;}
186   AliHLTConfigurationHandler* GetConfigurationHandler() const {return fpConfigurationHandler;}
187
188   /**
189    * Find a task with an id.
190    * @param id       CONFIGURATION id (not a COMPONENT id!)
191    */
192   AliHLTTask* FindTask(const char* id);
193
194   /**
195    * Print the task list.
196    */
197   void PrintTaskList();
198
199   /**
200    * Run one or more events.
201    * Core of the processing loop. The method expects the task list to be
202    * already created by a previous call to BuildTaskList(const char*)
203    *
204    * All tasks of the list will be subsequently processed for each event.
205    * The system can remain started if the \em bStop parameter is 0. In that
206    * case the system just waits for the next event. A specific call with
207    * nofEvents==0 is needed to execute the stop sequence.
208    * @param iNofEvents number of events
209    * @param bStop      stop the chain after processing
210    * @param trgMask    ctp trigger mask from the rawreader
211    * @param timestamp  timestamp of the event, read from the rawreader
212    * @param eventtype  event type, read from the rawreader
213    * @param participatingDetectors  the bit flags of the participating detectors
214    *           as will we inserted into the Common Data Header. This should only
215    *           be used for software event types.
216    * @return number of reconstructed events, neg error code if failed
217    */
218   int Run(Int_t iNofEvents, int bStop, AliHLTUInt64_t trgMask,
219           AliHLTUInt32_t timestamp, AliHLTUInt32_t eventtype,
220           AliHLTUInt32_t participatingDetectors = 0);
221
222   /**
223    * Run the tasklist
224    * Somehow the 64bit variable/default value did not work out on mac.
225    * Re-introducing the original function, and forwarding it.
226    */
227   int Run(Int_t iNofEvents=1, int bStop=1)
228   {return Run(iNofEvents, bStop, 0, 0, 0);}
229
230   /**
231    * Init all tasks from the list.
232    * The @ref AliHLTTask::Init method is called for each task, the components
233    * will be created.
234    * @return neg error code if failed
235    */
236   int InitTasks();
237
238   /**
239    * Init the stopwatches for all tasks.
240    * @param pStopwatches    object array of stopwatches, for types
241    *                        @see AliHLTComponent::AliHLTStopwatchType
242    * @return neg error code if failed
243    */
244   int InitBenchmarking(TObjArray* pStopwatches);
245
246   /**
247    * Stop the stopwatches for all tasks.
248    * @param pStopwatches    object array of stopwatches, for types
249    *                        @see AliHLTComponent::AliHLTStopwatchType
250    * @return neg error code if failed
251    */
252   int PauseBenchmarking(TObjArray* pStopwatches) const;
253
254   /**
255    * Continue the stopwatches for all tasks.
256    * @param pStopwatches    object array of stopwatches, for types
257    *                        @see AliHLTComponent::AliHLTStopwatchType
258    * @return neg error code if failed
259    */
260   int ResumeBenchmarking(TObjArray* pStopwatches) const;
261
262   /**
263    * Print benchmarking summary.
264    * Optionak: clean up stop watches.
265    * @param pStopwatches    object array of stopwatches
266    * @param bClean          delete stop watches if 1
267    * @return neg error code if failed
268    */
269   int PrintBenchmarking(TObjArray* pStopwatches, int bClean=0) const;
270
271   /**
272    * Start task list.
273    * The @ref AliHLTTask::StartRun method is called for each task, the
274    * components will be prepared for event processing.
275    * @return neg error code if failed
276    */
277   int StartTasks();
278
279   /**
280    * Process task list.
281    * The @ref AliHLTTask::ProcessTask method is called for each task.
282    * @return neg error code if failed
283    */
284   int ProcessTasks(Int_t eventNo, AliHLTUInt64_t trgMask,
285                    AliHLTUInt32_t timestamp, AliHLTUInt32_t eventtype,
286                    AliHLTUInt32_t participatingDetectors = 0);
287
288   /**
289    * Stop task list.
290    * The @ref AliHLTTask::EndRun method is called for each task, the components
291    * will be cleaned after event processing.
292    * @return neg error code if failed
293    */
294   int StopTasks();
295
296   /**
297    * Send a control event trough the chain.
298    * All data sources in the chain are switched to publish a control event like
299    * SOR or EOR. The event is propagated in the same way as a normal event.
300    * @param dt       type of the event
301    */
302   int SendControlEvent(AliHLTComponentDataType dt);
303
304   /**
305    * De-init all tasks from the list.
306    * The @ref AliHLTTask::Deinit method is called for each task, the components
307    * will be deleted.
308    * @return neg error code if failed
309    */
310   int DeinitTasks();
311
312   /**
313    * Cleanup all internal objects from HLTOUT processing.
314    */
315   int CleanHLTOUT();
316
317   /**
318    * The memory allocation function for components.
319    * This function is part of the running environment of the components, 
320    * see AliHLTAnalysisEnvironment
321    */
322   static void* AllocMemory( void* param, unsigned long size );
323
324   /**
325    * The allocation function for component EventDoneData.
326    * This function is part of the running environment of the components,
327    * see AliHLTAnalysisEnvironment
328    */
329   static int AllocEventDoneData( void* param, AliHLTEventID_t eventID, unsigned long size, AliHLTComponentEventDoneData** edd );
330
331   /**
332    * AliRoot embedded reconstruction.
333    * Main entry point to execute the HLT reconstruction from AliRoot. Called
334    * either by the AliHLTReconstructor plugin during AliRoot reconstruction
335    * of raw data, or AliHLTSimulation during simulation of data.
336    *
337    * The two cases are distinguished by the availablility of the AliRunLoader
338    * and raw reader.
339    * - AliRoot simulation: AliRunLoader is available and is propagated to the
340    *   module agents (AliHLTModuleAgent) to generate the corresponding
341    *   configurations and chains, and to the AliHLTOfflineSource components.
342    *   raw reader might be available depending on whether raw data was
343    *   simulated or not.
344    * - AliRoot reconstruction: raw reader is available and is propagated to
345    *   the agents and AliHLTOfflineSource components. AliRunLoader is always
346    *   NULL.
347    *
348    * The system remains started after the processing and just waits for the
349    * next event. A specific call with nofEvents==0 is needed to execute the
350    * stop sequence.
351    *
352    * The 'runLoader' and 'rawReader' parameters are propagated to all active
353    * AliHLTOfflineDataSource's and the HLT chain is processed for the given
354    * number of events. If the rawReader is NULL, reconstruction is done on
355    * simulated data, from real data if a RawReader is specified.
356    *
357    * After setting up the system with the reconstruction parameters the
358    * Run() method is called and carries out the processing of the chain.
359    *
360    * @param nofEvents     number of events
361    * @param runLoader     the AliRoot RunLoader
362    * @param rawReader     the AliRoot RawReader
363    * @return number of reconstructed events, neg. error code if failed 
364    */
365   int Reconstruct(int nofEvents, AliRunLoader* runLoader, 
366                   AliRawReader* rawReader=NULL);
367
368   /**
369    * Fill ESD for one event.
370    * To be called by the AliHLTReconstructor plugin during the event loop
371    * and FillESD method of the AliRoot reconstruction.
372    *
373    * The method is most likely deprecated as the scheme has been slightly
374    * changed. The ESD is filled by the HLTOUT handlers implemented by the
375    * HLT modules rather than by components within the reconstruction chain.
376    * Still, HLT reconstruction chains can be run during the AliRoot
377    * reconstruction, data produced by such chains is automatically added
378    * to the HLTOUT stream in order to be equivalent to the online HLT.
379    * The HLTOUT is processed during AliReconstruction at the end of the
380    * HLT event processing, literally during the FillESD method of the AliRoot
381    * reconstruction interface. The HLT module must implement HLTOUT handlers
382    * and provide those through the module agent.
383    *
384    * @param eventNo       current event no (Note: this event number is just a
385    *                      processing counter and is not related to the nature/
386    *                      origin of the event
387    * @param runLoader     the AliRoot runloader
388    * @param esd           an AliESDEvent instance
389    * @return neg. error code if failed 
390    */
391   int FillESD(int eventNo, AliRunLoader* runLoader, AliESDEvent* esd);
392
393   /**
394    * Process the HLTOUT data.
395    * The provided instance of AliHLTOUT provides the access to the data.
396    * AliHLTSystem queries all registered module agents (AliHLTModuleAgent)
397    * for the ability to treat a specific data block. As the last step the
398    * ESD object is filled. Please note that the provided ESD is the hltEsd
399    * in case of AliReconstructor (switched in AliReconstruction).
400    */
401   int ProcessHLTOUT(AliHLTOUT* pHLTOUT, AliESDEvent* esd);
402
403   /**
404    * Process all kChain-type data blocks of the HLTOUT data.
405    * Handlers of type AliHLTModuleAgent::kChain are executed as the first
406    * step of the processing. The function is invoked from ProcessHLTOUT(),
407    * eventual output of the chain is added to the HLTOUT collection.
408    */
409   int ProcessHLTOUTkChain(AliHLTOUT* pHLTOUT);
410
411   /**
412    * Load component libraries.
413    * @param libs          string of blank separated library names
414    * @return neg. error code if failed 
415    */
416   int LoadComponentLibraries(const char* libs);
417
418   /**
419    * Find a symbol in a dynamically loaded library.
420    * @param library      library
421    * @param symbol       the symbol to find
422    * @return void pointer to function
423    */
424   AliHLTfctVoid FindDynamicSymbol(const char* library, const char* symbol);
425
426   /**
427    * Prepare the HLT system for running.
428    * - module agents are requested to register configurations
429    * - task lists are built from the reconstruction chains of the modules
430    *
431    * @param rawReader    instance of the raw reader or NULL
432    * @param runloader    optional instance of the AliRunLoader
433    * @return neg. error code if failed <br>
434    *         -EBUSY      system is in kRunning state <br>
435    */
436   int Configure(AliRawReader* rawReader, AliRunLoader* runloader=NULL);
437
438   /**
439    * Old method kept for backward compatibilty.
440    *
441    * @param runloader    optional instance of the AliRunLoader
442    * @return neg. error code if failed <br>
443    *         -EBUSY      system is in kRunning state <br>
444    */
445   int Configure(AliRunLoader* runloader=NULL);
446
447   /**
448    * Scan options and load component libraries.
449    * The options consist of blank separated tokens. Libraries can be just
450    * specified by their name, and can be excluded by adding a '!'-mark in
451    * front. <br>
452    * Further options
453    * <!-- NOTE: ignore the \li. <i> and </i>: it's just doxygen formatting -->
454    * \li loglevel=<i>level</i> <br>
455    *     logging level for this processing
456    * \li frameworklog=<i>level</i> <br>
457    *     logging level for framework classes
458    * \li alilog=off
459    *     disable redirection of log messages to AliLog class
460    * \li config=<i>macro</i>
461    *     configuration macro
462    * \li chains=<i>configuration</i>
463    *     comma separated list of configurations to be run during local
464    *     reconstruction
465    * \li libmode=<i>static,dynamic(default)</i>
466    *     libraries are persistent if loaded in mode <i>static</i>, i.e. they
467    *     can't be unloaded
468    */
469   int ScanOptions(const char* options);
470
471   /**
472    * Reset the HLT system.
473    * Reset is not possible while the system is in running state.
474    * @param bForce       force the reset
475    * @return neg. error code if failed <br>
476    *         -EBUSY      system is in kRunning state <br>
477    */
478   int Reset(int bForce=0);
479
480   /**
481    * Load the configurations specified by the module agents.
482    * The runLoader is passed to the agent and allows configuration
483    * selection.
484    * - AliSimulation: runloader valid, raw reader might be valid
485    * - AliReconstruction: runloader always NULL, raw reader valid
486    *
487    * @param rawReader    instance of the raw reader or NULL
488    * @param runloader    optional instance of the AliRunLoader
489    * @return neg. error code if failed 
490    */
491   int LoadConfigurations(AliRawReader* rawReader, AliRunLoader* runloader=NULL);
492
493   /**
494    * Get the reconstruction chains from all agents and build the task lists.
495    * AliHLTModuleAgent implementations can define reconstruction chains
496    * depending on the availibility of AliRunLoader and AliRawReader parameters.
497    *
498    * @param rawReader    instance of the raw reader or NULL
499    * @param runloader    optional instance of the AliRunLoader
500    * @return neg. error code if failed 
501    */
502   int BuildTaskListsFromReconstructionChains(AliRawReader* rawReader, 
503                                              AliRunLoader* runloader=NULL);
504
505   enum AliHLTSystemState {
506     kUninitialized       = 0x0,
507     kLibrariesLoaded     = 0x1,
508     kConfigurationLoaded = 0x2,
509     kTaskListCreated     = 0x4,
510     kReady               = 0x7,
511     kStarted             = 0x8,
512     kRunning             = 0x10,
513     kError               = 0x1000
514   };
515
516   /**
517    * Check status of the system.
518    * @param flag          AliHLTSystemState value to check for
519    * @return 1 if set, 0 if not
520    */
521   int CheckStatus(int flag);
522
523   /**
524    * Get the current status.
525    * @return status flags of @ref AliHLTSystemState
526    */
527   int GetStatusFlags();
528
529   /**
530    * Set logging level for framework classes.
531    * This sets the local logging level of this instance and all subsequent
532    * framework classes to \em level.
533    * @param level     local logging level for the framework classes
534    */
535   void SetFrameworkLog(AliHLTComponentLogSeverity level);
536
537   /**
538    * Customized logging function.
539    * The name of the system and pointer is added at the beginning of each
540    * message if name was set.
541    */
542   int LoggingVarargs(AliHLTComponentLogSeverity severity, 
543                      const char* originClass, const char* originFunc,
544                      const char* file, int line, ... ) const;
545
546  protected:
547  
548  private:
549   /** copy constructor prohibited */
550   AliHLTSystem(const AliHLTSystem&);
551   /** assignment operator prohibited */
552   AliHLTSystem& operator=(const AliHLTSystem&);
553
554   /**
555    * Build task list from a configuration object. 
556    * This method implements the configuration parsing and transformation into
557    * a list of AliHLTTask objects. It has been made private in April 2007. 
558    * Use BuildTaskList(const char*) instead.
559    *
560    * @param pConf    pointer to configuration to build the task list from
561    */
562   int BuildTaskList(AliHLTConfiguration* pConf);
563
564   /**
565    * Set status flags.
566    */
567   int SetStatusFlags(int flags);
568
569   /**
570    * clear status flags.
571    */
572   int ClearStatusFlags(int flags);
573
574   /// Pointer to an instance of @ref AliHLTComponentHandler.
575   AliHLTComponentHandler* fpComponentHandler;                      //! transient
576
577   /// Pointer to an instance of @ref AliHLTConfigurationHandler.
578   AliHLTConfigurationHandler* fpConfigurationHandler;              //! transient
579
580   /** list of tasks */
581   TList fTaskList;                                                 // see above
582
583   /** the number of instances of AliHLTSystem */
584   static int fgNofInstances;                                       // see above
585
586   /** state of the object */
587   int fState;                                                      // see above
588
589   /** chains to be run during reconstruction */
590   TString fChains;                                                 //!transient
591
592   /** array of stopwatches */
593   TObjArray* fStopwatches;                                         //!transient
594
595   /** number of events processed in total */                        
596   int fEventCount;                                                 //!transient
597
598   /** number of events processed successfully */
599   int fGoodEvents;                                                 //!transient
600
601   /** array of default libraries */
602   static const char* fgkHLTDefaultLibs[];                          //!transient
603
604   /** active kChain handlers (AliHLTOUT::AliHLTOUTHandlerListEntryVector*) */
605   void* fpChainHandlers;                                           //!transient
606
607   /** active kEsd handlers (AliHLTOUT::AliHLTOUTHandlerListEntryVector*) */
608   void* fpEsdHandlers;                                             //!transient
609
610   /** active kProprietary handlers (AliHLTOUT::AliHLTOUTHandlerListEntryVector*) */
611   void* fpProprietaryHandlers;                                     //!transient
612
613   /** active HLTOUT task for the reconstruction */
614   AliHLTOUTTask* fpHLTOUTTask;                                     //!transient
615
616   /** special task to publish the control events */
617   AliHLTControlTask* fpControlTask;                                //!transient
618
619   /** name of this system instance */
620   TString fName;                                                   //!transient
621
622   /// ECS parameter string
623   TString fECSParams;                                              //!transient
624
625   /// indicate the argument 'hltout-type'
626   bool fUseHLTOUTComponentTypeGlobal;                              //!transient
627
628   ClassDef(AliHLTSystem, 14);
629 };
630
631 #endif