HLT/BASE/AliHLTComponentHandler.h

   1 //-*- Mode: C++ -*-
   2 // @(#) $Id$
   3
   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                               */
   8
   9 /** @file   AliHLTComponentHandler.h
  10     @author Matthias Richter, Timm Steinbeck
  11     @date
  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.
  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 <vector>
  24 //#include "TObject.h"
  25 #include "AliHLTDataTypes.h"
  26 #include "AliHLTLogging.h"
  27
  28 class AliHLTComponent;
  29 class AliHLTModuleAgent;
  30 struct AliHLTAnalysisEnvironment;
  31 struct AliHLTComponentDataType;
  32
  33 /**
  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
  38  */
  39 class AliHLTComponentHandler : public AliHLTLogging {
  40  public:
  41   /** standard constructor */
  42   AliHLTComponentHandler();
  43   /** constructor */
  44   AliHLTComponentHandler(AliHLTAnalysisEnvironment* pEnv);
  45   /** destructor */
  46   virtual ~AliHLTComponentHandler();
  47
  48   /**
  49    * Create an instance from the global sigleton.
  50    * Instance has to be destroyed by the Destroy function
  51    */
  52   static AliHLTComponentHandler* CreateHandler();
  53
  54   /**
  55    * Destroy an instance of the global singleton retrieved by
  56    * AliHLTComponentHandler::CreateHandler()
  57    */
  58   int Destroy();
  59
  60   /**
  61    * Library mode.
  62    * - kDynamic: library can be unloaded (unload forced at termination of the
  63    *             handler
  64    * - kStatic:  library persistent, once loaded it stays
  65    */
  66   enum TLibraryMode {kDynamic, kStatic};
  67
  68   /**
  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
  74    * @return none
  75    */
  76   void SetEnvironment(AliHLTAnalysisEnvironment* pEnv);
  77
  78   /**
  79    * Get the current environment.
  80    */
  81   const AliHLTAnalysisEnvironment* GetEnvironment() const {return &fEnvironment;}
  82
  83   /**
  84    * Set library mode.
  85    * The mode effects all loaded libraries until another mode is set.
  86    * @param mode             persistent library or not
  87    * @return previous mode
  88    */
  89   TLibraryMode SetLibraryMode(TLibraryMode mode);
  90
  91   /**
  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
 102    */
 103   int LoadLibrary( const char* libraryPath, int bActivateAgents=1);
 104
 105   /**
 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
 110    */
 111   void (*FindSymbol(const char* library, const char* symbol))();
 112
 113   /**
 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
 119    */
 120   int UnloadLibrary( const char* libraryPath );
 121
 122   /**
 123    * Schedule a component for registration.
 124    * Full registration will be done after successfull loading of the shared
 125    * library.
 126    * @param pSample  a sample object of the component
 127    * @return neg. error code if failed
 128    */
 129   int ScheduleRegister(AliHLTComponent* pSample );
 130
 131   /**
 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
 138    */
 139   int RegisterComponent(AliHLTComponent* pSample);
 140
 141   /**
 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
 147    */
 148   int AddComponent(AliHLTComponent* pSample);
 149
 150   /**
 151    * Registers all scheduled components.
 152    */
 153   int RegisterScheduledComponents();
 154
 155   /**
 156    * Deregister a component.
 157    * @param componentID   ID of the component
 158    * @return neg. error code if failed
 159    */
 160   int DeregisterComponent( const char* componentID );
 161
 162   /**
 163    * Add standard components
 164    * The standard components are part of the libHLTbase library and
 165    * need therefore a special handling.
 166    */
 167   int AddStandardComponents();
 168
 169   /**
 170    */
 171   int DeleteOwnedComponents();
 172
 173   /**
 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
 179    */
 180   //const char* FindComponentType( AliHLTComponentDataType dtype,
 181   //                               const char* prevType = NULL )
 182   //  { return NULL;}
 183
 184   /**
 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
 200    */
 201   int CreateComponent( const char* componentID, void* pEnvParam,
 202                        int argc, const char** argv, AliHLTComponent*& component);
 203
 204   /**
 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
 208    */
 209   int CreateComponent(const char* componentID, AliHLTComponent*& component );
 210
 211   /**
 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
 218    */
 219   int CreateComponent( const char* componentID, void* pEnvParam,
 220                        AliHLTComponent*& component )
 221     {
 222     return CreateComponent( componentID, pEnvParam, 0, NULL, component );
 223     }
 224
 225   /**
 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().
 230    *
 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
 234    */
 235   int SetRunDescription(const AliHLTRunDesc* desc, const char* runType);
 236
 237   /**
 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
 243    */
 244   int HasOutputData( const char* componentID);
 245
 246   /**
 247    * Print registered components to stdout.
 248    * @return none
 249    */
 250   void List();
 251
 252   /**
 253    * Announce version and compilation info of the base library.
 254    */
 255   int AnnounceVersion();
 256
 257   /**
 258    * Find a component.
 259    * @param componentID  ID of the component to find
 260    * @return index, neg. error code if failed
 261    */
 262   int FindComponentIndex(const char* componentID);
 263
 264  protected:
 265
 266  private:
 267   /** copy constructor prohibited */
 268   AliHLTComponentHandler(const AliHLTComponentHandler&);
 269   /** assignment operator prohibited */
 270   AliHLTComponentHandler& operator=(const AliHLTComponentHandler&);
 271
 272   /**
 273    * Find a component.
 274    * @param componentID  ID of the component to find
 275    * @return descriptor
 276    */
 277   AliHLTComponent* FindComponent(const char* componentID);
 278
 279   /**
 280    * Insert component to the list
 281    * @param pSample      sample object of the component
 282    * @return neg. error code if failed
 283    */
 284   int InsertComponent(AliHLTComponent* pSample);
 285
 286   /**
 287    * Close all libraries.
 288    * @return neg. error code if failed
 289    */
 290   int UnloadLibraries();
 291
 292   /**
 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
 298    *
 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
 305    */
 306   int ActivateAgents(const char* library=NULL, const char* blackList=NULL);
 307
 308   /**
 309    * Compound descriptor for component libraries
 310    */
 311   struct AliHLTLibHandle {
 312     AliHLTLibHandle() : fHandle(NULL), fName(NULL), fMode(kDynamic) {}
 313     /** dlopen handle */
 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
 319   };
 320
 321   /**
 322    * Find a specific library among the loaded libraries.
 323    * @param library     library name/path
 324    * @return pointer to AliHLTLibHandle
 325    */
 326   AliHLTLibHandle* FindLibrary(const char* library);
 327
 328   /**
 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
 334    */
 335   int UnloadLibrary(AliHLTComponentHandler::AliHLTLibHandle &handle);
 336
 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
 349
 350   /** run descriptor */
 351   AliHLTRunDesc fRunDesc;                                          //!transient
 352   /** run type string */
 353   char* fRunType;                                                  //!transient
 354
 355   /** the global singleton */
 356   static AliHLTComponentHandler* fgpInstance;                      //!transient
 357   /** number of used instances of the global singleton */
 358   static int fgNofInstances;                                       //!transient
 359
 360   ClassDef(AliHLTComponentHandler, 2);
 361
 362 };
 363 #endif
 364