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