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