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