bugfix: correct range of DDL for specified detector
[u/mrichter/AliRoot.git] / HLT / BASE / AliHLTModuleAgent.h
CommitLineData
30338a30 1//-*- Mode: C++ -*-
242bb794 2// @(#) $Id$
3
4#ifndef ALIHLTMODULEAGENT_H
5#define ALIHLTMODULEAGENT_H
79c114b5 6/* This file is property of and copyright by the ALICE HLT Project *
7 * ALICE Experiment at CERN, All rights reserved. *
242bb794 8 * See cxx source for full Copyright notice */
9
10/** @file AliHLTModuleAgent.h
11 @author Matthias Richter
12 @date
13 @brief Agent helper class for component libraries.
14 @note The class is used in Offline (AliRoot) context
15*/
16
30338a30 17// see below for class documentation
18// or
19// refer to README to build package
20// or
21// visit http://web.ift.uib.no/~kjeks/doc/alice-hlt
22
7dbfa7c9 23#include <string>
242bb794 24#include <TObject.h>
25#include <TList.h>
164de2ba 26#include <TString.h>
242bb794 27#include "AliHLTLogging.h"
28#include "AliHLTConfiguration.h"
29#include "AliHLTConfigurationHandler.h"
f3506ea2 30#include "AliHLTComponentHandler.h"
242bb794 31
32class AliRunLoader;
dee38f1b 33class AliRawReader;
62bb3cd4 34class AliRawStream;
35class AliHLTOUTHandler;
36class AliHLTOUT;
12ec5482 37class AliHLTModulePreprocessor;
242bb794 38
39/**
40 * @class AliHLTModuleAgent
41 * @brief Agent helper class for HLT sub modules, e.g. PHOS, TPC, Trigger
42 *
c215072c 43 * This class implements the agent base class for the HLT sub modules.
90ebac25 44 * The agent of a library gives information on the features of the library/
45 * components, like the configurations to run and other component libraries
46 * it depends on.
47 * @note There must not be more than one agent per module/library.
48 *
dee38f1b 49 * If a run loader is available, reconstruction is performed on simulated
a55f626d 50 * data as part of <tt>AliSimulation</tt>, if only the raw reader is present,
51 * on raw data as part of <tt>AliReconstruction</tt>. The configurations
dee38f1b 52 * can adapt to the two cases.
53 *
c215072c 54 * All HLT component libraries are loaded on demand through the HLT steering
55 * instance (@ref AliHLTSystem). A library can implement an agent derived
56 * from this base class, and has to define one global object of this agent
57 * in the code. The agent will be registered automatically, and the features
58 * can be queried when required.
59 *
90ebac25 60 * This is usually done during running the AliRoot reconstruction (see AliRoot
3294f81a 61 * documentation on <tt> AliSimulation </tt> and <tt> AliReconstruction </tt>).
dee38f1b 62 * The HLT implemets the @ref AliHLTSimulation and @ref
63 * AliHLTReconstructor which hold the HLT steering object. Several flags can
64 * be specified as options via the <tt>SetRunHLT</tt> method of
65 * <tt>AliSimulation</tt> and the <tt>SetOption</tt> method of
90ebac25 66 * <tt>AliReconstruction</tt>, including the component libraries to be loaded.
67 *
68 * @section alihltmoduleagent_interface Agent interface
69 * The child can implement the following functions:
70 * - @ref CreateConfigurations <br>
dee38f1b 71 * Create HLT configuration forming an HLT analysis chain. <br>
72 * Reconstruction of raw data or simulated data from digits needs
73 * usually different configurations. If a run loader is available,
a55f626d 74 * reconstruction is performed on simulated data, on raw data if Run
75 * loader is NULL and only the raw reader present.
90ebac25 76 *
dee38f1b 77 * - @ref GetReconstructionChains <br>
78 * Configurations run during event reconstruction. <br>
79 * Define chains to be run during the recunstruction step,
80 * Depending on the availability of AliRoot run loader or raw reader
90ebac25 81 * <br>
dee38f1b 82 *
90ebac25 83 * - @ref GetRequiredComponentLibraries <br>
84 * can indicate further libraries which are required for running the
85 * chains (e.g. if components of another library are used).
242bb794 86 *
90ebac25 87 * - @ref RegisterComponents <br>
88 * register componens, this can be used to avoid the component
89 * registration via global objects
90 * @see @ref alihltcomponent-handling
91 * <br>
62bb3cd4 92 * - @ref GetHandlerDescription <br>
93 * the agent can announce which part of the HLTOUT data can be treated
94 * by the library and through which method. Different types of handlers
95 * are defined to fit the various formats of the HLTOUT data.
96 * @see AliHLTOUTHandlerType
97 *
98 * - @ref GetOutputHandler <br>
99 * Return AliHLTOUTHandler for a given data type and specification.
100 * This is mainly intended to treat detector proprietary data.
101 *
90ebac25 102 * @section alihltmoduleagent_references References
103 * @see @ref AliHLTReconstructor interface to the AliRoot reconstruction
104 * @see @ref AliHLTAgentSample agent for the libAliHLTSample library
242bb794 105 *
106 * @ingroup alihlt_system
107 */
108class AliHLTModuleAgent : public TObject, public AliHLTLogging {
109 public:
110 /**
111 * standard constructor. The agent is automatically registered in the
112 * global agent manager
113 */
626bfcc1 114 AliHLTModuleAgent(const char* id);
242bb794 115 /** destructor */
116 virtual ~AliHLTModuleAgent();
117
118 /**
626bfcc1 119 * Get module id.
120 * The module id is a string specifying the detector, or module. The
af2ed151 121 * library must follow the naming scheme \em libAliHLTModule.so, e.g.
122 * \em libAliHLTTPC.so if the module is 'TPC'
626bfcc1 123 */
124 const char* GetModuleId() const;
125
126 /**
242bb794 127 * Print status info.
90ebac25 128 * Short summary on registered agents. This function acts globally on the
129 * list of agents if no specific agent is specified.
242bb794 130 */
131 static void PrintStatus(const char* agent=NULL);
132
133 /**
134 * Get the first agent in the list
135 * @return pointer to first agent in the list, NULL if empty
136 */
137 static AliHLTModuleAgent* GetFirstAgent();
138
139 /**
140 * Get the next agent in the list
141 * @return pointer to next agent in the list, NULL if end of list
142 */
143 static AliHLTModuleAgent* GetNextAgent();
144
145 /**
7dbfa7c9 146 * Get string of blank separated Module Ids
147 */
148 static string GetAgentIds();
149
150 /**
f3506ea2 151 * Activate a component handler for this agent.
152 * The @ref RegisterComponents method will be called in order to allow
153 * the agent to register components. Once activated, the function can
154 * be called repeatedly with the same handler and gently ignores the
155 * invocation. In the current stage of development, only one handler
156 * can be activated per agent. This is sufficient for the current
157 * operation, but can be extended.
9bb806cd 158 * @param [in] pHandler the component handler instance
f3506ea2 159 */
160 int ActivateComponentHandler(AliHLTComponentHandler* pHandler);
161
162 /**
242bb794 163 * Register all configurations belonging to this module with the
164 * AliHLTConfigurationHandler. The agent can adapt the configurations
165 * to be registered to the current AliRoot setup by checking the
dee38f1b 166 * runloader and the raw reader. <br>
a55f626d 167 * The presence of Run loader and raw reader determines the mode of the
168 * HLT reconstruction. If a run loader is available, reconstruction is
169 * performed on simulated data, a raw reader might be available in that
170 * case also. When running embedded into AliReconstruction, the Run loader
171 * is always NULL and the raw gives access to data. The configurations
dee38f1b 172 * can adapt to the two cases.
173 *
9bb806cd 174 * @param [in] handler the configuration handler
175 * @param [in] rawReader AliRoot RawReader instance
176 * @param [in] runloader AliRoot runloader
242bb794 177 * @return neg. error code if failed
178 */
179 virtual int CreateConfigurations(AliHLTConfigurationHandler* handler,
dee38f1b 180 AliRawReader* rawReader=NULL,
242bb794 181 AliRunLoader* runloader=NULL) const;
182
183 /**
dee38f1b 184 * Get the top configurations for event reconstruction.
242bb794 185 * A top configuration describes a processing chain. It can simply be
186 * described by the last configuration(s) in the chain.
187 * The agent can adapt the configurations to be registered to the current
dee38f1b 188 * AliRoot setup by checking the run loader and the raw reader.
9bb806cd 189 * @param [in] rawReader AliRoot RawReader instance
190 * @param [in] runloader AliRoot runloader
90ebac25 191 * @return string containing the top configurations separated by blanks
192 */
dee38f1b 193 virtual const char* GetReconstructionChains(AliRawReader* rawReader=NULL,
194 AliRunLoader* runloader=NULL) const;
242bb794 195
196 /**
dee38f1b 197 * Component libraries which the configurations of this agent depend on. <br>
198 * @note This is not the right place to specify libraries which this component
199 * library depends. Dependencies must be linked or loaded before.
242bb794 200 * @return list of component libraries as a blank-separated string.
201 */
202 virtual const char* GetRequiredComponentLibraries() const;
203
204 /**
f3506ea2 205 * Register components.
242bb794 206 * This method can be used to register components for the module instead
f3506ea2 207 * of the 'static object approach'. Registration is done by passing a
208 * sample object to the AliHLTComponentHandler via
209 * - @ref AliHLTComponentHandler::RegisterComponent <br>
210 * The sample object is owned by the agent, make sure to delete it.
211 * - @ref AliHLTComponentHandler::AddComponent <br>
212 * Same functionality but handler deletes the object at the end.
213 *
9bb806cd 214 * @param [in] pHandler instance of the component handler
242bb794 215 */
f3506ea2 216 virtual int RegisterComponents(AliHLTComponentHandler* pHandler) const;
242bb794 217
90ebac25 218 /**
80df291c 219 * Define QA plugins
220 * @return blank separated list of class names
221 */
222 virtual const char* GetQAPlugins() const;
223
224 /**
62bb3cd4 225 * IDs for output handlers.
226 * The agent can provide output handlers in order to treat the output
227 * data coming from the HLTOUT nodes.
228 */
229 enum AliHLTOUTHandlerType {
230 kUnknownOutput =0,
164de2ba 231
62bb3cd4 232 /** output is in ESD format */
233 kEsd,
164de2ba 234
235 /** agent provides data for a RawReader
236 * From the data block one or more output blocks can be
237 * created idenditcal to the ddl format. The blocks are
238 * provided to subsequent analysis by a RawReader instance.
239 * The data block can be processed in order to provide the
240 * raw data, e.g. in case of lossless compression.
241 */
242 kRawReader,
243
244 /** agent can create a raw stream
245 * The agent directly generates a detector specific RawStream
246 * object. This is used for pre-analyzed data which will not
247 * be converted back to the raw format.
248 */
249 kRawStream,
250
251 /** agent provides a chain
d1d1bbd7 252 * The data block is fed into an analysis chain, the treatment
164de2ba 253 * depends on the components in the chain.
254 */
62bb3cd4 255 kChain,
164de2ba 256
62bb3cd4 257 /** agent provides detector specific handler */
258 kProprietary,
259 kLastOutputHandler
260 };
261
262 /**
263 * Output handler description.
264 * \em fModule: module name specific for the handler type
164de2ba 265 * - kRawReader: DDL no printed in ascii format
266 * - kRawStream: class name of the RawStream class
62bb3cd4 267 * - kChain: blank separated list of chains
268 * - kProprietary: name of the handler class
269 */
164de2ba 270 class AliHLTOUTHandlerDesc {
271 public:
272 AliHLTOUTHandlerDesc() : fHType(kUnknownOutput), fDt(kAliHLTVoidDataType), fModule() {}
273
274 AliHLTOUTHandlerDesc(AliHLTOUTHandlerType handlerType, AliHLTComponentDataType dt, const char* module)
275 : fHType(handlerType), fDt(dt), fModule(module) {}
276
626bfcc1 277 AliHLTOUTHandlerDesc(const AliHLTOUTHandlerDesc& src)
278 : fHType(src.fHType), fDt(src.fDt), fModule(src.fModule) {}
279
e1723aba 280 AliHLTOUTHandlerDesc& operator=(const AliHLTOUTHandlerDesc& src) {
281 if (this==&src) return *this;
b0914d2e 282 fHType=src.fHType; fDt=src.fDt; fModule=src.fModule; return *this;
626bfcc1 283 }
284
71af1abf 285 ~AliHLTOUTHandlerDesc() {}
164de2ba 286
44dc7683 287 bool operator==(const AliHLTOUTHandlerType handlerType) const {
288 return fHType==handlerType;
289 }
b005ef92 290 /**
291 * Two descriptors are equal if all members match.
292 */
293 bool operator==(const AliHLTOUTHandlerDesc& desc) const {
294 return fDt==desc.fDt && fHType==desc.fHType && fModule==desc.fModule;
295 }
296
c5123824 297 operator AliHLTOUTHandlerType() {return fHType;}
298 operator AliHLTComponentDataType() {return fDt;}
44dc7683 299
164de2ba 300 private:
62bb3cd4 301 /** type of the handler */
13398559 302 AliHLTOUTHandlerType fHType; //!transient
62bb3cd4 303 /** data type treated by the handler */
13398559 304 AliHLTComponentDataType fDt; //!transient
62bb3cd4 305 /** class or chain name */
13398559 306 TString fModule; //!transient
62bb3cd4 307 };
308
c5123824 309 static const AliHLTOUTHandlerDesc fgkVoidHandlerDesc; //! initializer
310
62bb3cd4 311 /**
312 * Get handler description for a data block.
9d4cf2ab 313 * Depending on the data type and data specification the handler must
314 * provide information
315 * - if it can handle the data block, and
316 * - details how it will handle it, mainly the type of the handler
317 * @ref AliHLTOUTHandlerType
318 *
9bb806cd 319 * @param [in] dt data type of the block
320 * @param [in] spec specification of the block
321 * @param [out] desc handler description
62bb3cd4 322 * @return 1 if the agent can provide a handler, 0 if not
323 */
324 virtual int GetHandlerDescription(AliHLTComponentDataType dt,
325 AliHLTUInt32_t spec,
af2ed151 326 AliHLTOUTHandlerDesc& desc) const;
164de2ba 327
62bb3cd4 328 /**
329 * Get handler for a data block of the HLTOUT data.
164de2ba 330 * The agent can also provide an overloaded @ref DeleteOutputHandler
331 * function to implement customized clean up. It is also possible to
332 * return the same instance of a handler for different data blocks.<br>
333 *
334 * The framework first collects the handlers for all data blocks, and
335 * calls the @ref AliHLTOUTHandler::ProcessData method afterwords for
336 * each handler.
9bb806cd 337 * @param [in] dt data type of the block
338 * @param [in] spec specification of the block
164de2ba 339 * @return pointer to handler
62bb3cd4 340 */
341 virtual AliHLTOUTHandler* GetOutputHandler(AliHLTComponentDataType dt,
164de2ba 342 AliHLTUInt32_t spec);
343
344 /**
345 * Delete an HLTOUT handler.
d4a18597 346 * This is the final cleanup. The framwork makes sure that the handler is
347 * not used any further outside the agent. Even if the agent returned the
348 * same handler several times, cleanup is invoked only once. The default
349 * implementation just deletes the object.
164de2ba 350 * @param pInstance pointer to handler
351 */
352 virtual int DeleteOutputHandler(AliHLTOUTHandler* pInstance);
62bb3cd4 353
354 /**
355 * Get raw stream for a data block.
9bb806cd 356 * @param [in] dt data type of the block
357 * @param [in] spec specification of the block
358 * @param [in] pData data control object
62bb3cd4 359 * @return Rawstream object, NULL if no Rawstream available for data type/spec
360 */
164de2ba 361 // this method is likely to be moved to a specific implementation
362 // of AliHLTOUTHandler
363// virtual AliRawStream* GetRawStream(AliHLTComponentDataType dt,
364// AliHLTUInt32_t spec,
365// const AliHLTOUT* pData);
62bb3cd4 366
367 /**
12ec5482 368 * Get the preprocessor for this component library.
369 * Create an instance of the preprocessor for this component library.
370 * The caller will delete it after useage.
371 * @return pointer to AliHLTModulePreprocessor object.
372 */
373 virtual AliHLTModulePreprocessor* GetPreprocessor();
374
375 /**
90ebac25 376 * Old method kept for backward compatibility, redirected to @ref
dee38f1b 377 * GetReconstructionChains.
90ebac25 378 */
379 const char* GetTopConfigurations(AliRunLoader* runloader=NULL) const {
dee38f1b 380 return GetReconstructionChains(NULL,runloader);
90ebac25 381 }
382
242bb794 383 protected:
384
385 private:
626bfcc1 386 /** standard constructor prohibited */
387 AliHLTModuleAgent();
dee38f1b 388 /** copy constructor prohibited */
389 AliHLTModuleAgent(const AliHLTModuleAgent&);
390 /** assignment operator prohibited */
391 AliHLTModuleAgent& operator=(const AliHLTModuleAgent&);
392
242bb794 393 /**
394 * Register agent in the global list.
395 * @return neg. error code if failed
396 */
397 static int Register(AliHLTModuleAgent* pAgent);
398
399 /**
400 * Unregister agent in the global list.
401 * @return neg. error code if failed
402 */
403 static int Unregister(AliHLTModuleAgent* pAgent);
404
405 /** the list of active agents */
13398559 406 static AliHLTModuleAgent* fgAnchor; //! transient
7617ca1e 407
408 /** next element in the list */
409 AliHLTModuleAgent* fpNext; //! transient
242bb794 410
411 /** the current object link (list position) */
13398559 412 static AliHLTModuleAgent* fgCurrent; //! transient
7617ca1e 413
414 /** number of agents */
13398559 415 static int fgCount; //! transient
242bb794 416
626bfcc1 417 /** instance of the active component handler */
f3506ea2 418 AliHLTComponentHandler* fpComponentHandler; //! transient
419
626bfcc1 420 /** id of the module */
421 TString fModuleId; //! transient
422
423 ClassDef(AliHLTModuleAgent, 3);
242bb794 424};
425
426#endif