Line data Source code
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 0 : 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 0 : 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 : /**
304 : * Loop through all the agents and deregister this instance if neccessary.
305 : */
306 :
307 : int DeactivateAgents() const;
308 :
309 : public:
310 : /**
311 : * Compound descriptor for component libraries - must be public
312 : */
313 : struct AliHLTLibHandle {
314 156 : AliHLTLibHandle() : fHandle(NULL), fName(NULL), fMode(kDynamic) {}
315 : /** dlopen handle */
316 : void* fHandle; //! transient
317 : /** name of the library, casted to TString* before use */
318 : void* fName; //! transient
319 : /** library mode: kStatic means never unloaded */
320 : TLibraryMode fMode; //! transient
321 : };
322 : private:
323 : /**
324 : * Find a specific library among the loaded libraries.
325 : * @param library library name/path
326 : * @return pointer to AliHLTLibHandle
327 : */
328 : AliHLTLibHandle* FindLibrary(const char* library);
329 :
330 : /**
331 : * Unload a component shared library.
332 : * All components will be de-registered when the last instance of the
333 : * library was unloaded.
334 : * @param handle handle to the library to unload
335 : * @return 0 if succeeded, neg. error code if failed
336 : */
337 : int UnloadLibrary(AliHLTComponentHandler::AliHLTLibHandle &handle);
338 :
339 : /** list of registered components */
340 : vector<AliHLTComponent*> fComponentList; // see above
341 : /** list of scheduled components */
342 : vector<AliHLTComponent*> fScheduleList; // see above
343 : /** list of libraries */
344 : vector<AliHLTLibHandle> fLibraryList; // see above
345 : /** running environment for the component */
346 : AliHLTAnalysisEnvironment fEnvironment; // see above
347 : /** list of owned components, deleted at termination of the handler */
348 : vector<AliHLTComponent*> fOwnedComponents; // see above
349 : /** library mode effects all loaded libraries until a new mode is set */
350 : TLibraryMode fLibraryMode; // see above
351 :
352 : /** run descriptor */
353 : AliHLTRunDesc fRunDesc; //!transient
354 : /** run type string */
355 : char* fRunType; //!transient
356 :
357 : /** the global singleton */
358 : static AliHLTComponentHandler* fgpInstance; //!transient
359 : /** number of used instances of the global singleton */
360 : static int fgNofInstances; //!transient
361 :
362 126 : ClassDef(AliHLTComponentHandler, 2);
363 :
364 : };
365 : #endif
366 :
|
