25bfa088d2b6914eb993d9fbb6b610862387746f
[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 "AliHLTLogging.h"
26 #include "AliHLTConfiguration.h"
27 #include "AliHLTConfigurationHandler.h"
28 #include "AliHLTComponentHandler.h"
29
30 class AliRunLoader;
31 class AliRawReader;
32
33 /**
34  * @class AliHLTModuleAgent
35  * @brief Agent helper class for HLT sub modules, e.g. PHOS, TPC, Trigger
36  *
37  * This class implements the agent base class for the HLT sub modules.
38  * The agent of a library gives information on the features of the library/
39  * components, like the configurations to run and other component libraries
40  * it depends on.
41  * @note There must not be more than one agent per module/library.
42  *
43  * If a run loader is available, reconstruction is performed on simulated
44  * data as part of <tt>AliSimulation</tt>, if the raw reader is present on
45  * raw data as part of <tt>AliReconstruction</tt>. The configurations
46  * can adapt to the two cases.
47  *
48  * All HLT component libraries are loaded on demand through the HLT steering
49  * instance (@ref AliHLTSystem). A library can implement an agent derived 
50  * from this base class, and has to define one global object of this agent
51  * in the code. The agent will be registered automatically, and the features
52  * can be queried when required.
53  *
54  * This is usually done during running the AliRoot reconstruction (see AliRoot
55  * documentation on <tt> AliSimulation </tt> and <tt> AliReconstruction </tt>).
56  * The HLT implemets the @ref AliHLTSimulation and @ref
57  * AliHLTReconstructor which hold the HLT steering object. Several flags can
58  * be specified as options via the <tt>SetRunHLT</tt> method of
59  * <tt>AliSimulation</tt> and the <tt>SetOption</tt> method of 
60  * <tt>AliReconstruction</tt>, including the component libraries to be loaded.
61  *
62  * @section alihltmoduleagent_interface Agent interface
63  * The child can implement the following functions:
64  * - @ref CreateConfigurations                                              <br>
65  *       Create HLT configuration forming an HLT analysis chain.            <br>
66  *       Reconstruction of raw data or simulated data from digits needs
67  *       usually different configurations. If a run loader is available,
68  *       reconstruction is performed on simulated data, on raw data if the
69  *       raw reader is present.
70  *
71  * - @ref GetReconstructionChains                                           <br>
72  *       Configurations run during event reconstruction.                    <br>
73  *       Define chains to be run during the recunstruction step,
74  *       Depending on the availability of AliRoot run loader or raw reader
75  *                                                                          <br>
76  *
77  * - @ref GetRequiredComponentLibraries                                     <br>
78  *       can indicate further libraries which are required for running the
79  *       chains (e.g. if components of another library are used).
80  *
81  * - @ref RegisterComponents                                                <br>
82  *       register componens, this can be used to avoid the component
83  *       registration via global objects 
84  *       @see @ref alihltcomponent-handling
85  *                                                                          <br>
86  * @section alihltmoduleagent_references References
87  * @see @ref AliHLTReconstructor interface to the AliRoot reconstruction
88  * @see @ref AliHLTAgentSample agent for the libAliHLTSample library
89  *
90  * @ingroup alihlt_system
91  */
92 class AliHLTModuleAgent : public TObject, public AliHLTLogging {
93  public:
94   /**
95    * standard constructor. The agent is automatically registered in the
96    * global agent manager
97    */
98   AliHLTModuleAgent();
99   /** destructor */
100   virtual ~AliHLTModuleAgent();
101
102   /**
103    * Print status info.
104    * Short summary on registered agents. This function acts globally on the
105    * list of agents if no specific agent is specified.
106    */
107   static void PrintStatus(const char* agent=NULL);
108
109   /**
110    * Get the first agent in the list
111    * @return  pointer to first agent in the list, NULL if empty
112    */
113   static AliHLTModuleAgent* GetFirstAgent();
114
115   /**
116    * Get the next agent in the list
117    * @return  pointer to next agent in the list, NULL if end of list
118    */
119   static AliHLTModuleAgent* GetNextAgent();
120
121   /**
122    * Activate a component handler for this agent.
123    * The @ref RegisterComponents method will be called in order to allow
124    * the agent to register components. Once activated, the function can
125    * be called repeatedly with the same handler and gently ignores the
126    * invocation. In the current stage of development, only one handler
127    * can be activated per agent. This is sufficient for the current
128    * operation, but can be extended.
129    * @param pHandler  [in] the component handler instance
130    */
131   int ActivateComponentHandler(AliHLTComponentHandler* pHandler);
132
133   /**
134    * Register all configurations belonging to this module with the
135    * AliHLTConfigurationHandler. The agent can adapt the configurations
136    * to be registered to the current AliRoot setup by checking the
137    * runloader and the raw reader. <br>
138    * Run loader and raw reader are usually not present at the same time.
139    * If a run loader is available, reconstruction is performed on simulated
140    * data, if the raw reader is present on raw data. The configurations
141    * can adapt to the two cases.
142    *
143    * @param handler   [in] the configuration handler
144    * @param rawReader [in] AliRoot RawReader instance 
145    * @param runloader [in] AliRoot runloader
146    * @return neg. error code if failed
147    */
148   virtual int CreateConfigurations(AliHLTConfigurationHandler* handler,
149                                    AliRawReader* rawReader=NULL,
150                                    AliRunLoader* runloader=NULL) const;
151
152   /**
153    * Get the top configurations for event reconstruction.
154    * A top configuration describes a processing chain. It can simply be
155    * described by the last configuration(s) in the chain. 
156    * The agent can adapt the configurations to be registered to the current
157    * AliRoot setup by checking the run loader and the raw reader.
158    * @param rawReader [in] AliRoot RawReader instance 
159    * @param runloader [in] AliRoot runloader
160    * @return string containing the top configurations separated by blanks
161    */
162   virtual const char* GetReconstructionChains(AliRawReader* rawReader=NULL,
163                                               AliRunLoader* runloader=NULL) const;
164
165   /**
166    * Component libraries which the configurations of this agent depend on. <br>
167    * @note This is not the right place to specify libraries which this component
168    * library depends. Dependencies must be linked or loaded before.
169    * @return list of component libraries as a blank-separated string.
170    */
171   virtual const char* GetRequiredComponentLibraries() const;
172
173   /**
174    * Register components.
175    * This method can be used to register components for the module instead
176    * of the 'static object approach'. Registration is done by passing a
177    * sample object to the AliHLTComponentHandler via
178    * - @ref AliHLTComponentHandler::RegisterComponent                      <br>
179    *        The sample object is owned by the agent, make sure to delete it.
180    * - @ref AliHLTComponentHandler::AddComponent                           <br>
181    *        Same functionality but handler deletes the object at the end.
182    *
183    * @param pHandler  [in] instance of the component handler          
184    */
185   virtual int RegisterComponents(AliHLTComponentHandler* pHandler) const;
186
187   /**
188    * Old method kept for backward compatibility, redirected to @ref
189    * GetReconstructionChains.
190    */
191   const char* GetTopConfigurations(AliRunLoader* runloader=NULL) const {
192     return GetReconstructionChains(NULL,runloader);
193   }
194
195  protected:
196
197  private:
198   /** copy constructor prohibited */
199   AliHLTModuleAgent(const AliHLTModuleAgent&);
200   /** assignment operator prohibited */
201   AliHLTModuleAgent& operator=(const AliHLTModuleAgent&);
202
203   /**
204    * Register agent in the global list.
205    * @return neg. error code if failed
206    */
207   static int Register(AliHLTModuleAgent* pAgent);
208
209   /**
210    * Unregister agent in the global list.
211    * @return neg. error code if failed
212    */
213   static int Unregister(AliHLTModuleAgent* pAgent);
214
215   /** the list of active agents */
216   static AliHLTModuleAgent* fAnchor;                               //! transient
217
218   /** next element in the list */
219   AliHLTModuleAgent* fpNext;                                       //! transient
220
221   /** the current object link (list position) */
222   static AliHLTModuleAgent* fCurrent;                              //! transient
223
224   /** number of agents */
225   static int fCount;                                               //! transient
226
227   /* instance of the active component handler */
228   AliHLTComponentHandler* fpComponentHandler;                      //! transient
229
230   ClassDef(AliHLTModuleAgent, 2);
231 };
232
233 #endif