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 *
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 * 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.
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 * The class handles a list of configurations. Configurations are translated
97 * into task lists which can be executed.
99 * @note This class is only used for the @ref alihlt_system.
101 * @ingroup alihlt_system
103 class AliHLTSystem : public AliHLTLogging {
105 /** default constructor */
106 AliHLTSystem(AliHLTComponentLogSeverity loglevel=kHLTLogDefault, const char* name="");
108 virtual ~AliHLTSystem();
111 * Pointer to an instance of @ref AliHLTComponentHandler.
113 AliHLTComponentHandler* fpComponentHandler; //! transient
116 * Pointer to an instance of @ref AliHLTConfigurationHandler.
118 AliHLTConfigurationHandler* fpConfigurationHandler; //! transient
121 * Add a configuration to the end of the list.
122 * @param pConf pointer to configuration to add
124 int AddConfiguration(AliHLTConfiguration* pConf);
127 * Insert a configuration to the end of the list after the specified
129 * @param pConf pointer to configuration to insert
130 * @param pPrec pointer to configuration to insert the new one after
132 int InsertConfiguration(AliHLTConfiguration* pConf, AliHLTConfiguration* pPrec);
135 * Remove a configuration from the list.
136 * @param pConf pointer to configuration to delete
138 int DeleteConfiguration(AliHLTConfiguration* pConf);
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
151 int BuildTaskList(const char* pConf);
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
159 int BuildTaskList(AliHLTConfiguration* pConf);
162 * Clean the list of tasks and delete all the task objects.
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
174 int InsertTask(AliHLTTask* pTask);
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
183 int AddHLTOUTTask(const char* chains);
185 AliHLTOUTTask* GetHLTOUTTask() const {return fpHLTOUTTask;}
188 * Find a task with an id.
189 * @param id CONFIGURATION id (not a COMPONENT id!)
191 AliHLTTask* FindTask(const char* id);
194 * Print the task list.
196 void PrintTaskList();
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
211 int Run(Int_t iNofEvents=1, int bStop=1);
214 * Init all tasks from the list.
215 * The @ref AliHLTTask::Init method is called for each task, the components
217 * @return neg error code if failed
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
227 int InitBenchmarking(TObjArray* pStopwatches);
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
235 int PauseBenchmarking(TObjArray* pStopwatches) const;
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
243 int ResumeBenchmarking(TObjArray* pStopwatches) const;
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
252 int PrintBenchmarking(TObjArray* pStopwatches, int bClean=0) const;
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
264 * The @ref AliHLTTask::ProcessTask method is called for each task.
265 * @return neg error code if failed
267 int ProcessTasks(Int_t eventNo);
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
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
283 int SendControlEvent(AliHLTComponentDataType dt);
286 * De-init all tasks from the list.
287 * The @ref AliHLTTask::Deinit method is called for each task, the components
289 * @return neg error code if failed
294 * Cleanup all internal objects from HLTOUT processing.
299 * The memory allocation function for components.
300 * This function is part of the running environment of the components.
302 static void* AllocMemory( void* param, unsigned long size );
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.
310 * The two cases are distinguished by the availablility of the run loader
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.
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
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
331 int Reconstruct(int nofEvents, AliRunLoader* runLoader,
332 AliRawReader* rawReader=NULL);
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.
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.
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
360 int FillESD(int eventNo, AliRunLoader* runLoader, AliESDEvent* esd);
363 * Process the HLTOUT data.
365 int ProcessHLTOUT(AliHLTOUT* pHLTOUT, AliESDEvent* esd);
368 * Process all kChain-type data blocks of the HLTOUT data.
369 * The function is involed from ProcessHLTOUT as the first step in
372 int ProcessHLTOUTkChain(AliHLTOUT* pHLTOUT);
375 * Load component libraries.
376 * @param libs string of blank separated library names
377 * @return neg. error code if failed
379 int LoadComponentLibraries(const char* libs);
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
387 void (*FindDynamicSymbol(const char* library, const char* symbol))();
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
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>
399 int Configure(AliRawReader* rawReader, AliRunLoader* runloader=NULL);
402 * Old method kept for backward compatibilty.
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>
408 int Configure(AliRunLoader* runloader=NULL);
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
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
426 * \li libmode=<i>static,dynamic(default)</i>
427 * libraries are persistent if loaded in mode <i>static</i>, i.e. they
430 int ScanOptions(const char* options);
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>
439 int Reset(int bForce=0);
442 * Load the configurations specified by the module agents.
443 * The runLoader is passed to the agent and allows configuration
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
449 int LoadConfigurations(AliRawReader* rawReader, AliRunLoader* runloader=NULL);
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
457 int BuildTaskListsFromReconstructionChains(AliRawReader* rawReader,
458 AliRunLoader* runloader=NULL);
460 enum AliHLTSystemState {
461 kUninitialized = 0x0,
462 kLibrariesLoaded = 0x1,
463 kConfigurationLoaded = 0x2,
464 kTaskListCreated = 0x4,
472 * Check status of the system.
473 * @param flag AliHLTSystemState value to check for
474 * @return 1 if set, 0 if not
476 int CheckStatus(int flag);
479 * Get the current status.
480 * @return status flags of @ref AliHLTSystemState
482 int GetStatusFlags();
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
490 void SetFrameworkLog(AliHLTComponentLogSeverity level);
493 * Customized logging function.
494 * The name of the system and pointer is added at the beginning of each
495 * message if name was set.
497 int LoggingVarargs(AliHLTComponentLogSeverity severity,
498 const char* originClass, const char* originFunc,
499 const char* file, int line, ... ) const;
504 /** copy constructor prohibited */
505 AliHLTSystem(const AliHLTSystem&);
506 /** assignment operator prohibited */
507 AliHLTSystem& operator=(const AliHLTSystem&);
512 int SetStatusFlags(int flags);
515 * clear status flags.
517 int ClearStatusFlags(int flags);
519 /* TList fConfList; */
520 /* int fbListChanged; */
523 TList fTaskList; // see above
525 /** the number of instances of AliHLTSystem */
526 static int fgNofInstances; // see above
528 /** state of the object */
529 int fState; // see above
531 /** chains to be run during reconstruction */
532 TString fChains; //!transient
534 /** array of stopwatches */
535 TObjArray* fStopwatches; //!transient
537 /** number of events processed in total */
538 int fEventCount; //!transient
540 /** number of events processed successfully */
541 int fGoodEvents; //!transient
543 /** array of default libraries */
544 static const char* fgkHLTDefaultLibs[]; //!transient
546 /** active kChain handlers (AliHLTOUT::AliHLTOUTHandlerListEntryVector*) */
547 void* fpChainHandlers; //!transient
549 /** active kEsd handlers (AliHLTOUT::AliHLTOUTHandlerListEntryVector*) */
550 void* fpEsdHandlers; //!transient
552 /** active kProprietary handlers (AliHLTOUT::AliHLTOUTHandlerListEntryVector*) */
553 void* fpProprietaryHandlers; //!transient
555 /** active HLTOUT task for the reconstruction */
556 AliHLTOUTTask* fpHLTOUTTask; //!transient
558 /** special task to publish the control events */
559 AliHLTControlTask* fpControlTask; //!transient
561 /** name of this system instance */
562 TString fName; //!transient
564 ClassDef(AliHLTSystem, 12);