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 AliHLTComponentEnvironment;
  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(AliHLTComponentEnvironment* pEnv);
  45   /** destructor */
  46   virtual ~AliHLTComponentHandler();
  47
  48   /**
  49    * Library mode.
  50    * - kDynamic: library can be unloaded (unload forced at termination of the
  51    *             handler
  52    * - kStatic:  library persistent, once loaded it stays
  53    */
  54   enum TLibraryMode {kDynamic, kStatic};
  55
  56   /**
  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
  62    * @return none
  63    */
  64   void SetEnvironment(AliHLTComponentEnvironment* pEnv);
  65
  66   /**
  67    * Set library mode.
  68    * The mode effects all loaded libraries until another mode is set.
  69    * @param mode             persistent library or not
  70    * @return previous mode
  71    */
  72   TLibraryMode SetLibraryMode(TLibraryMode mode);
  73
  74   /**
  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
  85    */
  86   int LoadLibrary( const char* libraryPath, int bActivateAgents=1);
  87
  88   /**
  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
  93    */
  94   void* FindSymbol(const char* library, const char* symbol);
  95
  96   /**
  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
 102    */
 103   int UnloadLibrary( const char* libraryPath );
 104
 105   /**
 106    * Schedule a component for registration.
 107    * Full registration will be done after successfull loading of the shared
 108    * library.
 109    * @param pSample  a sample object of the component
 110    * @return neg. error code if failed
 111    */
 112   int ScheduleRegister(AliHLTComponent* pSample );
 113
 114   /**
 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
 121    */
 122   int RegisterComponent(AliHLTComponent* pSample);
 123
 124   /**
 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
 130    */
 131   int AddComponent(AliHLTComponent* pSample);
 132
 133   /**
 134    * Registers all scheduled components.
 135    */
 136   int RegisterScheduledComponents();
 137
 138   /**
 139    * Deregister a component.
 140    * @param componentID   ID of the component
 141    * @return neg. error code if failed
 142    */
 143   int DeregisterComponent( const char* componentID );
 144
 145   /**
 146    * Add standard components
 147    * The standard components are part of the libHLTbase library and
 148    * need therefore a special handling.
 149    */
 150   int AddStandardComponents();
 151
 152   /**
 153    */
 154   int DeleteOwnedComponents();
 155
 156   /**
 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
 162    */
 163   //const char* FindComponentType( AliHLTComponentDataType dtype,
 164   //                               const char* prevType = NULL )
 165   //  { return NULL;}
 166
 167   /**
 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    * @param cdbPath      optional CDB path
 183    * @return component pointer in component, neg. error code if failed
 184    */
 185   int CreateComponent( const char* componentID, void* pEnvParam,
 186                        int argc, const char** argv, AliHLTComponent*& component,
 187                        const char* cdbPath=NULL);
 188
 189   /**
 190    * Create a component of the given name (ID).
 191    * Introduced for backward compatibility.
 192    * @param componentID  ID of the component to create
 193    * @param pEnvParam    environment parameter for the component
 194    * @param component    reference to receive the create component instance
 195    * @return component pointer in component, neg. error code if failed
 196    */
 197   int CreateComponent( const char* componentID, void* pEnvParam,
 198                        AliHLTComponent*& component )
 199     {
 200     return CreateComponent( componentID, pEnvParam, 0, NULL, component );
 201     }
 202
 203   /**
 204    * Check if a registered component has output data, e.g. is of type
 205    * kSource or kProcessor (see @ref AliHLTComponent::TComponentType).
 206    * @param componentID  ID of the component to create
 207    * @return 1 if component has output data, 0 if not                 <br>
 208    *         -ENOENT     if component does not exist
 209    */
 210   int HasOutputData( const char* componentID);
 211
 212   /**
 213    * Print registered components to stdout.
 214    * @return none
 215    */
 216   void List();
 217
 218   /**
 219    * Announce version and compilation info of the base library.
 220    */
 221   int AnnounceVersion();
 222
 223   /**
 224    * Find a component.
 225    * @param componentID  ID of the component to find
 226    * @return index, neg. error code if failed
 227    */
 228   int FindComponentIndex(const char* componentID);
 229
 230  protected:
 231
 232  private:
 233   /** copy constructor prohibited */
 234   AliHLTComponentHandler(const AliHLTComponentHandler&);
 235   /** assignment operator prohibited */
 236   AliHLTComponentHandler& operator=(const AliHLTComponentHandler&);
 237
 238   /**
 239    * Find a component.
 240    * @param componentID  ID of the component to find
 241    * @return descriptor
 242    */
 243   AliHLTComponent* FindComponent(const char* componentID);
 244
 245   /**
 246    * Insert component to the list
 247    * @param pSample      sample object of the component
 248    * @return neg. error code if failed
 249    */
 250   int InsertComponent(AliHLTComponent* pSample);
 251
 252   /**
 253    * Close all libraries.
 254    * @return neg. error code if failed
 255    */
 256   int UnloadLibraries();
 257
 258   /**
 259    * Activate all module agents with this component handler.
 260    * The function loops over all available module agents and activates
 261    * each agent with this component handler. During activation, the
 262    * dynamic component registration is carried out by the agents version
 263    * of @ref AliHLTModuleAgent::RegisterComponents
 264    * @param blackList     array of agents which should be excluded
 265    * @param size          array size
 266    */
 267   int ActivateAgents(const AliHLTModuleAgent** blackList=NULL, int size=0);
 268
 269   /**
 270    * Compound descriptor for component libraries
 271    */
 272   struct AliHLTLibHandle {
 273     AliHLTLibHandle() : fHandle(NULL), fName(NULL), fMode(kDynamic) {}
 274     /** dlopen handle */
 275     void* fHandle;                                                 //! transient
 276     /** name of the library, casted to TString* before use */
 277     void* fName;                                                   //! transient
 278     /** library mode: kStatic means never unloaded */
 279     TLibraryMode fMode;                                            //! transient
 280   };
 281
 282   /**
 283    * Find a specific library among the loaded libraries.
 284    * @param library     library name/path
 285    * @return pointer to AliHLTLibHandle
 286    */
 287   AliHLTLibHandle* FindLibrary(const char* library);
 288
 289   /**
 290    * Unload a component shared library.
 291    * All components will be de-registered when the last instance of the
 292    * library was unloaded.
 293    * @param handle       handle to the library to unload
 294    * @return 0 if succeeded, neg. error code if failed
 295    */
 296   int UnloadLibrary(AliHLTComponentHandler::AliHLTLibHandle &handle);
 297
 298   /** list of registered components */
 299   vector<AliHLTComponent*> fComponentList;                         // see above
 300   /** list of scheduled components */
 301   vector<AliHLTComponent*> fScheduleList;                          // see above
 302   /** list of libraries */
 303   vector<AliHLTLibHandle> fLibraryList;                            // see above
 304   /** running environment for the component */
 305   AliHLTComponentEnvironment fEnvironment;                         // see above
 306   /** list of owned components, deleted at termination of the handler */
 307   vector<AliHLTComponent*> fOwnedComponents;                       // see above
 308   /** library mode effects all loaded libraries until a new mode is set */
 309   TLibraryMode fLibraryMode;                                       // see above
 310
 311   ClassDef(AliHLTComponentHandler, 0);
 312
 313 };
 314 #endif
 315