4 #ifndef ALIHLTCOMPONENTHANDLER_H
5 #define ALIHLTCOMPONENTHANDLER_H
6 /* Copyright(c) 1998-1999, ALICE Experiment at CERN, All rights reserved. *
7 * See cxx source for full Copyright notice */
9 /** @file AliHLTComponentHandler.h
10 @author Matthias Richter, Timm Steinbeck
12 @brief Global handling of HLT processing components
13 @note The handler is part of the interface and both used in the
14 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 AliHLTComponentEnvironment;
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(AliHLTComponentEnvironment* pEnv);
46 virtual ~AliHLTComponentHandler();
50 * - kDynamic: library can be unloaded (unload forced at termination of the
52 * - kStatic: library persistent, once loaded it stays
54 enum TLibraryMode {kDynamic, kStatic};
57 * Set the environment for the HLT framework.
58 * The environment mainly consists of function pointers for the integration
59 * of the HLT framework into a system like the PubSub online system or
60 * AliRoot offline system.
61 * @param pEnv pointer to @ref AliHLTComponentEnvironment structure
64 void SetEnvironment(AliHLTComponentEnvironment* pEnv);
68 * The mode effects all loaded libraries until another mode is set.
69 * @param mode persistent library or not
70 * @return previous mode
72 TLibraryMode SetLibraryMode(TLibraryMode mode);
75 * Load a component shared library.
76 * The component library needs to be loaded from the ComponentHanler in order
77 * to automatically register all components in the library.
78 * Registration is done by passing a sample object of the component to the
79 * handler. The object has to be valid during the whole runtime and should
80 * thus be a global object which is ONLY used for the purpose of registration.
81 * This also ensures automatically registration at library load time.
82 * @param libraryPath const char string containing the library name/path
83 * @param bActivateAgents activate agents after loading (@ref ActivateAgents)
84 * @return 0 if succeeded, neg. error code if failed
86 int LoadLibrary( const char* libraryPath, int bActivateAgents=1);
89 * Find a symbol in a dynamically loaded library.
90 * @param library library
91 * @param symbol the symbol to find
92 * @return void pointer to function
94 void* FindSymbol(const char* library, const char* symbol);
97 * Unload a component shared library.
98 * All components will be de-registered when the last instance of the
99 * library was unloaded.
100 * @param libraryPath library name as specified to @ref LoadLibrary
101 * @return 0 if succeeded, neg. error code if failed
103 int UnloadLibrary( const char* libraryPath );
106 * Schedule a component for registration.
107 * Full registration will be done after successfull loading of the shared
109 * @param pSample a sample object of the component
110 * @return neg. error code if failed
112 int ScheduleRegister(AliHLTComponent* pSample );
115 * Register a component.
116 * Registration is done by passing a sample object of the component to the
117 * handler. The object has to be valid during the whole runtime and should
118 * thus be a global object which is ONLY used for the purpose of registration.
119 * @param pSample a sample object of the component
120 * @return neg. error code if failed
122 int RegisterComponent(AliHLTComponent* pSample);
125 * Add a component and leave control of the sample object to the handler.
126 * Exactly the same functionality as @ref RegisterComponent but deletes
127 * the sample object at clean-up of the handler.
128 * @param pSample a sample object of the component
129 * @return neg. error code if failed
131 int AddComponent(AliHLTComponent* pSample);
134 * Registers all scheduled components.
136 int RegisterScheduledComponents();
139 * Deregister a component.
140 * @param componentID ID of the component
141 * @return neg. error code if failed
143 int DeregisterComponent( const char* componentID );
146 * Add standard components
147 * The standard components are part of the libHLTbase library and
148 * need therefore a special handling.
150 int AddStandardComponents();
154 int DeleteOwnedComponents();
157 * Find the ID of a component with the given output data.
158 * @param dtype data type descriptor
159 * @param prevType can be used to iterate if there are multiple components
160 * with the same output data type.
161 * @return component id
163 //const char* FindComponentType( AliHLTComponentDataType dtype,
164 // const char* prevType = NULL )
168 * Create a component of the given name (ID).
169 * The method tries to find a registerd component of id \em componentID and
170 * calls the \em Spawn method of the template component. After successful
171 * creation of a new object, the Init method is called in order to initialize
172 * the environment and the component arguments. <br>
173 * The environment is the same for all components, but each component can
174 * have an additional private parameter \em pEnvParam.<br>
175 * The component arguments consist of an array of strings and the array size
176 * in the usual manner of the main() function.
177 * @param componentID ID of the component to create
178 * @param pEnvParam environment parameter for the component
179 * @param argc number of arguments in argv
180 * @param argv argument array like in main()
181 * @param component reference to receive the create component instance
182 * @return component pointer in component, neg. error code if failed
184 int CreateComponent( const char* componentID, void* pEnvParam,
185 int argc, const char** argv, AliHLTComponent*& component );
188 * Create a component of the given name (ID).
189 * Introduced for backward compatibility.
190 * @param componentID ID of the component to create
191 * @param pEnvParam environment parameter for the component
192 * @param component reference to receive the create component instance
193 * @return component pointer in component, neg. error code if failed
195 int CreateComponent( const char* componentID, void* pEnvParam,
196 AliHLTComponent*& component )
198 return CreateComponent( componentID, pEnvParam, 0, NULL, component );
202 * Check if a registered component has output data, e.g. is of type
203 * kSource or kProcessor (see @ref AliHLTComponent::TComponentType).
204 * @param componentID ID of the component to create
205 * @return 1 if component has output data, 0 if not <br>
206 * -ENOENT if component does not exist
208 int HasOutputData( const char* componentID);
211 * Print registered components to stdout.
217 * Announce version and compilation info of the base library.
219 int AnnounceVersion();
223 * @param componentID ID of the component to find
224 * @return index, neg. error code if failed
226 int FindComponentIndex(const char* componentID);
231 /** copy constructor prohibited */
232 AliHLTComponentHandler(const AliHLTComponentHandler&);
233 /** assignment operator prohibited */
234 AliHLTComponentHandler& operator=(const AliHLTComponentHandler&);
238 * @param componentID ID of the component to find
241 AliHLTComponent* FindComponent(const char* componentID);
244 * Insert component to the list
245 * @param pSample sample object of the component
246 * @return neg. error code if failed
248 int InsertComponent(AliHLTComponent* pSample);
251 * Close all libraries.
252 * @return neg. error code if failed
254 int UnloadLibraries();
257 * Activate all module agents with this component handler.
258 * The function loops over all available module agents and activates
259 * each agent with this component handler. During activation, the
260 * dynamic component registration is carried out by the agents version
261 * of @ref AliHLTModuleAgent::RegisterComponents
262 * @param blackList array of agents which should be excluded
263 * @param size array size
265 int ActivateAgents(const AliHLTModuleAgent** blackList=NULL, int size=0);
268 * Compound descriptor for component libraries
270 struct AliHLTLibHandle {
271 AliHLTLibHandle() : fHandle(NULL), fName(NULL), fMode(kDynamic) {}
273 void* fHandle; //! transient
274 /** name of the library, casted to TString* before use */
275 void* fName; //! transient
276 /** library mode: kStatic means never unloaded */
277 TLibraryMode fMode; //! transient
281 * Find a specific library among the loaded libraries.
282 * @param library library name/path
283 * @return pointer to AliHLTLibHandle
285 AliHLTLibHandle* FindLibrary(const char* library);
288 * Unload a component shared library.
289 * All components will be de-registered when the last instance of the
290 * library was unloaded.
291 * @param handle handle to the library to unload
292 * @return 0 if succeeded, neg. error code if failed
294 int UnloadLibrary(AliHLTComponentHandler::AliHLTLibHandle &handle);
296 /** list of registered components */
297 vector<AliHLTComponent*> fComponentList; // see above
298 /** list of scheduled components */
299 vector<AliHLTComponent*> fScheduleList; // see above
300 /** list of libraries */
301 vector<AliHLTLibHandle> fLibraryList; // see above
302 /** running environment for the component */
303 AliHLTComponentEnvironment fEnvironment; // see above
304 /** list of owned components, deleted at termination of the handler */
305 vector<AliHLTComponent*> fOwnedComponents; // see above
306 /** library mode effects all loaded libraries until a new mode is set */
307 TLibraryMode fLibraryMode; // see above
309 ClassDef(AliHLTComponentHandler, 0);