ALIROOT-5600 - skip non-participating detector modules
[u/mrichter/AliRoot.git] / HLT / BASE / AliHLTComponentHandler.h
1 //-*- Mode: C++ -*-
2 // $Id$
3
4 #ifndef ALIHLTCOMPONENTHANDLER_H
5 #define ALIHLTCOMPONENTHANDLER_H
6 //* This file is property of and copyright by the                          * 
7 //* ALICE Experiment at CERN, All rights reserved.                         *
8 //* See cxx source for full Copyright notice                               *
9
10 /// @file   AliHLTComponentHandler.h
11 /// @author Matthias Richter, Timm Steinbeck
12 /// @date   
13 /// @brief  Global handling of HLT processing components
14 /// @note   The handler is part of the interface and both used in the
15 ///         Online (PubSub) and Offline (AliRoot) context.
16
17 #include <vector>
18 #include "AliHLTDataTypes.h"
19 #include "AliHLTLogging.h"
20
21 using std::vector;
22
23 class AliHLTComponent;
24 class AliHLTModuleAgent;
25 struct AliHLTAnalysisEnvironment;
26 struct AliHLTComponentDataType;
27
28 /**
29  * @class AliHLTComponentHandler
30  * The component handler controls all the processing components available in
31  * the system. It also controls the component shared libraries.
32  * @ingroup alihlt_component
33  */
34 class AliHLTComponentHandler : public AliHLTLogging {
35  public:
36   /** standard constructor */
37   AliHLTComponentHandler();
38   /** constructor */
39   AliHLTComponentHandler(AliHLTAnalysisEnvironment* pEnv);
40   /** destructor */
41   virtual ~AliHLTComponentHandler();
42
43   /**
44    * Create an instance from the global sigleton.
45    * Instance has to be destroyed by the Destroy function
46    */
47   static AliHLTComponentHandler* CreateHandler();
48
49   /**
50    * Destroy an instance of the global singleton retrieved by
51    * AliHLTComponentHandler::CreateHandler()
52    */
53   int Destroy();
54
55   /**
56    * Library mode.
57    * - kDynamic: library can be unloaded (unload forced at termination of the
58    *             handler
59    * - kStatic:  library persistent, once loaded it stays
60    */
61   enum TLibraryMode {kDynamic, kStatic};
62
63   /**
64    * Set the environment for the HLT framework.
65    * The environment mainly consists of function pointers for the integration
66    * of the HLT framework into a system like the PubSub online system or
67    * AliRoot offline system.
68    * @param pEnv    pointer to @ref AliHLTAnalysisEnvironment structure
69    * @return none
70    */
71   void SetEnvironment(AliHLTAnalysisEnvironment* pEnv);
72
73   /**
74    * Get the current environment.
75    */
76   const AliHLTAnalysisEnvironment* GetEnvironment() const {return &fEnvironment;}
77
78   /**
79    * Set library mode.
80    * The mode effects all loaded libraries until another mode is set.
81    * @param mode             persistent library or not
82    * @return previous mode
83    */
84   TLibraryMode SetLibraryMode(TLibraryMode mode);
85
86   /**
87    * Load a component shared library.
88    * The component library needs to be loaded from the ComponentHanler in order
89    * to automatically register all components in the library.
90    * Registration is done by passing a sample object of the component to the
91    * handler. The object has to be valid during the whole runtime and should
92    * thus be a global object which is ONLY used for the purpose of registration.
93    * This also ensures automatically registration at library load time.
94    * @param libraryPath      const char string containing the library name/path
95    * @param bActivateAgents  activate agents after loading (@ref ActivateAgents)
96    * @return 0 if succeeded, neg. error code if failed
97    */
98   int LoadLibrary( const char* libraryPath, int bActivateAgents=1);
99
100   /**
101    * Find a symbol in a dynamically loaded library.
102    * @param library      library
103    * @param symbol       the symbol to find
104    * @return void pointer to function
105    */
106   AliHLTfctVoid FindSymbol(const char* library, const char* symbol);
107
108   /**
109    * Unload a component shared library.
110    * All components will be de-registered when the last instance of the
111    * library was unloaded.
112    * @param libraryPath  library name as specified to @ref LoadLibrary
113    * @return 0 if succeeded, neg. error code if failed
114    */
115   int UnloadLibrary( const char* libraryPath );
116
117   /**
118    * Schedule a component for registration.
119    * Full registration will be done after successfull loading of the shared
120    * library.
121    * @param pSample  a sample object of the component
122    * @return neg. error code if failed
123    */
124   int ScheduleRegister(AliHLTComponent* pSample );
125
126   /**
127    * Register a component.
128    * Registration is done by passing a sample object of the component to the
129    * handler. The object has to be valid during the whole runtime and should
130    * thus be a global object which is ONLY used for the purpose of registration.
131    * @param pSample   a sample object of the component
132    * @return neg. error code if failed
133    */
134   int RegisterComponent(AliHLTComponent* pSample);
135
136   /**
137    * Add a component and leave control of the sample object to the handler.
138    * Exactly the same functionality as @ref RegisterComponent but deletes
139    * the sample object at clean-up of the handler.
140    * @param pSample   a sample object of the component
141    * @return neg. error code if failed
142    */
143   int AddComponent(AliHLTComponent* pSample);
144
145   /**
146    * Registers all scheduled components.
147    */
148   int RegisterScheduledComponents();
149
150   /**
151    * Deregister a component.
152    * @param componentID   ID of the component
153    * @return neg. error code if failed
154    */
155   int DeregisterComponent( const char* componentID );
156
157   /**
158    * Add standard components
159    * The standard components are part of the libHLTbase library and
160    * need therefore a special handling.
161    */
162   int AddStandardComponents();
163
164   /**
165    */
166   int DeleteOwnedComponents();
167
168   /**
169    * Find the ID of a component with the given output data.
170    * @param dtype     data type descriptor
171    * @param prevType  can be used to iterate if there are multiple components
172    *                  with the same output data type.
173    * @return component id
174    */
175   //const char* FindComponentType( AliHLTComponentDataType dtype,
176   //                               const char* prevType = NULL )
177   //  { return NULL;}
178
179   /**
180    * Create a component of the given name (ID).
181    * The method tries to find a registerd component of id \em componentID and
182    * calls the \em Spawn method of the template component. After successful
183    * creation of a new object, the Init method is called in order to initialize
184    * the environment and the component arguments. <br>
185    * The environment is the same for all components, but each component can
186    * have an additional private parameter \em pEnvParam.<br>
187    * The component arguments consist of an array of strings and the array size
188    * in the usual manner of the main() function.
189    * @param componentID  ID of the component to create
190    * @param pEnvParam    environment parameter for the component
191    * @param argc         number of arguments in argv
192    * @param argv         argument array like in main()
193    * @param component    reference to receive the create component instance
194    * @return component pointer in component, neg. error code if failed
195    */
196   int CreateComponent( const char* componentID, void* pEnvParam, 
197                        int argc, const char** argv, AliHLTComponent*& component);
198
199   /**
200    * Create component without initializing it.
201    * @param componentID  ID of the component to create
202    * @param component    reference to receive the create component instance
203    */
204   int CreateComponent(const char* componentID, AliHLTComponent*& component );
205
206   /**
207    * Create a component of the given name (ID).
208    * Introduced for backward compatibility.
209    * @param componentID  ID of the component to create
210    * @param pEnvParam    environment parameter for the component
211    * @param component    reference to receive the create component instance
212    * @return component pointer in component, neg. error code if failed
213    */
214   int CreateComponent( const char* componentID, void* pEnvParam, 
215                        AliHLTComponent*& component ) 
216     {
217     return CreateComponent( componentID, pEnvParam, 0, NULL, component );
218     }
219
220   /**
221    * Set the run description.
222    * The run description is set globally for all components. Each component
223    * is initialized from the global run description after creation and before
224    * call of AliHLTComponent::Init().
225    *
226    * @param desc    run descriptor, currently only the run no member is used
227    * @param runType originally, run type was supposed to be a number and part
228    *                of the run descriptor. But it was defined as string later
229    */
230   int SetRunDescription(const AliHLTRunDesc* desc, const char* runType);
231
232   /**
233    * Check if a registered component has output data, e.g. is of type
234    * kSource or kProcessor (see @ref AliHLTComponent::TComponentType).
235    * @param componentID  ID of the component to create
236    * @return 1 if component has output data, 0 if not                 <br>
237    *         -ENOENT     if component does not exist
238    */
239   int HasOutputData( const char* componentID);
240
241   /**
242    * Print registered components to stdout.
243    * @return none
244    */
245   void List();
246
247   /**
248    * Announce version and compilation info of the base library.
249    */
250   int AnnounceVersion();
251
252   /**
253    * Find a component.
254    * @param componentID  ID of the component to find
255    * @return index, neg. error code if failed
256    */
257   int FindComponentIndex(const char* componentID);
258
259  protected:
260
261  private:
262   /** copy constructor prohibited */
263   AliHLTComponentHandler(const AliHLTComponentHandler&);
264   /** assignment operator prohibited */
265   AliHLTComponentHandler& operator=(const AliHLTComponentHandler&);
266
267   /**
268    * Find a component.
269    * @param componentID  ID of the component to find
270    * @return descriptor
271    */
272   AliHLTComponent* FindComponent(const char* componentID);
273
274   /**
275    * Insert component to the list
276    * @param pSample      sample object of the component
277    * @return neg. error code if failed
278    */
279   int InsertComponent(AliHLTComponent* pSample);
280
281   /**
282    * Close all libraries.
283    * @return neg. error code if failed
284    */
285   int UnloadLibraries();
286
287   /**
288    * Activate all module agents with this component handler.
289    * The function loops over all available module agents and activates
290    * each agent with this component handler. During activation, the
291    * dynamic component registration is carried out by the agents version
292    * of @ref AliHLTModuleAgent::RegisterComponents
293    *
294    * Agents are identified by an id which is a string containing the
295    * module name. Libraries follow the naming scheme libAliHLT<MOD>.so
296    * If the library name is provided and the specific agent found in the
297    * list, only that one is activated. All pending agents otherwize.
298    * @param library       library to activate the agent for
299    * @param blackList     blank separated list of module ids
300    */
301   int ActivateAgents(const char* library=NULL, const char* blackList=NULL);
302
303 public:
304   /**
305    * Compound descriptor for component libraries - must be public 
306    */
307   struct AliHLTLibHandle {
308     AliHLTLibHandle() : fHandle(NULL), fName(NULL), fMode(kDynamic) {}
309     /** dlopen handle */
310     void* fHandle;                                                 //! transient
311     /** name of the library, casted to TString* before use */
312     void* fName;                                                   //! transient
313     /** library mode: kStatic means never unloaded */
314     TLibraryMode fMode;                                            //! transient
315   };
316 private:
317   /**
318    * Find a specific library among the loaded libraries.
319    * @param library     library name/path
320    * @return pointer to AliHLTLibHandle
321    */
322   AliHLTLibHandle* FindLibrary(const char* library);
323
324   /**
325    * Unload a component shared library.
326    * All components will be de-registered when the last instance of the
327    * library was unloaded.
328    * @param handle       handle to the library to unload
329    * @return 0 if succeeded, neg. error code if failed
330    */
331   int UnloadLibrary(AliHLTComponentHandler::AliHLTLibHandle &handle);
332
333   /** list of registered components */
334   vector<AliHLTComponent*> fComponentList;                         // see above 
335   /** list of scheduled components */
336   vector<AliHLTComponent*> fScheduleList;                          // see above 
337   /** list of libraries */
338   vector<AliHLTLibHandle> fLibraryList;                            // see above 
339   /** running environment for the component */
340   AliHLTAnalysisEnvironment fEnvironment;                         // see above 
341   /** list of owned components, deleted at termination of the handler */
342   vector<AliHLTComponent*> fOwnedComponents;                       // see above 
343   /** library mode effects all loaded libraries until a new mode is set */
344   TLibraryMode fLibraryMode;                                       // see above 
345
346   /** run descriptor */
347   AliHLTRunDesc fRunDesc;                                          //!transient 
348   /** run type string */
349   char* fRunType;                                                  //!transient 
350
351   /** the global singleton */
352   static AliHLTComponentHandler* fgpInstance;                      //!transient
353   /** number of used instances of the global singleton */
354   static int fgNofInstances;                                       //!transient 
355
356   ClassDef(AliHLTComponentHandler, 2);
357
358 };
359 #endif
360