6 //* This file is property of and copyright by the *
7 //* ALICE Experiment at CERN, All rights reserved. *
8 //* See cxx source for full Copyright notice *
10 // @file AliHLTSystem.h
11 // @author Matthias Richter
13 // @brief Global HLT module management and AliRoot integration.
14 // @note The class is used in Offline (AliRoot) context
18 * @defgroup alihlt_system HLT integration into AliRoot
19 * This section describes the HLT integration into AliRoot.
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)
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.
34 * More details how to setup up such a chain can be found:
35 * - The examples page under @ref tut_hltsystem
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.
44 * Since the detector data is needed, the HLT simulation is run at the
45 * end of AliSimulation.
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>.
50 * More Details an be found in the module:
51 * - @ref alihlt_aliroot_simulation
53 * @section alihlt_system_reconstruction AliRoot reconstruction
55 * Like all other ALICE detectors, HLT utilizes the AliReconstruction interface
56 * to implement a plugin for the AliRoot reconstruction. The reconstructor can be
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
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.
71 * More Details an be found in the module:
72 * - @ref alihlt_aliroot_reconstruction
76 #include "AliHLTLogging.h"
80 class AliHLTComponentHandler;
81 class AliHLTConfiguration;
82 class AliHLTConfigurationHandler;
86 class AliHLTControlTask;
95 * Main class for the HLT integration into AliRoot.
96 * @note This class is only used for the @ref alihlt_system.
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)
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
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.
121 * @section alihltsystem_usage Usage
122 * The class AliHLTPluginBase handles the global instance of AliHLTSystem,
123 * the instance is created and fetched like
125 * // setup the HLT system
126 * AliHLTSystem* pHLT=AliHLTPluginBase::GetInstance();
129 * @ingroup alihlt_system
131 class AliHLTSystem : public AliHLTLogging {
133 /** default constructor */
134 AliHLTSystem(AliHLTComponentLogSeverity loglevel=kHLTLogDefault,
136 AliHLTComponentHandler* pCompHandler=NULL,
137 AliHLTConfigurationHandler* pConfHandler=NULL
140 virtual ~AliHLTSystem();
144 * This method is used to build the list of tasks from the configuration
145 * id of a single 'master' configuration.
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.
153 * The function can be called multiple times in order to add more than one
154 * chain to the system.
156 * @param pConf configuration name/id
158 int BuildTaskList(const char* pConf);
161 * Clean the list of tasks and delete all the task objects.
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
173 int InsertTask(AliHLTTask* pTask);
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
182 int AddHLTOUTTask(const char* chains);
184 AliHLTOUTTask* GetHLTOUTTask() const {return fpHLTOUTTask;}
185 AliHLTComponentHandler* GetComponentHandler() const {return fpComponentHandler;}
186 AliHLTConfigurationHandler* GetConfigurationHandler() const {return fpConfigurationHandler;}
189 * Find a task with an id.
190 * @param id CONFIGURATION id (not a COMPONENT id!)
192 AliHLTTask* FindTask(const char* id);
195 * Print the task list.
197 void PrintTaskList();
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*)
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
218 int Run(Int_t iNofEvents, int bStop, AliHLTUInt64_t trgMask,
219 AliHLTUInt32_t timestamp, AliHLTUInt32_t eventtype,
220 AliHLTUInt32_t participatingDetectors = 0);
222 int Run(Int_t iNofEvents, int bStop, AliHLTTriggerMask_t trgMask,
223 AliHLTUInt32_t timestamp, AliHLTUInt32_t eventtype,
224 AliHLTUInt32_t participatingDetectors = 0);
228 * Somehow the 64bit variable/default value did not work out on mac.
229 * Re-introducing the original function, and forwarding it.
231 int Run(Int_t iNofEvents=1, int bStop=1)
232 {return Run(iNofEvents, bStop, 0, 0, 0);}
235 * Init all tasks from the list.
236 * The @ref AliHLTTask::Init method is called for each task, the components
238 * @return neg error code if failed
243 * Init the stopwatches for all tasks.
244 * @param pStopwatches object array of stopwatches, for types
245 * @see AliHLTComponent::AliHLTStopwatchType
246 * @return neg error code if failed
248 int InitBenchmarking(TObjArray* pStopwatches);
251 * Stop the stopwatches for all tasks.
252 * @param pStopwatches object array of stopwatches, for types
253 * @see AliHLTComponent::AliHLTStopwatchType
254 * @return neg error code if failed
256 int PauseBenchmarking(TObjArray* pStopwatches) const;
259 * Continue the stopwatches for all tasks.
260 * @param pStopwatches object array of stopwatches, for types
261 * @see AliHLTComponent::AliHLTStopwatchType
262 * @return neg error code if failed
264 int ResumeBenchmarking(TObjArray* pStopwatches) const;
267 * Print benchmarking summary.
268 * Optionak: clean up stop watches.
269 * @param pStopwatches object array of stopwatches
270 * @param bClean delete stop watches if 1
271 * @return neg error code if failed
273 int PrintBenchmarking(TObjArray* pStopwatches, int bClean=0) const;
277 * The @ref AliHLTTask::StartRun method is called for each task, the
278 * components will be prepared for event processing.
279 * @return neg error code if failed
285 * The @ref AliHLTTask::ProcessTask method is called for each task.
286 * @return neg error code if failed
288 int ProcessTasks(Int_t eventNo, AliHLTTriggerMask_t trgMask,
289 AliHLTUInt32_t timestamp, AliHLTUInt32_t eventtype,
290 AliHLTUInt32_t participatingDetectors = 0);
294 * The @ref AliHLTTask::EndRun method is called for each task, the components
295 * will be cleaned after event processing.
296 * @return neg error code if failed
301 * Send a control event trough the chain.
302 * All data sources in the chain are switched to publish a control event like
303 * SOR or EOR. The event is propagated in the same way as a normal event.
304 * @param dt type of the event
306 int SendControlEvent(AliHLTComponentDataType dt);
309 * De-init all tasks from the list.
310 * The @ref AliHLTTask::Deinit method is called for each task, the components
312 * @return neg error code if failed
317 * Cleanup all internal objects from HLTOUT processing.
318 * Go through the list of HLTOUT handlers and release them.
320 int CleanupHLTOUTHandlers();
323 * The memory allocation function for components.
324 * This function is part of the running environment of the components,
325 * see AliHLTAnalysisEnvironment
327 static void* AllocMemory( void* param, unsigned long size );
330 * The allocation function for component EventDoneData.
331 * This function is part of the running environment of the components,
332 * see AliHLTAnalysisEnvironment
334 static int AllocEventDoneData( void* param, AliHLTEventID_t eventID, unsigned long size, AliHLTComponentEventDoneData** edd );
337 * AliRoot embedded reconstruction.
338 * Main entry point to execute the HLT reconstruction from AliRoot. Called
339 * either by the AliHLTReconstructor plugin during AliRoot reconstruction
340 * of raw data, or AliHLTSimulation during simulation of data.
342 * The two cases are distinguished by the availablility of the AliRunLoader
344 * - AliRoot simulation: AliRunLoader is available and is propagated to the
345 * module agents (AliHLTModuleAgent) to generate the corresponding
346 * configurations and chains, and to the AliHLTOfflineSource components.
347 * raw reader might be available depending on whether raw data was
349 * - AliRoot reconstruction: raw reader is available and is propagated to
350 * the agents and AliHLTOfflineSource components. AliRunLoader is always
353 * The system remains started after the processing and just waits for the
354 * next event. A specific call with nofEvents==0 is needed to execute the
357 * The 'runLoader' and 'rawReader' parameters are propagated to all active
358 * AliHLTOfflineDataSource's and the HLT chain is processed for the given
359 * number of events. If the rawReader is NULL, reconstruction is done on
360 * simulated data, from real data if a RawReader is specified.
362 * After setting up the system with the reconstruction parameters the
363 * Run() method is called and carries out the processing of the chain.
365 * @param nofEvents number of events
366 * @param runLoader the AliRoot RunLoader
367 * @param rawReader the AliRoot RawReader
368 * @return number of reconstructed events, neg. error code if failed
370 int Reconstruct(int nofEvents, AliRunLoader* runLoader,
371 AliRawReader* rawReader=NULL);
374 * Fill ESD for one event.
375 * To be called by the AliHLTReconstructor plugin during the event loop
376 * and FillESD method of the AliRoot reconstruction.
378 * The method is most likely deprecated as the scheme has been slightly
379 * changed. The ESD is filled by the HLTOUT handlers implemented by the
380 * HLT modules rather than by components within the reconstruction chain.
381 * Still, HLT reconstruction chains can be run during the AliRoot
382 * reconstruction, data produced by such chains is automatically added
383 * to the HLTOUT stream in order to be equivalent to the online HLT.
384 * The HLTOUT is processed during AliReconstruction at the end of the
385 * HLT event processing, literally during the FillESD method of the AliRoot
386 * reconstruction interface. The HLT module must implement HLTOUT handlers
387 * and provide those through the module agent.
389 * @param eventNo current event no (Note: this event number is just a
390 * processing counter and is not related to the nature/
391 * origin of the event
392 * @param runLoader the AliRoot runloader
393 * @param esd an AliESDEvent instance
394 * @return neg. error code if failed
396 int FillESD(int eventNo, AliRunLoader* runLoader, AliESDEvent* esd);
399 * Init the HLTOUT instance for the current event.
400 * The instance can be used by other classes to get hold on the data
402 * @param instance instance to be set as the active HLTOUT
403 * @return -EBUSY other active instance already existing
405 int InitHLTOUT(AliHLTOUT* instance);
408 * Invalidate the HLTOUT instance.
409 * @param instance target variable for the instance
410 * @return -EBUSY if instance in use
412 int InvalidateHLTOUT(AliHLTOUT** instance=NULL);
415 * Get the HLTOUT instance.
416 * User method for processing classes. To be released after use.
417 * @return pointer to HLTOUT instance
419 AliHLTOUT* RequestHLTOUT();
422 * Release the HLTOUT instance after use.
423 * @param instance pointer to instance to be released
424 * @return -ENOENT if instance does not match
426 int ReleaseHLTOUT(const AliHLTOUT* instance);
429 * Process the HLTOUT data.
430 * The provided instance of AliHLTOUT provides the access to the data.
431 * AliHLTSystem queries all registered module agents (AliHLTModuleAgent)
432 * for the ability to treat a specific data block. As the last step the
433 * ESD object is filled. Please note that the provided ESD is the hltEsd
434 * in case of AliReconstructor (switched in AliReconstruction).
436 int ProcessHLTOUT(AliHLTOUT* pHLTOUT, AliESDEvent* esd);
439 * Process all kChain-type data blocks of the HLTOUT data.
440 * Handlers of type AliHLTModuleAgent::kChain are executed as the first
441 * step of the processing. The function is invoked from ProcessHLTOUT(),
442 * eventual output of the chain is added to the HLTOUT collection.
444 int ProcessHLTOUTkChain(AliHLTOUT* pHLTOUT);
447 * Load component libraries.
448 * @param libs string of blank separated library names
449 * @return neg. error code if failed
451 int LoadComponentLibraries(const char* libs);
454 * Find a symbol in a dynamically loaded library.
455 * @param library library
456 * @param symbol the symbol to find
457 * @return void pointer to function
459 AliHLTfctVoid FindDynamicSymbol(const char* library, const char* symbol);
462 * Set participating detectors
463 * @param detMask detector mask
465 void SetDetectorMask(UInt_t detMask) {fDetMask=detMask;}
468 * Prepare the HLT system for running.
469 * - module agents are requested to register configurations
470 * - task lists are built from the reconstruction chains of the modules
472 * @param rawReader instance of the raw reader or NULL
473 * @param runloader optional instance of the AliRunLoader
474 * @return neg. error code if failed <br>
475 * -EBUSY system is in kRunning state <br>
477 int Configure(AliRawReader* rawReader, AliRunLoader* runloader=NULL);
480 * Old method kept for backward compatibilty.
482 * @param runloader optional instance of the AliRunLoader
483 * @return neg. error code if failed <br>
484 * -EBUSY system is in kRunning state <br>
486 int Configure(AliRunLoader* runloader=NULL);
489 * Scan options and load component libraries.
490 * The options consist of blank separated tokens. Libraries can be just
491 * specified by their name, and can be excluded by adding a '!'-mark in
494 * <!-- NOTE: ignore the \li. <i> and </i>: it's just doxygen formatting -->
495 * \li loglevel=<i>level</i> <br>
496 * logging level for this processing
497 * \li frameworklog=<i>level</i> <br>
498 * logging level for framework classes
500 * disable redirection of log messages to AliLog class
501 * \li config=<i>macro</i>
502 * configuration macro
503 * \li chains=<i>configuration</i>
504 * comma separated list of configurations to be run during local
506 * \li libmode=<i>static,dynamic(default)</i>
507 * libraries are persistent if loaded in mode <i>static</i>, i.e. they
510 int ScanOptions(const char* options);
513 * Reset the HLT system.
514 * Reset is not possible while the system is in running state.
515 * @param bForce force the reset
516 * @return neg. error code if failed <br>
517 * -EBUSY system is in kRunning state <br>
519 int Reset(int bForce=0);
522 * Load the configurations specified by the module agents.
523 * The runLoader is passed to the agent and allows configuration
525 * - AliSimulation: runloader valid, raw reader might be valid
526 * - AliReconstruction: runloader always NULL, raw reader valid
528 * @param rawReader instance of the raw reader or NULL
529 * @param runloader optional instance of the AliRunLoader
530 * @return neg. error code if failed
532 int LoadConfigurations(AliRawReader* rawReader, AliRunLoader* runloader=NULL);
535 * Get the reconstruction chains from all agents and build the task lists.
536 * AliHLTModuleAgent implementations can define reconstruction chains
537 * depending on the availibility of AliRunLoader and AliRawReader parameters.
539 * @param rawReader instance of the raw reader or NULL
540 * @param runloader optional instance of the AliRunLoader
541 * @return neg. error code if failed
543 int BuildTaskListsFromReconstructionChains(AliRawReader* rawReader,
544 AliRunLoader* runloader=NULL);
546 enum AliHLTSystemState {
547 kUninitialized = 0x0,
548 kLibrariesLoaded = 0x1,
549 kConfigurationLoaded = 0x2,
550 kTaskListCreated = 0x4,
558 * Check status of the system.
559 * @param flag AliHLTSystemState value to check for
560 * @return 1 if set, 0 if not
562 int CheckStatus(int flag);
565 * Get the current status.
566 * @return status flags of @ref AliHLTSystemState
568 int GetStatusFlags();
571 * Set logging level for framework classes.
572 * This sets the local logging level of this instance and all subsequent
573 * framework classes to \em level.
574 * @param level local logging level for the framework classes
576 void SetFrameworkLog(AliHLTComponentLogSeverity level);
579 * Customized logging function.
580 * The name of the system and pointer is added at the beginning of each
581 * message if name was set.
583 int LoggingVarargs(AliHLTComponentLogSeverity severity,
584 const char* originClass, const char* originFunc,
585 const char* file, int line, ... ) const;
590 /** copy constructor prohibited */
591 AliHLTSystem(const AliHLTSystem&);
592 /** assignment operator prohibited */
593 AliHLTSystem& operator=(const AliHLTSystem&);
596 * Build task list from a configuration object.
597 * This method implements the configuration parsing and transformation into
598 * a list of AliHLTTask objects. It has been made private in April 2007.
599 * Use BuildTaskList(const char*) instead.
601 * @param pConf pointer to configuration to build the task list from
603 int BuildTaskList(AliHLTConfiguration* pConf);
608 int SetStatusFlags(int flags);
611 * clear status flags.
613 int ClearStatusFlags(int flags);
615 /// Pointer to an instance of @ref AliHLTComponentHandler.
616 AliHLTComponentHandler* fpComponentHandler; //! transient
618 /// Pointer to an instance of @ref AliHLTConfigurationHandler.
619 AliHLTConfigurationHandler* fpConfigurationHandler; //! transient
622 TList fTaskList; // see above
624 /** the number of instances of AliHLTSystem */
625 static int fgNofInstances; // see above
627 /** state of the object */
628 int fState; // see above
630 /** chains to be run during reconstruction */
631 TString fChains; //!transient
633 /** array of stopwatches */
634 TObjArray* fStopwatches; //!transient
636 /** number of events processed in total */
637 int fEventCount; //!transient
639 /** number of events processed successfully */
640 int fGoodEvents; //!transient
642 /** array of default libraries */
643 static const char* fgkHLTDefaultLibs[]; //!transient
645 /** active kChain handlers (AliHLTOUT::AliHLTOUTHandlerListEntryVector*) */
646 void* fpChainHandlers; //!transient
648 /** active kEsd handlers (AliHLTOUT::AliHLTOUTHandlerListEntryVector*) */
649 void* fpEsdHandlers; //!transient
651 /** active kProprietary handlers (AliHLTOUT::AliHLTOUTHandlerListEntryVector*) */
652 void* fpProprietaryHandlers; //!transient
654 /** active HLTOUT task for the reconstruction */
655 AliHLTOUTTask* fpHLTOUTTask; //!transient
657 /** HLTOUT instance for the current event */
658 AliHLTOUT* fpHLTOUT; //!transient
660 /** HLTOUT use counter */
661 int fHLTOUTUse; //!transient
663 /** special task to publish the control events */
664 AliHLTControlTask* fpControlTask; //!transient
666 /** name of this system instance */
667 TString fName; //!transient
669 /// ECS parameter string
670 TString fECSParams; //!transient
672 /// indicate the argument 'hltout-type'
673 bool fUseHLTOUTComponentTypeGlobal; //!transient
676 UInt_t fDetMask; //!transient
678 ClassDef(AliHLTSystem, 0);