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