correcting doxygen warning
[u/mrichter/AliRoot.git] / HLT / BASE / AliHLTSystem.h
CommitLineData
30338a30 1//-*- Mode: C++ -*-
f23a6e1a 2// @(#) $Id$
3
4#ifndef ALIHLTSYSTEM_H
5#define ALIHLTSYSTEM_H
c5123824 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 *
f23a6e1a 9
b22e91eb 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*/
f23a6e1a 16
b22e91eb 17/**
18 * @defgroup alihlt_system HLT integration into AliRoot
19 * This section describes the HLT integration into AliRoot.
fb345ed7 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 * 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.
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 *
b22e91eb 74 */
f23a6e1a 75
5ec8e281 76#include "AliHLTLogging.h"
77#include <TList.h>
c043fa2c 78#include <TString.h>
f23a6e1a 79
5ec8e281 80class AliHLTComponentHandler;
81class AliHLTConfiguration;
85465857 82class AliHLTConfigurationHandler;
5ec8e281 83class AliHLTTask;
c5123824 84class AliHLTOUT;
f3c1d403 85class AliHLTOUTTask;
19b5c321 86class AliHLTControlTask;
242bb794 87class AliRunLoader;
88class AliRawReader;
af885e0f 89class AliESDEvent;
90ebac25 90class TObjArray;
91class TStopwatch;
f23a6e1a 92
bfccbf68 93/**
94 * @class AliHLTSystem
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.
98 *
b22e91eb 99 * @note This class is only used for the @ref alihlt_system.
100 *
101 * @ingroup alihlt_system
bfccbf68 102 */
5ec8e281 103class AliHLTSystem : public AliHLTLogging {
104 public:
bfccbf68 105 /** default constructor */
19b5c321 106 AliHLTSystem(AliHLTComponentLogSeverity loglevel=kHLTLogDefault, const char* name="");
bfccbf68 107 /** destructor */
f23a6e1a 108 virtual ~AliHLTSystem();
109
bfccbf68 110 /**
a742f6f8 111 * Build a task list
3b35e87c 112 * This method is used to build the tasks from the 'master' configuration
113 * objects which are added to the HLT system handler. This is an iterative
114 * process since the task might depend upon other configurations. For each
115 * configuration object which has not yet been converted into a task, the
116 * method will be called iteratively. Finally, after building all tasks which
117 * the current one depends on have been created, the task is inserted to the
118 * list of tasks with the InsertTask method.
a742f6f8 119 * @param pConf configuration name/id
120 */
121 int BuildTaskList(const char* pConf);
122
123 /**
bfccbf68 124 * Clean the list of tasks and delete all the task objects.
3b35e87c 125 */
5ec8e281 126 int CleanTaskList();
127
bfccbf68 128 /**
129 * Insert a task to the task list.
130 * The method first checks whether all dependencies are resolved (i.e. exist
70ed7d01 131 * already in the task list). During this iteration the cross links between
132 * the tasks are set as well. If all dependencies are resolved, the task is
133 * added at the end of the list.
bfccbf68 134 * @param pTask pointer to task to add
3b35e87c 135 */
5ec8e281 136 int InsertTask(AliHLTTask* pTask);
137
bfccbf68 138 /**
19b5c321 139 * Add HLTOUT task to the end of the task list.
140 * If one of the specified chains has output, an AliHLTOUTTask is
141 * added which controls the output. All other chains are removed from the
142 * AliHLTOUTTask input.
143 * @return 0 if no task has been added, 1 if task has been added
144 */
145 int AddHLTOUTTask(const char* chains);
146
147 AliHLTOUTTask* GetHLTOUTTask() const {return fpHLTOUTTask;}
f331e6c5 148 AliHLTComponentHandler* GetComponentHandler() const {return fpComponentHandler;}
149 AliHLTConfigurationHandler* GetConfigurationHandler() const {return fpConfigurationHandler;}
19b5c321 150
151 /**
bfccbf68 152 * Find a task with an id.
153 * @param id CONFIGURATION id (not a COMPONENT id!)
3b35e87c 154 */
5ec8e281 155 AliHLTTask* FindTask(const char* id);
156
bfccbf68 157 /**
158 * Print the task list.
3b35e87c 159 */
5ec8e281 160 void PrintTaskList();
161
53feaef5 162 /**
163 * Run the task list.
9ce4bf4a 164 * The method checks whether the task list has already been build. If not,
165 * or the configuration list has been changed, the @ref BuildTaskList
dee38f1b 166 * method is called. <br>
53feaef5 167 * All tasks of the list will be subsequently processed for each event.
dee38f1b 168 * The system can remain started if the \em bStop parameter is 0. In that
169 * case the system just waits for the next event. A specific call with
170 * nofEvents==0 is needed to execute the stop sequence.
53feaef5 171 * @param iNofEvents number of events
dee38f1b 172 * @param bStop stop the chain after processing
242bb794 173 * @return number of reconstructed events, neg error code if failed
53feaef5 174 */
41017954 175 int Run(Int_t iNofEvents, int bStop, AliHLTUInt64_t trgMask);
176
177 /**
178 * Run the tasklist
179 * Somehow the 64bit variable/default value did not work out on mac.
180 * Re-introducing the original function, and forwarding it.
181 */
182 int Run(Int_t iNofEvents=1, int bStop=1)
183 {return Run(iNofEvents, bStop, 0);}
53feaef5 184
185 /**
9ce4bf4a 186 * Init all tasks from the list.
187 * The @ref AliHLTTask::Init method is called for each task, the components
188 * will be created.
189 * @return neg error code if failed
190 */
191 int InitTasks();
192
193 /**
90ebac25 194 * Init the stopwatches for all tasks.
195 * @param pStopwatches object array of stopwatches, for types
196 * @see AliHLTComponent::AliHLTStopwatchType
197 * @return neg error code if failed
198 */
199 int InitBenchmarking(TObjArray* pStopwatches);
200
201 /**
032c5e5e 202 * Stop the stopwatches for all tasks.
203 * @param pStopwatches object array of stopwatches, for types
204 * @see AliHLTComponent::AliHLTStopwatchType
205 * @return neg error code if failed
206 */
207 int PauseBenchmarking(TObjArray* pStopwatches) const;
208
209 /**
210 * Continue the stopwatches for all tasks.
211 * @param pStopwatches object array of stopwatches, for types
212 * @see AliHLTComponent::AliHLTStopwatchType
213 * @return neg error code if failed
214 */
215 int ResumeBenchmarking(TObjArray* pStopwatches) const;
216
217 /**
dee38f1b 218 * Print benchmarking summary.
219 * Optionak: clean up stop watches.
220 * @param pStopwatches object array of stopwatches
221 * @param bClean delete stop watches if 1
222 * @return neg error code if failed
223 */
032c5e5e 224 int PrintBenchmarking(TObjArray* pStopwatches, int bClean=0) const;
dee38f1b 225
226 /**
53feaef5 227 * Start task list.
70ed7d01 228 * The @ref AliHLTTask::StartRun method is called for each task, the
229 * components will be prepared for event processing.
53feaef5 230 * @return neg error code if failed
231 */
232 int StartTasks();
233
234 /**
235 * Process task list.
236 * The @ref AliHLTTask::ProcessTask method is called for each task.
237 * @return neg error code if failed
238 */
c4ffab2c 239 int ProcessTasks(Int_t eventNo, AliHLTUInt64_t trgMask=0);
53feaef5 240
241 /**
242 * Stop task list.
243 * The @ref AliHLTTask::EndRun method is called for each task, the components
244 * will be cleaned after event processing.
245 * @return neg error code if failed
5ec8e281 246 */
53feaef5 247 int StopTasks();
5ec8e281 248
9ce4bf4a 249 /**
457ec821 250 * Send a control event trough the chain.
251 * All data sources in the chain are switched to publish a control event like
252 * SOR or EOR. The event is propagated in the same way as a normal event.
253 * @param dt type of the event
254 */
255 int SendControlEvent(AliHLTComponentDataType dt);
256
257 /**
9ce4bf4a 258 * De-init all tasks from the list.
259 * The @ref AliHLTTask::Deinit method is called for each task, the components
260 * will be deleted.
261 * @return neg error code if failed
262 */
263 int DeinitTasks();
264
265 /**
a472be38 266 * Cleanup all internal objects from HLTOUT processing.
267 */
268 int CleanHLTOUT();
269
270 /**
9ce4bf4a 271 * The memory allocation function for components.
272 * This function is part of the running environment of the components.
273 */
274 static void* AllocMemory( void* param, unsigned long size );
275
242bb794 276 /**
324ca3b4 277 * The allocation function for component EventDoneData.
278 * This function is part of the running environment of the components.
279 */
280 static int AllocEventDoneData( void* param, AliHLTEventID_t eventID, unsigned long size, AliHLTComponentEventDoneData** edd );
281
282 /**
dee38f1b 283 * AliRoot embedded reconstruction.
284 * Main entry point to execute the HLT reconstruction from AliRoot. Called
285 * either by the AliHLTReconstructor plugin during AliRoot reconstruction
286 * of raw data, or AliHLTSimulation during simulation of data.
287 *
288 * The two cases are distinguished by the availablility of the run loader
289 * and raw reader.
290 * - AliRoot simulation: run loader is available and is propagated to the
291 * module agents (AliHLTModuleAgent) to generate the corresponding
292 * configurations and chains, and to the AliHLTOfflineSource components.
293 * - AliRoot reconstruction: raw reader is available and is propagated to
294 * the agents and AliHLTOfflineSource components.
295 *
296 * The system remains started after the processing and just waits for the
297 * next event. A specific call with nofEvents==0 is needed to execute the
298 * stop sequence.
299 *
242bb794 300 * The 'runLoader' and 'rawReader' parameters are set to all active
301 * AliHLTOfflineDataSource's and the HLT chain is processed for the given
302 * number of events. If the rawReader is NULL, reconstruction is done on
303 * simulated data, from real data if a RawReader is specified.
304 * @param nofEvents number of events
305 * @param runLoader the AliRoot runloader
306 * @param rawReader the AliRoot RawReader
307 * @return number of reconstructed events, neg. error code if failed
308 */
309 int Reconstruct(int nofEvents, AliRunLoader* runLoader,
310 AliRawReader* rawReader=NULL);
311
312 /**
313 * Fill ESD for one event.
314 * To be called by the AliHLTReconstructor plugin during the event loop
315 * and FillESD method of the AliRoot reconstruction.
c5123824 316 *
317 * The method is most likely deprecated as the scheme has been slightly
318 * changed. The ESD is filled by the HLTOUT handlers u=implemented by the
319 * HLT modules rather than by components within the reconstruction chain.
320 * Still, HLT reconstruction chains can be run during the AliRoot
321 * reconstruction, data produced by such chains is automatically added
322 * to the HLTOUT stream in order to be equivalent to the online HLT.
323 * The HLTOUT is processed during AliReconstruction at the end of the
324 * HLT event processing, literally during the FillESD method of the AliRoot
325 * reconstruction interface. The HLT module must implement HLTOUT handlers
326 * and provide those through the module agent.
327 *
242bb794 328 * This method is called on event basis, and thus must copy the previously
329 * reconstructed data of the event from the 'ESD' recorder. The FillESD
330 * method of all active AliHLTOfflineDataSink's is called.
331 * @param eventNo current event no (Note: this event number is just a
332 * processing counter and is not related to the nature/
333 * origin of the event
334 * @param runLoader the AliRoot runloader
af885e0f 335 * @param esd an AliESDEvent instance
242bb794 336 * @return neg. error code if failed
337 */
af885e0f 338 int FillESD(int eventNo, AliRunLoader* runLoader, AliESDEvent* esd);
242bb794 339
340 /**
c5123824 341 * Process the HLTOUT data.
342 */
343 int ProcessHLTOUT(AliHLTOUT* pHLTOUT, AliESDEvent* esd);
344
345 /**
0f1882a7 346 * Process all kChain-type data blocks of the HLTOUT data.
347 * The function is involed from ProcessHLTOUT as the first step in
348 * the processing.
349 */
350 int ProcessHLTOUTkChain(AliHLTOUT* pHLTOUT);
351
352 /**
242bb794 353 * Load component libraries.
354 * @param libs string of blank separated library names
355 * @return neg. error code if failed
356 */
357 int LoadComponentLibraries(const char* libs);
358
359 /**
85f0cede 360 * Find a symbol in a dynamically loaded library.
361 * @param library library
362 * @param symbol the symbol to find
363 * @return void pointer to function
364 */
f331e6c5 365 AliHLTfctVoid FindDynamicSymbol(const char* library, const char* symbol);
85f0cede 366
367 /**
242bb794 368 * Prepare the HLT system for running.
369 * - module agents are requested to register configurations
370 * - task lists are built from the top configurations of the modules
c043fa2c 371 *
dee38f1b 372 * @param rawReader instance of the raw reader or NULL
c043fa2c 373 * @param runloader optional instance of the run loader
242bb794 374 * @return neg. error code if failed <br>
375 * -EBUSY system is in kRunning state <br>
376 */
dee38f1b 377 int Configure(AliRawReader* rawReader, AliRunLoader* runloader=NULL);
242bb794 378
dee38f1b 379 /**
380 * Old method kept for backward compatibilty.
381 *
382 * @param runloader optional instance of the run loader
383 * @return neg. error code if failed <br>
384 * -EBUSY system is in kRunning state <br>
385 */
386 int Configure(AliRunLoader* runloader=NULL);
c043fa2c 387
388 /**
b005ef92 389 * Scan options and load component libraries.
390 * The options consist of blank separated tokens. Libraries can be just
391 * specified by their name. Further options
1ac82ce6 392 * <!-- NOTE: ignore the \li. <i> and </i>: it's just doxygen formatting -->
c043fa2c 393 * \li loglevel=<i>level</i> <br>
394 * logging level for this processing
dba03d72 395 * \li frameworklog=<i>level</i> <br>
396 * logging level for framework classes
c043fa2c 397 * \li alilog=off
398 * disable redirection of log messages to AliLog class
399 * \li config=<i>macro</i>
400 * configuration macro
dee38f1b 401 * \li chains=<i>configuration</i>
c043fa2c 402 * comma separated list of configurations to be run during local
403 * reconstruction
dba03d72 404 * \li libmode=<i>static,dynamic(default)</i>
405 * libraries are persistent if loaded in mode <i>static</i>, i.e. they
406 * can't be unloaded
c043fa2c 407 */
408 int ScanOptions(const char* options);
409
242bb794 410 /**
411 * Reset the HLT system.
412 * Reset is not possible while the system is in running state.
413 * @param bForce force the reset
414 * @return neg. error code if failed <br>
415 * -EBUSY system is in kRunning state <br>
416 */
417 int Reset(int bForce=0);
418
419 /**
420 * Load the configurations specified by the module agents.
421 * The runLoader is passed to the agent and allows configuration
422 * selection.
dee38f1b 423 * @param rawReader instance of the raw reader or NULL
424 * @param runloader optional instance of the run loader
242bb794 425 * @return neg. error code if failed
426 */
dee38f1b 427 int LoadConfigurations(AliRawReader* rawReader, AliRunLoader* runloader=NULL);
242bb794 428
429 /**
430 * Get the top configurations of all agents and build the task lists.
dee38f1b 431 * @param rawReader instance of the raw reader or NULL
432 * @param runloader optional instance of the run loader
242bb794 433 * @return neg. error code if failed
434 */
f3506ea2 435 int BuildTaskListsFromReconstructionChains(AliRawReader* rawReader,
436 AliRunLoader* runloader=NULL);
242bb794 437
6a8e0bb4 438 enum AliHLTSystemState {
242bb794 439 kUninitialized = 0x0,
440 kLibrariesLoaded = 0x1,
441 kConfigurationLoaded = 0x2,
442 kTaskListCreated = 0x4,
443 kReady = 0x7,
dee38f1b 444 kStarted = 0x8,
445 kRunning = 0x10,
242bb794 446 kError = 0x1000
9253e11b 447 };
242bb794 448
449 /**
450 * Check status of the system.
6a8e0bb4 451 * @param flag AliHLTSystemState value to check for
242bb794 452 * @return 1 if set, 0 if not
453 */
454 int CheckStatus(int flag);
455
456 /**
457 * Get the current status.
6a8e0bb4 458 * @return status flags of @ref AliHLTSystemState
242bb794 459 */
460 int GetStatusFlags();
461
e642a402 462 /**
463 * Set logging level for framework classes.
464 * This sets the local logging level of this instance and all subsequent
465 * framework classes to \em level.
466 * @param level local logging level for the framework classes
467 */
468 void SetFrameworkLog(AliHLTComponentLogSeverity level);
469
97d2b87a 470 /**
471 * Customized logging function.
472 * The name of the system and pointer is added at the beginning of each
473 * message if name was set.
474 */
475 int LoggingVarargs(AliHLTComponentLogSeverity severity,
476 const char* originClass, const char* originFunc,
477 const char* file, int line, ... ) const;
478
5ec8e281 479 protected:
5ec8e281 480
481 private:
c043fa2c 482 /** copy constructor prohibited */
483 AliHLTSystem(const AliHLTSystem&);
484 /** assignment operator prohibited */
485 AliHLTSystem& operator=(const AliHLTSystem&);
486
242bb794 487 /**
f331e6c5 488 * Build task list from a configuration object.
489 * This method implements the configuration parsing and transformation into
490 * a list of AliHLTTask objects. It has been made private in April 2007.
491 * Use BuildTaskList(const char*) instead.
492 *
493 * @param pConf pointer to configuration to build the task list from
494 */
495 int BuildTaskList(AliHLTConfiguration* pConf);
496
497 /**
242bb794 498 * Set status flags.
499 */
500 int SetStatusFlags(int flags);
501
502 /**
503 * clear status flags.
504 */
505 int ClearStatusFlags(int flags);
506
f331e6c5 507 /// Pointer to an instance of @ref AliHLTComponentHandler.
508 AliHLTComponentHandler* fpComponentHandler; //! transient
509
510 /// Pointer to an instance of @ref AliHLTConfigurationHandler.
511 AliHLTConfigurationHandler* fpConfigurationHandler; //! transient
5ec8e281 512
242bb794 513 /** list of tasks */
70ed7d01 514 TList fTaskList; // see above
f23a6e1a 515
fc455fba 516 /** the number of instances of AliHLTSystem */
517 static int fgNofInstances; // see above
518
242bb794 519 /** state of the object */
520 int fState; // see above
521
dee38f1b 522 /** chains to be run during reconstruction */
523 TString fChains; //!transient
524
6a8e0bb4 525 /** array of stopwatches */
dee38f1b 526 TObjArray* fStopwatches; //!transient
527
6a8e0bb4 528 /** number of events processed in total */
dee38f1b 529 int fEventCount; //!transient
530
6a8e0bb4 531 /** number of events processed successfully */
dee38f1b 532 int fGoodEvents; //!transient
c043fa2c 533
6a8e0bb4 534 /** array of default libraries */
535 static const char* fgkHLTDefaultLibs[]; //!transient
536
b005ef92 537 /** active kChain handlers (AliHLTOUT::AliHLTOUTHandlerListEntryVector*) */
538 void* fpChainHandlers; //!transient
539
540 /** active kEsd handlers (AliHLTOUT::AliHLTOUTHandlerListEntryVector*) */
541 void* fpEsdHandlers; //!transient
542
543 /** active kProprietary handlers (AliHLTOUT::AliHLTOUTHandlerListEntryVector*) */
544 void* fpProprietaryHandlers; //!transient
545
f3c1d403 546 /** active HLTOUT task for the reconstruction */
547 AliHLTOUTTask* fpHLTOUTTask; //!transient
548
19b5c321 549 /** special task to publish the control events */
550 AliHLTControlTask* fpControlTask; //!transient
551
552 /** name of this system instance */
553 TString fName; //!transient
554
c4ffab2c 555 /// ECS parameter string
556 TString fECSParams; //!transient
557
558 ClassDef(AliHLTSystem, 13);
f23a6e1a 559};
f23a6e1a 560
c043fa2c 561#endif