]>
Commit | Line | Data |
---|---|---|
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 | |
32 | class AliRunLoader; | |
dee38f1b | 33 | class AliRawReader; |
62bb3cd4 | 34 | class AliRawStream; |
35 | class AliHLTOUTHandler; | |
36 | class AliHLTOUT; | |
12ec5482 | 37 | class 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 | */ | |
108 | class 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 | ||
626bfcc1 | 118 | /** |
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 | ||
242bb794 | 126 | /** |
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 | ||
7dbfa7c9 | 145 | /** |
146 | * Get string of blank separated Module Ids | |
147 | */ | |
148 | static string GetAgentIds(); | |
149 | ||
f3506ea2 | 150 | /** |
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 | ||
242bb794 | 162 | /** |
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 | |
80df291c | 218 | /** |
219 | * Define QA plugins | |
220 | * @return blank separated list of class names | |
221 | */ | |
222 | virtual const char* GetQAPlugins() const; | |
223 | ||
62bb3cd4 | 224 | /** |
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 | |
12ec5482 | 367 | /** |
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 | ||
90ebac25 | 375 | /** |
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 |