4 #ifndef ALIHLTCOMPONENTHANDLER_H
5 #define ALIHLTCOMPONENTHANDLER_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 *
10 /// @file AliHLTComponentHandler.h
11 /// @author Matthias Richter, Timm Steinbeck
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.
17 // see below for class documentation
19 // refer to README to build package
21 // visit http://web.ift.uib.no/~kjeks/doc/alice-hlt
24 //#include "TObject.h"
25 #include "AliHLTDataTypes.h"
26 #include "AliHLTLogging.h"
28 class AliHLTComponent;
29 class AliHLTModuleAgent;
30 struct AliHLTAnalysisEnvironment;
31 struct AliHLTComponentDataType;
34 * @class AliHLTComponentHandler
35 * The component handler controls all the processing components available in
36 * the system. It also controls the component shared libraries.
37 * @ingroup alihlt_component
39 class AliHLTComponentHandler : public AliHLTLogging {
41 /** standard constructor */
42 AliHLTComponentHandler();
44 AliHLTComponentHandler(AliHLTAnalysisEnvironment* pEnv);
46 virtual ~AliHLTComponentHandler();
49 * Create an instance from the global sigleton.
50 * Instance has to be destroyed by the Destroy function
52 static AliHLTComponentHandler* CreateHandler();
55 * Destroy an instance of the global singleton retrieved by
56 * AliHLTComponentHandler::CreateHandler()
62 * - kDynamic: library can be unloaded (unload forced at termination of the
64 * - kStatic: library persistent, once loaded it stays
66 enum TLibraryMode {kDynamic, kStatic};
69 * Set the environment for the HLT framework.
70 * The environment mainly consists of function pointers for the integration
71 * of the HLT framework into a system like the PubSub online system or
72 * AliRoot offline system.
73 * @param pEnv pointer to @ref AliHLTAnalysisEnvironment structure
76 void SetEnvironment(AliHLTAnalysisEnvironment* pEnv);
79 * Get the current environment.
81 const AliHLTAnalysisEnvironment* GetEnvironment() const {return &fEnvironment;}
85 * The mode effects all loaded libraries until another mode is set.
86 * @param mode persistent library or not
87 * @return previous mode
89 TLibraryMode SetLibraryMode(TLibraryMode mode);
92 * Load a component shared library.
93 * The component library needs to be loaded from the ComponentHanler in order
94 * to automatically register all components in the library.
95 * Registration is done by passing a sample object of the component to the
96 * handler. The object has to be valid during the whole runtime and should
97 * thus be a global object which is ONLY used for the purpose of registration.
98 * This also ensures automatically registration at library load time.
99 * @param libraryPath const char string containing the library name/path
100 * @param bActivateAgents activate agents after loading (@ref ActivateAgents)
101 * @return 0 if succeeded, neg. error code if failed
103 int LoadLibrary( const char* libraryPath, int bActivateAgents=1);
106 * Find a symbol in a dynamically loaded library.
107 * @param library library
108 * @param symbol the symbol to find
109 * @return void pointer to function
111 AliHLTfctVoid FindSymbol(const char* library, const char* symbol);
114 * Unload a component shared library.
115 * All components will be de-registered when the last instance of the
116 * library was unloaded.
117 * @param libraryPath library name as specified to @ref LoadLibrary
118 * @return 0 if succeeded, neg. error code if failed
120 int UnloadLibrary( const char* libraryPath );
123 * Schedule a component for registration.
124 * Full registration will be done after successfull loading of the shared
126 * @param pSample a sample object of the component
127 * @return neg. error code if failed
129 int ScheduleRegister(AliHLTComponent* pSample );
132 * Register a component.
133 * Registration is done by passing a sample object of the component to the
134 * handler. The object has to be valid during the whole runtime and should
135 * thus be a global object which is ONLY used for the purpose of registration.
136 * @param pSample a sample object of the component
137 * @return neg. error code if failed
139 int RegisterComponent(AliHLTComponent* pSample);
142 * Add a component and leave control of the sample object to the handler.
143 * Exactly the same functionality as @ref RegisterComponent but deletes
144 * the sample object at clean-up of the handler.
145 * @param pSample a sample object of the component
146 * @return neg. error code if failed
148 int AddComponent(AliHLTComponent* pSample);
151 * Registers all scheduled components.
153 int RegisterScheduledComponents();
156 * Deregister a component.
157 * @param componentID ID of the component
158 * @return neg. error code if failed
160 int DeregisterComponent( const char* componentID );
163 * Add standard components
164 * The standard components are part of the libHLTbase library and
165 * need therefore a special handling.
167 int AddStandardComponents();
171 int DeleteOwnedComponents();
174 * Find the ID of a component with the given output data.
175 * @param dtype data type descriptor
176 * @param prevType can be used to iterate if there are multiple components
177 * with the same output data type.
178 * @return component id
180 //const char* FindComponentType( AliHLTComponentDataType dtype,
181 // const char* prevType = NULL )
185 * Create a component of the given name (ID).
186 * The method tries to find a registerd component of id \em componentID and
187 * calls the \em Spawn method of the template component. After successful
188 * creation of a new object, the Init method is called in order to initialize
189 * the environment and the component arguments. <br>
190 * The environment is the same for all components, but each component can
191 * have an additional private parameter \em pEnvParam.<br>
192 * The component arguments consist of an array of strings and the array size
193 * in the usual manner of the main() function.
194 * @param componentID ID of the component to create
195 * @param pEnvParam environment parameter for the component
196 * @param argc number of arguments in argv
197 * @param argv argument array like in main()
198 * @param component reference to receive the create component instance
199 * @return component pointer in component, neg. error code if failed
201 int CreateComponent( const char* componentID, void* pEnvParam,
202 int argc, const char** argv, AliHLTComponent*& component);
205 * Create component without initializing it.
206 * @param componentID ID of the component to create
207 * @param component reference to receive the create component instance
209 int CreateComponent(const char* componentID, AliHLTComponent*& component );
212 * Create a component of the given name (ID).
213 * Introduced for backward compatibility.
214 * @param componentID ID of the component to create
215 * @param pEnvParam environment parameter for the component
216 * @param component reference to receive the create component instance
217 * @return component pointer in component, neg. error code if failed
219 int CreateComponent( const char* componentID, void* pEnvParam,
220 AliHLTComponent*& component )
222 return CreateComponent( componentID, pEnvParam, 0, NULL, component );
226 * Set the run description.
227 * The run description is set globally for all components. Each component
228 * is initialized from the global run description after creation and before
229 * call of AliHLTComponent::Init().
231 * @param desc run descriptor, currently only the run no member is used
232 * @param runType originally, run type was supposed to be a number and part
233 * of the run descriptor. But it was defined as string later
235 int SetRunDescription(const AliHLTRunDesc* desc, const char* runType);
238 * Check if a registered component has output data, e.g. is of type
239 * kSource or kProcessor (see @ref AliHLTComponent::TComponentType).
240 * @param componentID ID of the component to create
241 * @return 1 if component has output data, 0 if not <br>
242 * -ENOENT if component does not exist
244 int HasOutputData( const char* componentID);
247 * Print registered components to stdout.
253 * Announce version and compilation info of the base library.
255 int AnnounceVersion();
259 * @param componentID ID of the component to find
260 * @return index, neg. error code if failed
262 int FindComponentIndex(const char* componentID);
267 /** copy constructor prohibited */
268 AliHLTComponentHandler(const AliHLTComponentHandler&);
269 /** assignment operator prohibited */
270 AliHLTComponentHandler& operator=(const AliHLTComponentHandler&);
274 * @param componentID ID of the component to find
277 AliHLTComponent* FindComponent(const char* componentID);
280 * Insert component to the list
281 * @param pSample sample object of the component
282 * @return neg. error code if failed
284 int InsertComponent(AliHLTComponent* pSample);
287 * Close all libraries.
288 * @return neg. error code if failed
290 int UnloadLibraries();
293 * Activate all module agents with this component handler.
294 * The function loops over all available module agents and activates
295 * each agent with this component handler. During activation, the
296 * dynamic component registration is carried out by the agents version
297 * of @ref AliHLTModuleAgent::RegisterComponents
299 * Agents are identified by an id which is a string containing the
300 * module name. Libraries follow the naming scheme libAliHLT<MOD>.so
301 * If the library name is provided and the specific agent found in the
302 * list, only that one is activated. All pending agents otherwize.
303 * @param library library to activate the agent for
304 * @param blackList blank separated list of module ids
306 int ActivateAgents(const char* library=NULL, const char* blackList=NULL);
309 * Compound descriptor for component libraries
311 struct AliHLTLibHandle {
312 AliHLTLibHandle() : fHandle(NULL), fName(NULL), fMode(kDynamic) {}
314 void* fHandle; //! transient
315 /** name of the library, casted to TString* before use */
316 void* fName; //! transient
317 /** library mode: kStatic means never unloaded */
318 TLibraryMode fMode; //! transient
322 * Find a specific library among the loaded libraries.
323 * @param library library name/path
324 * @return pointer to AliHLTLibHandle
326 AliHLTLibHandle* FindLibrary(const char* library);
329 * Unload a component shared library.
330 * All components will be de-registered when the last instance of the
331 * library was unloaded.
332 * @param handle handle to the library to unload
333 * @return 0 if succeeded, neg. error code if failed
335 int UnloadLibrary(AliHLTComponentHandler::AliHLTLibHandle &handle);
337 /** list of registered components */
338 vector<AliHLTComponent*> fComponentList; // see above
339 /** list of scheduled components */
340 vector<AliHLTComponent*> fScheduleList; // see above
341 /** list of libraries */
342 vector<AliHLTLibHandle> fLibraryList; // see above
343 /** running environment for the component */
344 AliHLTAnalysisEnvironment fEnvironment; // see above
345 /** list of owned components, deleted at termination of the handler */
346 vector<AliHLTComponent*> fOwnedComponents; // see above
347 /** library mode effects all loaded libraries until a new mode is set */
348 TLibraryMode fLibraryMode; // see above
350 /** run descriptor */
351 AliHLTRunDesc fRunDesc; //!transient
352 /** run type string */
353 char* fRunType; //!transient
355 /** the global singleton */
356 static AliHLTComponentHandler* fgpInstance; //!transient
357 /** number of used instances of the global singleton */
358 static int fgNofInstances; //!transient
360 ClassDef(AliHLTComponentHandler, 2);