4 #ifndef ALIHLTMODULEAGENT_H
5 #define ALIHLTMODULEAGENT_H
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 */
10 /** @file AliHLTModuleAgent.h
11 @author Matthias Richter
13 @brief Agent helper class for component libraries.
14 @note The class is used in Offline (AliRoot) context
17 // see below for class documentation
19 // refer to README to build package
21 // visit http://web.ift.uib.no/~kjeks/doc/alice-hlt
26 #include "AliHLTLogging.h"
27 #include "AliHLTConfiguration.h"
28 #include "AliHLTConfigurationHandler.h"
29 #include "AliHLTComponentHandler.h"
34 class AliHLTOUTHandler;
38 * @class AliHLTModuleAgent
39 * @brief Agent helper class for HLT sub modules, e.g. PHOS, TPC, Trigger
41 * This class implements the agent base class for the HLT sub modules.
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
45 * @note There must not be more than one agent per module/library.
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.
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.
58 * This is usually done during running the AliRoot reconstruction (see AliRoot
59 * documentation on <tt> AliSimulation </tt> and <tt> AliReconstruction </tt>).
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
64 * <tt>AliReconstruction</tt>, including the component libraries to be loaded.
66 * @section alihltmoduleagent_interface Agent interface
67 * The child can implement the following functions:
68 * - @ref CreateConfigurations <br>
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.
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
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).
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
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
96 * - @ref GetOutputHandler <br>
97 * Return AliHLTOUTHandler for a given data type and specification.
98 * This is mainly intended to treat detector proprietary data.
100 * @section alihltmoduleagent_references References
101 * @see @ref AliHLTReconstructor interface to the AliRoot reconstruction
102 * @see @ref AliHLTAgentSample agent for the libAliHLTSample library
104 * @ingroup alihlt_system
106 class AliHLTModuleAgent : public TObject, public AliHLTLogging {
109 * standard constructor. The agent is automatically registered in the
110 * global agent manager
114 virtual ~AliHLTModuleAgent();
118 * Short summary on registered agents. This function acts globally on the
119 * list of agents if no specific agent is specified.
121 static void PrintStatus(const char* agent=NULL);
124 * Get the first agent in the list
125 * @return pointer to first agent in the list, NULL if empty
127 static AliHLTModuleAgent* GetFirstAgent();
130 * Get the next agent in the list
131 * @return pointer to next agent in the list, NULL if end of list
133 static AliHLTModuleAgent* GetNextAgent();
136 * Activate a component handler for this agent.
137 * The @ref RegisterComponents method will be called in order to allow
138 * the agent to register components. Once activated, the function can
139 * be called repeatedly with the same handler and gently ignores the
140 * invocation. In the current stage of development, only one handler
141 * can be activated per agent. This is sufficient for the current
142 * operation, but can be extended.
143 * @param pHandler [in] the component handler instance
145 int ActivateComponentHandler(AliHLTComponentHandler* pHandler);
148 * Register all configurations belonging to this module with the
149 * AliHLTConfigurationHandler. The agent can adapt the configurations
150 * to be registered to the current AliRoot setup by checking the
151 * runloader and the raw reader. <br>
152 * Run loader and raw reader are usually not present at the same time.
153 * If a run loader is available, reconstruction is performed on simulated
154 * data, if the raw reader is present on raw data. The configurations
155 * can adapt to the two cases.
157 * @param handler [in] the configuration handler
158 * @param rawReader [in] AliRoot RawReader instance
159 * @param runloader [in] AliRoot runloader
160 * @return neg. error code if failed
162 virtual int CreateConfigurations(AliHLTConfigurationHandler* handler,
163 AliRawReader* rawReader=NULL,
164 AliRunLoader* runloader=NULL) const;
167 * Get the top configurations for event reconstruction.
168 * A top configuration describes a processing chain. It can simply be
169 * described by the last configuration(s) in the chain.
170 * The agent can adapt the configurations to be registered to the current
171 * AliRoot setup by checking the run loader and the raw reader.
172 * @param rawReader [in] AliRoot RawReader instance
173 * @param runloader [in] AliRoot runloader
174 * @return string containing the top configurations separated by blanks
176 virtual const char* GetReconstructionChains(AliRawReader* rawReader=NULL,
177 AliRunLoader* runloader=NULL) const;
180 * Component libraries which the configurations of this agent depend on. <br>
181 * @note This is not the right place to specify libraries which this component
182 * library depends. Dependencies must be linked or loaded before.
183 * @return list of component libraries as a blank-separated string.
185 virtual const char* GetRequiredComponentLibraries() const;
188 * Register components.
189 * This method can be used to register components for the module instead
190 * of the 'static object approach'. Registration is done by passing a
191 * sample object to the AliHLTComponentHandler via
192 * - @ref AliHLTComponentHandler::RegisterComponent <br>
193 * The sample object is owned by the agent, make sure to delete it.
194 * - @ref AliHLTComponentHandler::AddComponent <br>
195 * Same functionality but handler deletes the object at the end.
197 * @param pHandler [in] instance of the component handler
199 virtual int RegisterComponents(AliHLTComponentHandler* pHandler) const;
202 * IDs for output handlers.
203 * The agent can provide output handlers in order to treat the output
204 * data coming from the HLTOUT nodes.
206 enum AliHLTOUTHandlerType {
209 /** output is in ESD format */
212 /** agent provides data for a RawReader
213 * From the data block one or more output blocks can be
214 * created idenditcal to the ddl format. The blocks are
215 * provided to subsequent analysis by a RawReader instance.
216 * The data block can be processed in order to provide the
217 * raw data, e.g. in case of lossless compression.
221 /** agent can create a raw stream
222 * The agent directly generates a detector specific RawStream
223 * object. This is used for pre-analyzed data which will not
224 * be converted back to the raw format.
228 /** agent provides a chain
229 * The data bock is fed into an analysis chain, the treatment
230 * depends on the components in the chain.
234 /** agent provides detector specific handler */
240 * Output handler description.
241 * \em fModule: module name specific for the handler type
242 * - kRawReader: DDL no printed in ascii format
243 * - kRawStream: class name of the RawStream class
244 * - kChain: blank separated list of chains
245 * - kProprietary: name of the handler class
247 class AliHLTOUTHandlerDesc {
249 AliHLTOUTHandlerDesc() : fHType(kUnknownOutput), fDt(kAliHLTVoidDataType), fModule() {}
251 AliHLTOUTHandlerDesc(AliHLTOUTHandlerType handlerType, AliHLTComponentDataType dt, const char* module)
252 : fHType(handlerType), fDt(dt), fModule(module) {}
254 ~AliHLTOUTHandlerDesc() {}
257 /** type of the handler */
258 AliHLTOUTHandlerType fHType;
259 /** data type treated by the handler */
260 AliHLTComponentDataType fDt;
261 /** class or chain name */
266 * Get handler description for a data block.
267 * @param dt [in] data type of the block
268 * @param spec [in] specification of the block
269 * @param pDesc [out] handler description
270 * @return 1 if the agent can provide a handler, 0 if not
272 virtual int GetHandlerDescription(AliHLTComponentDataType dt,
274 AliHLTOUTHandlerDesc* pDesc) const;
277 * Get handler for a data block of the HLTOUT data.
278 * The agent can also provide an overloaded @ref DeleteOutputHandler
279 * function to implement customized clean up. It is also possible to
280 * return the same instance of a handler for different data blocks.<br>
282 * The framework first collects the handlers for all data blocks, and
283 * calls the @ref AliHLTOUTHandler::ProcessData method afterwords for
285 * @param dt [in] data type of the block
286 * @param spec [in] specification of the block
287 * @return pointer to handler
289 virtual AliHLTOUTHandler* GetOutputHandler(AliHLTComponentDataType dt,
290 AliHLTUInt32_t spec);
293 * Delete an HLTOUT handler.
294 * Even if the agent returned the handler several times, this is the
295 * final cleanup. The framwork makes sure that the handler is not
296 * used any further outside the agent. The default implementation just
297 * deltetes the object.
298 * @param pInstance pointer to handler
300 virtual int DeleteOutputHandler(AliHLTOUTHandler* pInstance);
303 * Get raw stream for a data block.
304 * @param dt [in] data type of the block
305 * @param spec [in] specification of the block
306 * @param pData [in] data control object
307 * @return Rawstream object, NULL if no Rawstream available for data type/spec
309 // this method is likely to be moved to a specific implementation
310 // of AliHLTOUTHandler
311 // virtual AliRawStream* GetRawStream(AliHLTComponentDataType dt,
312 // AliHLTUInt32_t spec,
313 // const AliHLTOUT* pData);
316 * Old method kept for backward compatibility, redirected to @ref
317 * GetReconstructionChains.
319 const char* GetTopConfigurations(AliRunLoader* runloader=NULL) const {
320 return GetReconstructionChains(NULL,runloader);
326 /** copy constructor prohibited */
327 AliHLTModuleAgent(const AliHLTModuleAgent&);
328 /** assignment operator prohibited */
329 AliHLTModuleAgent& operator=(const AliHLTModuleAgent&);
332 * Register agent in the global list.
333 * @return neg. error code if failed
335 static int Register(AliHLTModuleAgent* pAgent);
338 * Unregister agent in the global list.
339 * @return neg. error code if failed
341 static int Unregister(AliHLTModuleAgent* pAgent);
343 /** the list of active agents */
344 static AliHLTModuleAgent* fAnchor; //! transient
346 /** next element in the list */
347 AliHLTModuleAgent* fpNext; //! transient
349 /** the current object link (list position) */
350 static AliHLTModuleAgent* fCurrent; //! transient
352 /** number of agents */
353 static int fCount; //! transient
355 /* instance of the active component handler */
356 AliHLTComponentHandler* fpComponentHandler; //! transient
358 ClassDef(AliHLTModuleAgent, 2);