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
27 #include "AliHLTLogging.h"
28 #include "AliHLTConfiguration.h"
29 #include "AliHLTConfigurationHandler.h"
30 #include "AliHLTComponentHandler.h"
35 class AliHLTOUTHandler;
37 class AliHLTModulePreprocessor;
40 * @class AliHLTModuleAgent
41 * @brief Agent helper class for HLT sub modules, e.g. PHOS, TPC, Trigger
43 * This class implements the agent base class for the HLT sub modules.
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
47 * @note There must not be more than one agent per module/library.
49 * If a run loader is available, reconstruction is performed on simulated
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
52 * can adapt to the two cases.
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.
60 * This is usually done during running the AliRoot reconstruction (see AliRoot
61 * documentation on <tt> AliSimulation </tt> and <tt> AliReconstruction </tt>).
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
66 * <tt>AliReconstruction</tt>, including the component libraries to be loaded.
68 * @section alihltmoduleagent_interface Agent interface
69 * The child can implement the following functions:
70 * - @ref CreateConfigurations <br>
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,
74 * reconstruction is performed on simulated data, on raw data if Run
75 * loader is NULL and only the raw reader present.
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
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).
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
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
98 * - @ref GetOutputHandler <br>
99 * Return AliHLTOUTHandler for a given data type and specification.
100 * This is mainly intended to treat detector proprietary data.
102 * @section alihltmoduleagent_references References
103 * @see @ref AliHLTReconstructor interface to the AliRoot reconstruction
104 * @see @ref AliHLTAgentSample agent for the libAliHLTSample library
106 * @ingroup alihlt_system
108 class AliHLTModuleAgent : public TObject, public AliHLTLogging {
111 * standard constructor. The agent is automatically registered in the
112 * global agent manager
114 AliHLTModuleAgent(const char* id);
116 virtual ~AliHLTModuleAgent();
120 * The module id is a string specifying the detector, or module. The
121 * library must follow the naming scheme \em libAliHLTModule.so, e.g.
122 * \em libAliHLTTPC.so if the module is 'TPC'
124 const char* GetModuleId() const;
128 * Short summary on registered agents. This function acts globally on the
129 * list of agents if no specific agent is specified.
131 static void PrintStatus(const char* agent=NULL);
134 * Get the first agent in the list
135 * @return pointer to first agent in the list, NULL if empty
137 static AliHLTModuleAgent* GetFirstAgent();
140 * Get the next agent in the list
141 * @return pointer to next agent in the list, NULL if end of list
143 static AliHLTModuleAgent* GetNextAgent();
146 * Get string of blank separated Module Ids
148 static string GetAgentIds();
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.
158 * @param [in] pHandler the component handler instance
160 int ActivateComponentHandler(AliHLTComponentHandler* pHandler);
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
166 * runloader and the raw reader. <br>
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
172 * can adapt to the two cases.
174 * @param [in] handler the configuration handler
175 * @param [in] rawReader AliRoot RawReader instance
176 * @param [in] runloader AliRoot runloader
177 * @return neg. error code if failed
179 virtual int CreateConfigurations(AliHLTConfigurationHandler* handler,
180 AliRawReader* rawReader=NULL,
181 AliRunLoader* runloader=NULL) const;
184 * Get the top configurations for event reconstruction.
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
188 * AliRoot setup by checking the run loader and the raw reader.
189 * @param [in] rawReader AliRoot RawReader instance
190 * @param [in] runloader AliRoot runloader
191 * @return string containing the top configurations separated by blanks
193 virtual const char* GetReconstructionChains(AliRawReader* rawReader=NULL,
194 AliRunLoader* runloader=NULL) const;
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.
200 * @return list of component libraries as a blank-separated string.
202 virtual const char* GetRequiredComponentLibraries() const;
205 * Register components.
206 * This method can be used to register components for the module instead
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.
214 * @param [in] pHandler instance of the component handler
216 virtual int RegisterComponents(AliHLTComponentHandler* pHandler) const;
220 * @return blank separated list of class names
222 virtual const char* GetQAPlugins() const;
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.
229 enum AliHLTOUTHandlerType {
232 /** output is in ESD format */
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.
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.
251 /** agent provides a chain
252 * The data block is fed into an analysis chain, the treatment
253 * depends on the components in the chain.
257 /** agent provides detector specific handler */
263 * Output handler description.
264 * \em fModule: module name specific for the handler type
265 * - kRawReader: DDL no printed in ascii format
266 * - kRawStream: class name of the RawStream class
267 * - kChain: blank separated list of chains
268 * - kProprietary: name of the handler class
270 class AliHLTOUTHandlerDesc {
272 AliHLTOUTHandlerDesc() : fHType(kUnknownOutput), fDt(kAliHLTVoidDataType), fModule() {}
274 AliHLTOUTHandlerDesc(AliHLTOUTHandlerType handlerType, AliHLTComponentDataType dt, const char* module)
275 : fHType(handlerType), fDt(dt), fModule(module) {}
277 AliHLTOUTHandlerDesc(const AliHLTOUTHandlerDesc& src)
278 : fHType(src.fHType), fDt(src.fDt), fModule(src.fModule) {}
280 const AliHLTOUTHandlerDesc& operator=(const AliHLTOUTHandlerDesc& src) {
281 fHType=src.fHType; fDt=src.fDt; fModule=src.fModule; return *this;
284 ~AliHLTOUTHandlerDesc() {}
286 bool operator==(const AliHLTOUTHandlerType handlerType) const {
287 return fHType==handlerType;
290 * Two descriptors are equal if all members match.
292 bool operator==(const AliHLTOUTHandlerDesc& desc) const {
293 return fDt==desc.fDt && fHType==desc.fHType && fModule==desc.fModule;
296 operator AliHLTOUTHandlerType() {return fHType;}
297 operator AliHLTComponentDataType() {return fDt;}
300 /** type of the handler */
301 AliHLTOUTHandlerType fHType; //!transient
302 /** data type treated by the handler */
303 AliHLTComponentDataType fDt; //!transient
304 /** class or chain name */
305 TString fModule; //!transient
308 static const AliHLTOUTHandlerDesc fgkVoidHandlerDesc; //! initializer
311 * Get handler description for a data block.
312 * Depending on the data type and data specification the handler must
313 * provide information
314 * - if it can handle the data block, and
315 * - details how it will handle it, mainly the type of the handler
316 * @ref AliHLTOUTHandlerType
318 * @param [in] dt data type of the block
319 * @param [in] spec specification of the block
320 * @param [out] desc handler description
321 * @return 1 if the agent can provide a handler, 0 if not
323 virtual int GetHandlerDescription(AliHLTComponentDataType dt,
325 AliHLTOUTHandlerDesc& desc) const;
328 * Get handler for a data block of the HLTOUT data.
329 * The agent can also provide an overloaded @ref DeleteOutputHandler
330 * function to implement customized clean up. It is also possible to
331 * return the same instance of a handler for different data blocks.<br>
333 * The framework first collects the handlers for all data blocks, and
334 * calls the @ref AliHLTOUTHandler::ProcessData method afterwords for
336 * @param [in] dt data type of the block
337 * @param [in] spec specification of the block
338 * @return pointer to handler
340 virtual AliHLTOUTHandler* GetOutputHandler(AliHLTComponentDataType dt,
341 AliHLTUInt32_t spec);
344 * Delete an HLTOUT handler.
345 * This is the final cleanup. The framwork makes sure that the handler is
346 * not used any further outside the agent. Even if the agent returned the
347 * same handler several times, cleanup is invoked only once. The default
348 * implementation just deletes the object.
349 * @param pInstance pointer to handler
351 virtual int DeleteOutputHandler(AliHLTOUTHandler* pInstance);
354 * Get raw stream for a data block.
355 * @param [in] dt data type of the block
356 * @param [in] spec specification of the block
357 * @param [in] pData data control object
358 * @return Rawstream object, NULL if no Rawstream available for data type/spec
360 // this method is likely to be moved to a specific implementation
361 // of AliHLTOUTHandler
362 // virtual AliRawStream* GetRawStream(AliHLTComponentDataType dt,
363 // AliHLTUInt32_t spec,
364 // const AliHLTOUT* pData);
367 * Get the preprocessor for this component library.
368 * Create an instance of the preprocessor for this component library.
369 * The caller will delete it after useage.
370 * @return pointer to AliHLTModulePreprocessor object.
372 virtual AliHLTModulePreprocessor* GetPreprocessor();
375 * Old method kept for backward compatibility, redirected to @ref
376 * GetReconstructionChains.
378 const char* GetTopConfigurations(AliRunLoader* runloader=NULL) const {
379 return GetReconstructionChains(NULL,runloader);
385 /** standard constructor prohibited */
387 /** copy constructor prohibited */
388 AliHLTModuleAgent(const AliHLTModuleAgent&);
389 /** assignment operator prohibited */
390 AliHLTModuleAgent& operator=(const AliHLTModuleAgent&);
393 * Register agent in the global list.
394 * @return neg. error code if failed
396 static int Register(AliHLTModuleAgent* pAgent);
399 * Unregister agent in the global list.
400 * @return neg. error code if failed
402 static int Unregister(AliHLTModuleAgent* pAgent);
404 /** the list of active agents */
405 static AliHLTModuleAgent* fgAnchor; //! transient
407 /** next element in the list */
408 AliHLTModuleAgent* fpNext; //! transient
410 /** the current object link (list position) */
411 static AliHLTModuleAgent* fgCurrent; //! transient
413 /** number of agents */
414 static int fgCount; //! transient
416 /** instance of the active component handler */
417 AliHLTComponentHandler* fpComponentHandler; //! transient
419 /** id of the module */
420 TString fModuleId; //! transient
422 ClassDef(AliHLTModuleAgent, 3);