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