4aca51d7f4456e5f39eec0b04661ea011e6ead6b
[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
37 /**
38  * @class AliHLTModuleAgent
39  * @brief Agent helper class for HLT sub modules, e.g. PHOS, TPC, Trigger
40  *
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
44  * it depends on.
45  * @note There must not be more than one agent per module/library.
46  *
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.
51  *
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.
57  *
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.
65  *
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.
74  *
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
79  *                                                                          <br>
80  *
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).
84  *
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
89  *                                                                          <br>
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
95  *
96  * - @ref GetOutputHandler                                                  <br>
97  *       Return AliHLTOUTHandler for a given data type and specification.
98  *       This is mainly intended to treat detector proprietary data.
99  *
100  * @section alihltmoduleagent_references References
101  * @see @ref AliHLTReconstructor interface to the AliRoot reconstruction
102  * @see @ref AliHLTAgentSample agent for the libAliHLTSample library
103  *
104  * @ingroup alihlt_system
105  */
106 class AliHLTModuleAgent : public TObject, public AliHLTLogging {
107  public:
108   /**
109    * standard constructor. The agent is automatically registered in the
110    * global agent manager
111    */
112   AliHLTModuleAgent();
113   /** destructor */
114   virtual ~AliHLTModuleAgent();
115
116   /**
117    * Print status info.
118    * Short summary on registered agents. This function acts globally on the
119    * list of agents if no specific agent is specified.
120    */
121   static void PrintStatus(const char* agent=NULL);
122
123   /**
124    * Get the first agent in the list
125    * @return  pointer to first agent in the list, NULL if empty
126    */
127   static AliHLTModuleAgent* GetFirstAgent();
128
129   /**
130    * Get the next agent in the list
131    * @return  pointer to next agent in the list, NULL if end of list
132    */
133   static AliHLTModuleAgent* GetNextAgent();
134
135   /**
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
144    */
145   int ActivateComponentHandler(AliHLTComponentHandler* pHandler);
146
147   /**
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.
156    *
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
161    */
162   virtual int CreateConfigurations(AliHLTConfigurationHandler* handler,
163                                    AliRawReader* rawReader=NULL,
164                                    AliRunLoader* runloader=NULL) const;
165
166   /**
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
175    */
176   virtual const char* GetReconstructionChains(AliRawReader* rawReader=NULL,
177                                               AliRunLoader* runloader=NULL) const;
178
179   /**
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.
184    */
185   virtual const char* GetRequiredComponentLibraries() const;
186
187   /**
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.
196    *
197    * @param pHandler  [in] instance of the component handler          
198    */
199   virtual int RegisterComponents(AliHLTComponentHandler* pHandler) const;
200
201   /**
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.
205    */
206   enum AliHLTOUTHandlerType {
207     kUnknownOutput =0,
208
209     /** output is in ESD format */
210     kEsd,
211
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.
218      */
219     kRawReader,
220
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.
225      */
226     kRawStream,
227
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.
231      */
232     kChain,
233
234     /** agent provides detector specific handler */
235     kProprietary,
236     kLastOutputHandler
237   };
238
239   /**
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
246    */
247   class AliHLTOUTHandlerDesc {
248   public:
249     AliHLTOUTHandlerDesc() : fHType(kUnknownOutput), fDt(kAliHLTVoidDataType), fModule() {}
250
251     AliHLTOUTHandlerDesc(AliHLTOUTHandlerType handlerType, AliHLTComponentDataType dt, const char* module) 
252       : fHType(handlerType), fDt(dt), fModule(module) {}
253
254     ~AliHLTOUTHandlerDesc() {}
255
256   private:
257     /** type of the handler */
258     AliHLTOUTHandlerType    fHType;
259     /** data type treated by the handler */
260     AliHLTComponentDataType fDt;
261     /** class or chain name */
262     TString                 fModule;
263   };
264
265   /**
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
271    */
272   virtual int GetHandlerDescription(AliHLTComponentDataType dt,
273                                     AliHLTUInt32_t spec,
274                                     AliHLTOUTHandlerDesc* pDesc) const;
275
276   /**
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>
281    *
282    * The framework first collects the handlers for all data blocks, and
283    * calls the @ref AliHLTOUTHandler::ProcessData method afterwords for
284    * each handler.
285    * @param dt        [in] data type of the block
286    * @param spec      [in] specification of the block
287    * @return pointer to handler
288    */
289   virtual AliHLTOUTHandler* GetOutputHandler(AliHLTComponentDataType dt,
290                                              AliHLTUInt32_t spec);
291
292   /**
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
299    */
300   virtual int DeleteOutputHandler(AliHLTOUTHandler* pInstance);
301
302   /**
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
308    */
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);
314
315   /**
316    * Old method kept for backward compatibility, redirected to @ref
317    * GetReconstructionChains.
318    */
319   const char* GetTopConfigurations(AliRunLoader* runloader=NULL) const {
320     return GetReconstructionChains(NULL,runloader);
321   }
322
323  protected:
324
325  private:
326   /** copy constructor prohibited */
327   AliHLTModuleAgent(const AliHLTModuleAgent&);
328   /** assignment operator prohibited */
329   AliHLTModuleAgent& operator=(const AliHLTModuleAgent&);
330
331   /**
332    * Register agent in the global list.
333    * @return neg. error code if failed
334    */
335   static int Register(AliHLTModuleAgent* pAgent);
336
337   /**
338    * Unregister agent in the global list.
339    * @return neg. error code if failed
340    */
341   static int Unregister(AliHLTModuleAgent* pAgent);
342
343   /** the list of active agents */
344   static AliHLTModuleAgent* fAnchor;                               //! transient
345
346   /** next element in the list */
347   AliHLTModuleAgent* fpNext;                                       //! transient
348
349   /** the current object link (list position) */
350   static AliHLTModuleAgent* fCurrent;                              //! transient
351
352   /** number of agents */
353   static int fCount;                                               //! transient
354
355   /* instance of the active component handler */
356   AliHLTComponentHandler* fpComponentHandler;                      //! transient
357
358   ClassDef(AliHLTModuleAgent, 2);
359 };
360
361 #endif