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