]>
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 | ||
242bb794 | 23 | #include <TObject.h> |
24 | #include <TList.h> | |
164de2ba | 25 | #include <TString.h> |
242bb794 | 26 | #include "AliHLTLogging.h" |
27 | #include "AliHLTConfiguration.h" | |
28 | #include "AliHLTConfigurationHandler.h" | |
f3506ea2 | 29 | #include "AliHLTComponentHandler.h" |
242bb794 | 30 | |
31 | class AliRunLoader; | |
dee38f1b | 32 | class AliRawReader; |
62bb3cd4 | 33 | class AliRawStream; |
34 | class AliHLTOUTHandler; | |
35 | class AliHLTOUT; | |
242bb794 | 36 | |
37 | /** | |
38 | * @class AliHLTModuleAgent | |
39 | * @brief Agent helper class for HLT sub modules, e.g. PHOS, TPC, Trigger | |
40 | * | |
c215072c | 41 | * This class implements the agent base class for the HLT sub modules. |
90ebac25 | 42 | * The agent of a library gives information on the features of the library/ |
43 | * components, like the configurations to run and other component libraries | |
44 | * it depends on. | |
45 | * @note There must not be more than one agent per module/library. | |
46 | * | |
dee38f1b | 47 | * If a run loader is available, reconstruction is performed on simulated |
48 | * data as part of <tt>AliSimulation</tt>, if the raw reader is present on | |
49 | * raw data as part of <tt>AliReconstruction</tt>. The configurations | |
50 | * can adapt to the two cases. | |
51 | * | |
c215072c | 52 | * All HLT component libraries are loaded on demand through the HLT steering |
53 | * instance (@ref AliHLTSystem). A library can implement an agent derived | |
54 | * from this base class, and has to define one global object of this agent | |
55 | * in the code. The agent will be registered automatically, and the features | |
56 | * can be queried when required. | |
57 | * | |
90ebac25 | 58 | * This is usually done during running the AliRoot reconstruction (see AliRoot |
3294f81a | 59 | * documentation on <tt> AliSimulation </tt> and <tt> AliReconstruction </tt>). |
dee38f1b | 60 | * The HLT implemets the @ref AliHLTSimulation and @ref |
61 | * AliHLTReconstructor which hold the HLT steering object. Several flags can | |
62 | * be specified as options via the <tt>SetRunHLT</tt> method of | |
63 | * <tt>AliSimulation</tt> and the <tt>SetOption</tt> method of | |
90ebac25 | 64 | * <tt>AliReconstruction</tt>, including the component libraries to be loaded. |
65 | * | |
66 | * @section alihltmoduleagent_interface Agent interface | |
67 | * The child can implement the following functions: | |
68 | * - @ref CreateConfigurations <br> | |
dee38f1b | 69 | * Create HLT configuration forming an HLT analysis chain. <br> |
70 | * Reconstruction of raw data or simulated data from digits needs | |
71 | * usually different configurations. If a run loader is available, | |
72 | * reconstruction is performed on simulated data, on raw data if the | |
73 | * raw reader is present. | |
90ebac25 | 74 | * |
dee38f1b | 75 | * - @ref GetReconstructionChains <br> |
76 | * Configurations run during event reconstruction. <br> | |
77 | * Define chains to be run during the recunstruction step, | |
78 | * Depending on the availability of AliRoot run loader or raw reader | |
90ebac25 | 79 | * <br> |
dee38f1b | 80 | * |
90ebac25 | 81 | * - @ref GetRequiredComponentLibraries <br> |
82 | * can indicate further libraries which are required for running the | |
83 | * chains (e.g. if components of another library are used). | |
242bb794 | 84 | * |
90ebac25 | 85 | * - @ref RegisterComponents <br> |
86 | * register componens, this can be used to avoid the component | |
87 | * registration via global objects | |
88 | * @see @ref alihltcomponent-handling | |
89 | * <br> | |
62bb3cd4 | 90 | * - @ref GetHandlerDescription <br> |
91 | * the agent can announce which part of the HLTOUT data can be treated | |
92 | * by the library and through which method. Different types of handlers | |
93 | * are defined to fit the various formats of the HLTOUT data. | |
94 | * @see AliHLTOUTHandlerType | |
95 | * | |
96 | * - @ref GetOutputHandler <br> | |
97 | * Return AliHLTOUTHandler for a given data type and specification. | |
98 | * This is mainly intended to treat detector proprietary data. | |
99 | * | |
100 | * - @ref GetRawStream <br> | |
101 | * Return an AliRawStream object which is capable of treating the | |
102 | * specified data type and specification. Rawstream must be provided | |
103 | * for data blocks intended to be the input for AliRoot detector | |
104 | * reconstruction by replacing the normal input stream. | |
105 | * | |
90ebac25 | 106 | * @section alihltmoduleagent_references References |
107 | * @see @ref AliHLTReconstructor interface to the AliRoot reconstruction | |
108 | * @see @ref AliHLTAgentSample agent for the libAliHLTSample library | |
242bb794 | 109 | * |
110 | * @ingroup alihlt_system | |
111 | */ | |
112 | class AliHLTModuleAgent : public TObject, public AliHLTLogging { | |
113 | public: | |
114 | /** | |
115 | * standard constructor. The agent is automatically registered in the | |
116 | * global agent manager | |
117 | */ | |
118 | AliHLTModuleAgent(); | |
242bb794 | 119 | /** destructor */ |
120 | virtual ~AliHLTModuleAgent(); | |
121 | ||
122 | /** | |
123 | * Print status info. | |
90ebac25 | 124 | * Short summary on registered agents. This function acts globally on the |
125 | * list of agents if no specific agent is specified. | |
242bb794 | 126 | */ |
127 | static void PrintStatus(const char* agent=NULL); | |
128 | ||
129 | /** | |
130 | * Get the first agent in the list | |
131 | * @return pointer to first agent in the list, NULL if empty | |
132 | */ | |
133 | static AliHLTModuleAgent* GetFirstAgent(); | |
134 | ||
135 | /** | |
136 | * Get the next agent in the list | |
137 | * @return pointer to next agent in the list, NULL if end of list | |
138 | */ | |
139 | static AliHLTModuleAgent* GetNextAgent(); | |
140 | ||
f3506ea2 | 141 | /** |
142 | * Activate a component handler for this agent. | |
143 | * The @ref RegisterComponents method will be called in order to allow | |
144 | * the agent to register components. Once activated, the function can | |
145 | * be called repeatedly with the same handler and gently ignores the | |
146 | * invocation. In the current stage of development, only one handler | |
147 | * can be activated per agent. This is sufficient for the current | |
148 | * operation, but can be extended. | |
149 | * @param pHandler [in] the component handler instance | |
150 | */ | |
151 | int ActivateComponentHandler(AliHLTComponentHandler* pHandler); | |
152 | ||
242bb794 | 153 | /** |
154 | * Register all configurations belonging to this module with the | |
155 | * AliHLTConfigurationHandler. The agent can adapt the configurations | |
156 | * to be registered to the current AliRoot setup by checking the | |
dee38f1b | 157 | * runloader and the raw reader. <br> |
158 | * Run loader and raw reader are usually not present at the same time. | |
159 | * If a run loader is available, reconstruction is performed on simulated | |
160 | * data, if the raw reader is present on raw data. The configurations | |
161 | * can adapt to the two cases. | |
162 | * | |
96bda103 | 163 | * @param handler [in] the configuration handler |
dee38f1b | 164 | * @param rawReader [in] AliRoot RawReader instance |
96bda103 | 165 | * @param runloader [in] AliRoot runloader |
242bb794 | 166 | * @return neg. error code if failed |
167 | */ | |
168 | virtual int CreateConfigurations(AliHLTConfigurationHandler* handler, | |
dee38f1b | 169 | AliRawReader* rawReader=NULL, |
242bb794 | 170 | AliRunLoader* runloader=NULL) const; |
171 | ||
172 | /** | |
dee38f1b | 173 | * Get the top configurations for event reconstruction. |
242bb794 | 174 | * A top configuration describes a processing chain. It can simply be |
175 | * described by the last configuration(s) in the chain. | |
176 | * The agent can adapt the configurations to be registered to the current | |
dee38f1b | 177 | * AliRoot setup by checking the run loader and the raw reader. |
178 | * @param rawReader [in] AliRoot RawReader instance | |
179 | * @param runloader [in] AliRoot runloader | |
90ebac25 | 180 | * @return string containing the top configurations separated by blanks |
181 | */ | |
dee38f1b | 182 | virtual const char* GetReconstructionChains(AliRawReader* rawReader=NULL, |
183 | AliRunLoader* runloader=NULL) const; | |
242bb794 | 184 | |
185 | /** | |
dee38f1b | 186 | * Component libraries which the configurations of this agent depend on. <br> |
187 | * @note This is not the right place to specify libraries which this component | |
188 | * library depends. Dependencies must be linked or loaded before. | |
242bb794 | 189 | * @return list of component libraries as a blank-separated string. |
190 | */ | |
191 | virtual const char* GetRequiredComponentLibraries() const; | |
192 | ||
193 | /** | |
f3506ea2 | 194 | * Register components. |
242bb794 | 195 | * This method can be used to register components for the module instead |
f3506ea2 | 196 | * of the 'static object approach'. Registration is done by passing a |
197 | * sample object to the AliHLTComponentHandler via | |
198 | * - @ref AliHLTComponentHandler::RegisterComponent <br> | |
199 | * The sample object is owned by the agent, make sure to delete it. | |
200 | * - @ref AliHLTComponentHandler::AddComponent <br> | |
201 | * Same functionality but handler deletes the object at the end. | |
202 | * | |
203 | * @param pHandler [in] instance of the component handler | |
242bb794 | 204 | */ |
f3506ea2 | 205 | virtual int RegisterComponents(AliHLTComponentHandler* pHandler) const; |
242bb794 | 206 | |
62bb3cd4 | 207 | /** |
208 | * IDs for output handlers. | |
209 | * The agent can provide output handlers in order to treat the output | |
210 | * data coming from the HLTOUT nodes. | |
211 | */ | |
212 | enum AliHLTOUTHandlerType { | |
213 | kUnknownOutput =0, | |
164de2ba | 214 | |
62bb3cd4 | 215 | /** output is in ESD format */ |
216 | kEsd, | |
164de2ba | 217 | |
218 | /** agent provides data for a RawReader | |
219 | * From the data block one or more output blocks can be | |
220 | * created idenditcal to the ddl format. The blocks are | |
221 | * provided to subsequent analysis by a RawReader instance. | |
222 | * The data block can be processed in order to provide the | |
223 | * raw data, e.g. in case of lossless compression. | |
224 | */ | |
225 | kRawReader, | |
226 | ||
227 | /** agent can create a raw stream | |
228 | * The agent directly generates a detector specific RawStream | |
229 | * object. This is used for pre-analyzed data which will not | |
230 | * be converted back to the raw format. | |
231 | */ | |
232 | kRawStream, | |
233 | ||
234 | /** agent provides a chain | |
235 | * The data bock is fed into an analysis chain, the treatment | |
236 | * depends on the components in the chain. | |
237 | */ | |
62bb3cd4 | 238 | kChain, |
164de2ba | 239 | |
62bb3cd4 | 240 | /** agent provides detector specific handler */ |
241 | kProprietary, | |
242 | kLastOutputHandler | |
243 | }; | |
244 | ||
245 | /** | |
246 | * Output handler description. | |
247 | * \em fModule: module name specific for the handler type | |
164de2ba | 248 | * - kRawReader: DDL no printed in ascii format |
249 | * - kRawStream: class name of the RawStream class | |
62bb3cd4 | 250 | * - kChain: blank separated list of chains |
251 | * - kProprietary: name of the handler class | |
252 | */ | |
164de2ba | 253 | class AliHLTOUTHandlerDesc { |
254 | public: | |
255 | AliHLTOUTHandlerDesc() : fHType(kUnknownOutput), fDt(kAliHLTVoidDataType), fModule() {} | |
256 | ||
257 | AliHLTOUTHandlerDesc(AliHLTOUTHandlerType handlerType, AliHLTComponentDataType dt, const char* module) | |
258 | : fHType(handlerType), fDt(dt), fModule(module) {} | |
259 | ||
260 | ~AliHLTOUTHandlerDesc(); | |
261 | ||
262 | private: | |
62bb3cd4 | 263 | /** type of the handler */ |
264 | AliHLTOUTHandlerType fHType; | |
265 | /** data type treated by the handler */ | |
266 | AliHLTComponentDataType fDt; | |
267 | /** class or chain name */ | |
164de2ba | 268 | TString fModule; |
62bb3cd4 | 269 | }; |
270 | ||
271 | /** | |
272 | * Get handler description for a data block. | |
273 | * @param dt [in] data type of the block | |
274 | * @param spec [in] specification of the block | |
164de2ba | 275 | * @param pDesc [out] handler description |
62bb3cd4 | 276 | * @return 1 if the agent can provide a handler, 0 if not |
277 | */ | |
278 | virtual int GetHandlerDescription(AliHLTComponentDataType dt, | |
279 | AliHLTUInt32_t spec, | |
164de2ba | 280 | AliHLTOUTHandlerDesc* pDesc) const; |
281 | ||
62bb3cd4 | 282 | /** |
283 | * Get handler for a data block of the HLTOUT data. | |
164de2ba | 284 | * The agent can also provide an overloaded @ref DeleteOutputHandler |
285 | * function to implement customized clean up. It is also possible to | |
286 | * return the same instance of a handler for different data blocks.<br> | |
287 | * | |
288 | * The framework first collects the handlers for all data blocks, and | |
289 | * calls the @ref AliHLTOUTHandler::ProcessData method afterwords for | |
290 | * each handler. | |
62bb3cd4 | 291 | * @param dt [in] data type of the block |
292 | * @param spec [in] specification of the block | |
164de2ba | 293 | * @return pointer to handler |
62bb3cd4 | 294 | */ |
295 | virtual AliHLTOUTHandler* GetOutputHandler(AliHLTComponentDataType dt, | |
164de2ba | 296 | AliHLTUInt32_t spec); |
297 | ||
298 | /** | |
299 | * Delete an HLTOUT handler. | |
300 | * Even if the agent returned the handler several times, this is the | |
301 | * final cleanup. The framwork makes sure that the handler is not | |
302 | * used any further outside the agent. The default implementation just | |
303 | * deltetes the object. | |
304 | * @param pInstance pointer to handler | |
305 | */ | |
306 | virtual int DeleteOutputHandler(AliHLTOUTHandler* pInstance); | |
62bb3cd4 | 307 | |
308 | /** | |
309 | * Get raw stream for a data block. | |
310 | * @param dt [in] data type of the block | |
311 | * @param spec [in] specification of the block | |
312 | * @param pData [in] data control object | |
313 | * @return Rawstream object, NULL if no Rawstream available for data type/spec | |
314 | */ | |
164de2ba | 315 | // this method is likely to be moved to a specific implementation |
316 | // of AliHLTOUTHandler | |
317 | // virtual AliRawStream* GetRawStream(AliHLTComponentDataType dt, | |
318 | // AliHLTUInt32_t spec, | |
319 | // const AliHLTOUT* pData); | |
62bb3cd4 | 320 | |
90ebac25 | 321 | /** |
322 | * Old method kept for backward compatibility, redirected to @ref | |
dee38f1b | 323 | * GetReconstructionChains. |
90ebac25 | 324 | */ |
325 | const char* GetTopConfigurations(AliRunLoader* runloader=NULL) const { | |
dee38f1b | 326 | return GetReconstructionChains(NULL,runloader); |
90ebac25 | 327 | } |
328 | ||
242bb794 | 329 | protected: |
330 | ||
331 | private: | |
dee38f1b | 332 | /** copy constructor prohibited */ |
333 | AliHLTModuleAgent(const AliHLTModuleAgent&); | |
334 | /** assignment operator prohibited */ | |
335 | AliHLTModuleAgent& operator=(const AliHLTModuleAgent&); | |
336 | ||
242bb794 | 337 | /** |
338 | * Register agent in the global list. | |
339 | * @return neg. error code if failed | |
340 | */ | |
341 | static int Register(AliHLTModuleAgent* pAgent); | |
342 | ||
343 | /** | |
344 | * Unregister agent in the global list. | |
345 | * @return neg. error code if failed | |
346 | */ | |
347 | static int Unregister(AliHLTModuleAgent* pAgent); | |
348 | ||
349 | /** the list of active agents */ | |
7617ca1e | 350 | static AliHLTModuleAgent* fAnchor; //! transient |
351 | ||
352 | /** next element in the list */ | |
353 | AliHLTModuleAgent* fpNext; //! transient | |
242bb794 | 354 | |
355 | /** the current object link (list position) */ | |
7617ca1e | 356 | static AliHLTModuleAgent* fCurrent; //! transient |
357 | ||
358 | /** number of agents */ | |
359 | static int fCount; //! transient | |
242bb794 | 360 | |
f3506ea2 | 361 | /* instance of the active component handler */ |
362 | AliHLTComponentHandler* fpComponentHandler; //! transient | |
363 | ||
364 | ClassDef(AliHLTModuleAgent, 2); | |
242bb794 | 365 | }; |
366 | ||
367 | #endif |