getting rid of compilation warnings
[u/mrichter/AliRoot.git] / HLT / BASE / AliHLTModuleAgent.h
1 //-*- Mode: C++ -*-
2 // @(#) $Id$
3
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                               */
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
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
23 #include <TObject.h>
24 #include <TList.h>
25 #include <TString.h>
26 #include "AliHLTLogging.h"
27 #include "AliHLTConfiguration.h"
28 #include "AliHLTConfigurationHandler.h"
29 #include "AliHLTComponentHandler.h"
30
31 class AliRunLoader;
32 class AliRawReader;
33 class AliRawStream;
34 class AliHLTOUTHandler;
35 class AliHLTOUT;
36 class AliHLTModulePreprocessor;
37
38 /**
39  * @class AliHLTModuleAgent
40  * @brief Agent helper class for HLT sub modules, e.g. PHOS, TPC, Trigger
41  *
42  * This class implements the agent base class for the HLT sub modules.
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  *
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  *
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  *
59  * This is usually done during running the AliRoot reconstruction (see AliRoot
60  * documentation on <tt> AliSimulation </tt> and <tt> AliReconstruction </tt>).
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 
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>
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.
75  *
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
80  *                                                                          <br>
81  *
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).
85  *
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>
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  *
101  * @section alihltmoduleagent_references References
102  * @see @ref AliHLTReconstructor interface to the AliRoot reconstruction
103  * @see @ref AliHLTAgentSample agent for the libAliHLTSample library
104  *
105  * @ingroup alihlt_system
106  */
107 class 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(const char* id);
114   /** destructor */
115   virtual ~AliHLTModuleAgent();
116
117   /**
118    * Get module id.
119    * The module id is a string specifying the detector, or module. The
120    * library must follow the naming scheme \it libAliHLTModule.so, e.g.
121    * \it libAliHLTTPC.so if the module is 'TPC'
122    */
123   const char* GetModuleId() const;
124
125   /**
126    * Print status info.
127    * Short summary on registered agents. This function acts globally on the
128    * list of agents if no specific agent is specified.
129    */
130   static void PrintStatus(const char* agent=NULL);
131
132   /**
133    * Get the first agent in the list
134    * @return  pointer to first agent in the list, NULL if empty
135    */
136   static AliHLTModuleAgent* GetFirstAgent();
137
138   /**
139    * Get the next agent in the list
140    * @return  pointer to next agent in the list, NULL if end of list
141    */
142   static AliHLTModuleAgent* GetNextAgent();
143
144   /**
145    * Activate a component handler for this agent.
146    * The @ref RegisterComponents method will be called in order to allow
147    * the agent to register components. Once activated, the function can
148    * be called repeatedly with the same handler and gently ignores the
149    * invocation. In the current stage of development, only one handler
150    * can be activated per agent. This is sufficient for the current
151    * operation, but can be extended.
152    * @param pHandler  [in] the component handler instance
153    */
154   int ActivateComponentHandler(AliHLTComponentHandler* pHandler);
155
156   /**
157    * Register all configurations belonging to this module with the
158    * AliHLTConfigurationHandler. The agent can adapt the configurations
159    * to be registered to the current AliRoot setup by checking the
160    * runloader and the raw reader. <br>
161    * Run loader and raw reader are usually not present at the same time.
162    * If a run loader is available, reconstruction is performed on simulated
163    * data, if the raw reader is present on raw data. The configurations
164    * can adapt to the two cases.
165    *
166    * @param handler   [in] the configuration handler
167    * @param rawReader [in] AliRoot RawReader instance 
168    * @param runloader [in] AliRoot runloader
169    * @return neg. error code if failed
170    */
171   virtual int CreateConfigurations(AliHLTConfigurationHandler* handler,
172                                    AliRawReader* rawReader=NULL,
173                                    AliRunLoader* runloader=NULL) const;
174
175   /**
176    * Get the top configurations for event reconstruction.
177    * A top configuration describes a processing chain. It can simply be
178    * described by the last configuration(s) in the chain. 
179    * The agent can adapt the configurations to be registered to the current
180    * AliRoot setup by checking the run loader and the raw reader.
181    * @param rawReader [in] AliRoot RawReader instance 
182    * @param runloader [in] AliRoot runloader
183    * @return string containing the top configurations separated by blanks
184    */
185   virtual const char* GetReconstructionChains(AliRawReader* rawReader=NULL,
186                                               AliRunLoader* runloader=NULL) const;
187
188   /**
189    * Component libraries which the configurations of this agent depend on. <br>
190    * @note This is not the right place to specify libraries which this component
191    * library depends. Dependencies must be linked or loaded before.
192    * @return list of component libraries as a blank-separated string.
193    */
194   virtual const char* GetRequiredComponentLibraries() const;
195
196   /**
197    * Register components.
198    * This method can be used to register components for the module instead
199    * of the 'static object approach'. Registration is done by passing a
200    * sample object to the AliHLTComponentHandler via
201    * - @ref AliHLTComponentHandler::RegisterComponent                      <br>
202    *        The sample object is owned by the agent, make sure to delete it.
203    * - @ref AliHLTComponentHandler::AddComponent                           <br>
204    *        Same functionality but handler deletes the object at the end.
205    *
206    * @param pHandler  [in] instance of the component handler          
207    */
208   virtual int RegisterComponents(AliHLTComponentHandler* pHandler) const;
209
210   /**
211    * IDs for output handlers.
212    * The agent can provide output handlers in order to treat the output
213    * data coming from the HLTOUT nodes.
214    */
215   enum AliHLTOUTHandlerType {
216     kUnknownOutput =0,
217
218     /** output is in ESD format */
219     kEsd,
220
221     /** agent provides data for a RawReader
222      * From the data block one or more output blocks can be
223      * created idenditcal to the ddl format. The blocks are
224      * provided to subsequent analysis by a RawReader instance.
225      * The data block can be processed in order to provide the
226      * raw data, e.g. in case of lossless compression.
227      */
228     kRawReader,
229
230     /** agent can create a raw stream
231      * The agent directly generates a detector specific RawStream
232      * object. This is used for pre-analyzed data which will not
233      * be converted back to the raw format.
234      */
235     kRawStream,
236
237     /** agent provides a chain
238      * The data bock is fed into an analysis chain, the treatment
239      * depends on the components in the chain.
240      */
241     kChain,
242
243     /** agent provides detector specific handler */
244     kProprietary,
245     kLastOutputHandler
246   };
247
248   /**
249    * Output handler description.
250    * \em fModule: module name specific for the handler type
251    *              - kRawReader: DDL no printed in ascii format
252    *              - kRawStream: class name of the RawStream class
253    *              - kChain:     blank separated list of chains
254    *              - kProprietary: name of the handler class
255    */
256   class AliHLTOUTHandlerDesc {
257   public:
258     AliHLTOUTHandlerDesc() : fHType(kUnknownOutput), fDt(kAliHLTVoidDataType), fModule() {}
259
260     AliHLTOUTHandlerDesc(AliHLTOUTHandlerType handlerType, AliHLTComponentDataType dt, const char* module) 
261       : fHType(handlerType), fDt(dt), fModule(module) {}
262
263     AliHLTOUTHandlerDesc(const AliHLTOUTHandlerDesc& src) 
264       : fHType(src.fHType), fDt(src.fDt), fModule(src.fModule) {}
265
266     const AliHLTOUTHandlerDesc& operator=(const AliHLTOUTHandlerDesc& src) {
267       fHType=src.fHType; fDt=src.fDt; fModule=src.fModule; return *this;
268     }
269
270     ~AliHLTOUTHandlerDesc() {}
271
272   private:
273     /** type of the handler */
274     AliHLTOUTHandlerType    fHType;
275     /** data type treated by the handler */
276     AliHLTComponentDataType fDt;
277     /** class or chain name */
278     TString                 fModule;
279   };
280
281   /**
282    * Get handler description for a data block.
283    * @param dt        [in] data type of the block
284    * @param spec      [in] specification of the block
285    * @param desc      [out] handler description
286    * @return 1 if the agent can provide a handler, 0 if not
287    */
288   virtual int GetHandlerDescription(AliHLTComponentDataType dt,
289                                     AliHLTUInt32_t spec,
290                                     AliHLTOUTHandlerDesc& pDesc) const;
291
292   /**
293    * Get handler for a data block of the HLTOUT data.
294    * The agent can also provide an overloaded @ref DeleteOutputHandler
295    * function to implement customized clean up. It is also possible to
296    * return the same instance of a handler for different data blocks.<br>
297    *
298    * The framework first collects the handlers for all data blocks, and
299    * calls the @ref AliHLTOUTHandler::ProcessData method afterwords for
300    * each handler.
301    * @param dt        [in] data type of the block
302    * @param spec      [in] specification of the block
303    * @return pointer to handler
304    */
305   virtual AliHLTOUTHandler* GetOutputHandler(AliHLTComponentDataType dt,
306                                              AliHLTUInt32_t spec);
307
308   /**
309    * Delete an HLTOUT handler.
310    * Even if the agent returned the handler several times, this is the
311    * final cleanup. The framwork makes sure that the handler is not
312    * used any further outside the agent. The default implementation just
313    * deltetes the object.
314    * @param pInstance      pointer to handler
315    */
316   virtual int DeleteOutputHandler(AliHLTOUTHandler* pInstance);
317
318   /**
319    * Get raw stream for a data block.
320    * @param dt        [in] data type of the block
321    * @param spec      [in] specification of the block
322    * @param pData     [in] data control object
323    * @return Rawstream object, NULL if no Rawstream available for data type/spec
324    */
325   // this method is likely to be moved to a specific implementation
326   // of AliHLTOUTHandler
327 //   virtual AliRawStream* GetRawStream(AliHLTComponentDataType dt,
328 //                                   AliHLTUInt32_t spec,
329 //                                   const AliHLTOUT* pData);
330
331   /**
332    * Get the preprocessor for this component library.
333    * Create an instance of the preprocessor for this component library.
334    * The caller will delete it after useage.
335    * @return pointer to AliHLTModulePreprocessor object.
336    */
337   virtual AliHLTModulePreprocessor* GetPreprocessor();
338
339   /**
340    * Old method kept for backward compatibility, redirected to @ref
341    * GetReconstructionChains.
342    */
343   const char* GetTopConfigurations(AliRunLoader* runloader=NULL) const {
344     return GetReconstructionChains(NULL,runloader);
345   }
346
347  protected:
348
349  private:
350   /** standard constructor prohibited */
351   AliHLTModuleAgent();
352   /** copy constructor prohibited */
353   AliHLTModuleAgent(const AliHLTModuleAgent&);
354   /** assignment operator prohibited */
355   AliHLTModuleAgent& operator=(const AliHLTModuleAgent&);
356
357   /**
358    * Register agent in the global list.
359    * @return neg. error code if failed
360    */
361   static int Register(AliHLTModuleAgent* pAgent);
362
363   /**
364    * Unregister agent in the global list.
365    * @return neg. error code if failed
366    */
367   static int Unregister(AliHLTModuleAgent* pAgent);
368
369   /** the list of active agents */
370   static AliHLTModuleAgent* fAnchor;                               //! transient
371
372   /** next element in the list */
373   AliHLTModuleAgent* fpNext;                                       //! transient
374
375   /** the current object link (list position) */
376   static AliHLTModuleAgent* fCurrent;                              //! transient
377
378   /** number of agents */
379   static int fCount;                                               //! transient
380
381   /** instance of the active component handler */
382   AliHLTComponentHandler* fpComponentHandler;                      //! transient
383
384   /** id of the module */
385   TString fModuleId;                                               //! transient
386
387   ClassDef(AliHLTModuleAgent, 3);
388 };
389
390 #endif