HLT/BASE/AliHLTComponentHandler.h

   1 // @(#) $Id$
   2
   3 #ifndef ALIHLTCOMPONENTHANDLER_H
   4 #define ALIHLTCOMPONENTHANDLER_H
   5 /* Copyright(c) 1998-1999, ALICE Experiment at CERN, All rights reserved. *
   6  * See cxx source for full Copyright notice                               */
   7
   8 /** @file   AliHLTComponentHandler.h
   9     @author Matthias Richter, Timm Steinbeck
  10     @date
  11     @brief  Global handling of HLT processing components
  12     @note   The handler is part of the interface and both used in the
  13             Online (PubSub) and Offline (AliRoot) context.
  14                                                                           */
  15
  16
  17 #include <vector>
  18 //#include "TObject.h"
  19 #include "AliHLTDataTypes.h"
  20 #include "AliHLTLogging.h"
  21
  22 class AliHLTComponent;
  23 struct AliHLTComponentEnvironment;
  24 struct AliHLTComponentDataType;
  25
  26 /**
  27  * @class AliHLTComponentHandler
  28  * The component handler controls all the processing components available in
  29  * the system. It also controls the component shared libraries.
  30  * @ingroup alihlt_component
  31  */
  32 class AliHLTComponentHandler : public AliHLTLogging {
  33  public:
  34   /** standard constructor */
  35   AliHLTComponentHandler();
  36   /** constructor */
  37   AliHLTComponentHandler(AliHLTComponentEnvironment* pEnv);
  38   /** not a valid copy constructor, defined according to effective C++ style */
  39   AliHLTComponentHandler(const AliHLTComponentHandler&);
  40   /** not a valid assignment op, but defined according to effective C++ style */
  41   AliHLTComponentHandler& operator=(const AliHLTComponentHandler&);
  42   /** destructor */
  43   virtual ~AliHLTComponentHandler();
  44
  45   /**
  46    * Set the environment for the HLT framework.
  47    * The environment mainly consists of function pointers for the integration
  48    * of the HLT framework into a system like the PubSub online system or
  49    * AliRoot offline system.
  50    * @param pEnv    pointer to @ref AliHLTComponentEnvironment structure
  51    * @return none
  52    */
  53   void SetEnvironment(AliHLTComponentEnvironment* pEnv);
  54
  55   /**
  56    * Load a component shared library.
  57    * The component library needs to be loaded from the ComponentHanler in order
  58    * to automatically register all components in the library.
  59    * Registration is done by passing a sample object of the component to the
  60    * handler. The object has to be valid during the whole runtime and should
  61    * thus be a global object which is ONLY used for the purpose of registration.
  62    * This also ensures automatically registration at library load time.
  63    * @param libraryPath  const char string containing the library name/path
  64    * @return 0 if succeeded, neg. error code if failed
  65    */
  66   int LoadLibrary( const char* libraryPath );
  67
  68   /**
  69    * Find a symbol in a dynamically loaded library.
  70    * @param library      library
  71    * @param symbol       the symbol to find
  72    * @return void pointer to function
  73    */
  74   void* FindSymbol(const char* library, const char* symbol);
  75
  76   /**
  77    * Unload a component shared library.
  78    * All components will be de-registered when the last instance of the
  79    * library was unloaded.
  80    * @param libraryPath  library name as specified to @ref LoadLibrary
  81    * @return 0 if succeeded, neg. error code if failed
  82    */
  83   int UnloadLibrary( const char* libraryPath );
  84
  85   /**
  86    * Schedule a component for registration.
  87    * Full registration will be done after successfull loading of the shared
  88    * library.
  89    * @param pSample  a sample object of the component
  90    * @return neg. error code if failed
  91    */
  92   int ScheduleRegister(AliHLTComponent* pSample );
  93
  94   /**
  95    * Register a component.
  96    * Registration is done by passing a sample object of the component to the
  97    * handler. The object has to be valid during the whole runtime and should
  98    * thus be a global object which is ONLY used for the purpose of registration.
  99    * @param pSample  a sample object of the component
 100    * @return neg. error code if failed
 101    */
 102   int RegisterComponent(AliHLTComponent* pSample );
 103
 104   /**
 105    * Registers all scheduled components.
 106    */
 107   int RegisterScheduledComponents();
 108
 109   /**
 110    * Deregister a component.
 111    * @param componentID   ID of the component
 112    * @return neg. error code if failed
 113    */
 114   int DeregisterComponent( const char* componentID );
 115
 116   /**
 117    * Add standard components
 118    * The standard components are part of the libHLTbase library and
 119    * need therefore a special handling.
 120    */
 121   int AddStandardComponents();
 122
 123   /**
 124    */
 125   int DeleteStandardComponents();
 126
 127   /**
 128    * Find the ID of a component with the given output data.
 129    * @param dtype     data type descriptor
 130    * @param prevType  can be used to iterate if there are multiple components
 131    *                  with the same output data type.
 132    * @return component id
 133    */
 134   //const char* FindComponentType( AliHLTComponentDataType dtype,
 135   //                               const char* prevType = NULL )
 136   //  { return NULL;}
 137
 138   /**
 139    * Create a component of the given name (ID).
 140    * The method tries to find a registerd component of id \em componentID and
 141    * calls the \em Spawn method of the template component. After successful
 142    * creation of a new object, the Init method is called in order to initialize
 143    * the environment and the component arguments. <br>
 144    * The environment is the same for all components, but each component can
 145    * have an additional private parameter \em pEnvParam.<br>
 146    * The component arguments consist of an array of strings and the array size
 147    * in the usual manner of the main() function.
 148    * @param componentID  ID of the component to create
 149    * @param pEnvParam    environment parameter for the component
 150    * @param argc         number of arguments in argv
 151    * @param argv         argument array like in main()
 152    * @param component    reference to receive the create component instance
 153    * @return component pointer in component, neg. error code if failed
 154    */
 155   int CreateComponent( const char* componentID, void* pEnvParam,
 156                        int argc, const char** argv, AliHLTComponent*& component );
 157
 158   /**
 159    * Create a component of the given name (ID).
 160    * Introduced for backward compatibility.
 161    * @param componentID  ID of the component to create
 162    * @param pEnvParam    environment parameter for the component
 163    * @param component    reference to receive the create component instance
 164    * @return component pointer in component, neg. error code if failed
 165    */
 166   int CreateComponent( const char* componentID, void* pEnvParam,
 167                        AliHLTComponent*& component )
 168     {
 169     return CreateComponent( componentID, pEnvParam, 0, NULL, component );
 170     }
 171
 172   /**
 173    * Print registered components to stdout.
 174    * @return none
 175    */
 176   void List();
 177
 178   /**
 179    * Announce version and compilation info of the base library.
 180    */
 181   int AnnounceVersion();
 182
 183  protected:
 184
 185  private:
 186   /**
 187    * Find a component.
 188    * @param componentID  ID of the component to find
 189    * @return index, neg. error code if failed
 190    */
 191   int FindComponentIndex(const char* componentID);
 192
 193   /**
 194    * Find a component.
 195    * @param componentID  ID of the component to find
 196    * @return descriptor
 197    */
 198   AliHLTComponent* FindComponent(const char* componentID);
 199
 200   /**
 201    * Insert component to the list
 202    * @param pSample      sample object of the component
 203    * @return neg. error code if failed
 204    */
 205   int InsertComponent(AliHLTComponent* pSample);
 206
 207   /**
 208    * Close all libraries.
 209    * @return neg. error code if failed
 210    */
 211   int UnloadLibraries();
 212
 213   /**
 214    * Compount descriptor for component libraries
 215    */
 216   struct AliHLTLibHandle {
 217     AliHLTLibHandle() : fHandle(NULL), fName(NULL) {}
 218     /** dlopen handle */
 219     void* fHandle;                                                 //! transient
 220     /** name of the library, casted to TString* before use */
 221     void* fName;                                                   //! transient
 222   };
 223
 224   /**
 225    * Find a specific library among the loaded libraries.
 226    * @param library     library name/path
 227    * @return pointer to AliHLTLibHandle
 228    */
 229   AliHLTLibHandle* FindLibrary(const char* library);
 230
 231   /**
 232    * Unload a component shared library.
 233    * All components will be de-registered when the last instance of the
 234    * library was unloaded.
 235    * @param handle       handle to the library to unload
 236    * @return 0 if succeeded, neg. error code if failed
 237    */
 238   int UnloadLibrary(AliHLTComponentHandler::AliHLTLibHandle &handle);
 239
 240   /** list of registered components */
 241   vector<AliHLTComponent*> fComponentList;                         // see above
 242   /** list of scheduled components */
 243   vector<AliHLTComponent*> fScheduleList;                          // see above
 244   /** list of libraries */
 245   vector<AliHLTLibHandle> fLibraryList;                            // see above
 246   /** running environment for the component */
 247   AliHLTComponentEnvironment fEnvironment;                         // see above
 248   /** list of standard components */
 249   vector<AliHLTComponent*> fStandardList;                          // see above
 250
 251   ClassDef(AliHLTComponentHandler, 0);
 252
 253 };
 254 #endif
 255