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