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