- added version announcement to base library
[u/mrichter/AliRoot.git] / HLT / BASE / AliHLTComponentHandler.h
index 05e4d84f94783865dd437f153d67859d0cbe0679..638164d9adfffbbdfa9cb6e5b9986cba8fc78978 100644 (file)
@@ -24,76 +24,165 @@ struct AliHLTComponent_DataType;
 
 typedef void* AliHLTLibHandle;
 
+/**
+ * @class AliHLTComponentHandler
+ * The component handler controls all the processing components available in
+ * the system. It also controls the component shared libraries.
+ * @ingroup alihlt_component
+ */
 class AliHLTComponentHandler : public AliHLTLogging {
  public:
+  /** standard constructor */
   AliHLTComponentHandler();
+  /** destructor */
   virtual ~AliHLTComponentHandler();
 
+  /**
+   * Set the environment for the HLT framework.
+   * The environment mainly consists of function pointers for the integration
+   * of the HLT framework into a system like the PubSub online system or
+   * AliRoot offline system.
+   * @param pEnv    pointer to @ref AliHLTComponentEnvironment structure
+   * @return none
+   */
   void SetEnvironment(AliHLTComponentEnvironment* pEnv);
 
-  // Load a component shared library
+  /**
+   * Load a component shared library.
+   * The component library needs to be loaded from the ComponentHanler in order
+   * to automatically register all components in the library.
+   * Registration is done by passing a sample object of the component to the
+   * handler. The object has to be valid during the whole runtime and should
+   * thus be a global object which is ONLY used for the purpose of registration.
+   * This also ensures automatically registration at library load time.
+   * @param libraryPath  const char string containing the library name/path
+   * @return 0 if succeeded, neg. error code if failed
+   */
   int LoadLibrary( const char* libraryPath );
+
+  /**
+   * Unload a component shared library.
+   * All components will be de-registered.
+   * @param libraryPath  library name as specified to @ref LoadLibrary
+   * @return 0 if succeeded, neg. error code if failed
+   */
   int UnloadLibrary( const char* libraryPath );
 
-  /* Component registration funcions
-   * registration is done by passing a sample object of the component to the handler
-   * the object has to be valid during the whole runtime and should thus be a global object
+  /**
+   * Schedule a component for registration.
+   * Full registration will be done after successfull loading of the shared
+   * library.
+   * @param pSample  a sample object of the component
+   * @return neg. error code if failed
    */
-  // Schedule a component for registration, full registration will be done
-  // after successfull loading of the shared library
   int ScheduleRegister(AliHLTComponent* pSample );
 
-  // Register a component with the list of available components
+  /**
+   * Register a component.
+   * Registration is done by passing a sample object of the component to the
+   * handler. The object has to be valid during the whole runtime and should
+   * thus be a global object which is ONLY used for the purpose of registration.
+   * @param pSample  a sample object of the component
+   * @return neg. error code if failed
+   */
   int RegisterComponent(AliHLTComponent* pSample );
-  int DeregisterComponent( const char* componentID );
-
-  // Find the ID of a component with the given output data
-  // prevType can be used to iterate if there are multiple components with the same output data type.
-  const char* FindComponentType( AliHLTComponent_DataType, const char* prevType = NULL ) { return NULL;}
 
-  // Create a component of the given name
-  int CreateComponent( const char* componentType, void* environ_param, int argc, const char** argv, AliHLTComponent*& component );
-  int CreateComponent( const char* componentType, void* environ_param, AliHLTComponent*& component ) {
-    return CreateComponent( componentType, environ_param, 0, NULL, component );
-  }
+  /**
+   * Deregister a component.
+   * @param componentID   ID of the component
+   * @return neg. error code if failed
+   */
+  int DeregisterComponent( const char* componentID );
 
-  /* print registered components to stdout
+  /**
+   * Find the ID of a component with the given output data.
+   * @param dtype     data type descriptor
+   * @param prevType  can be used to iterate if there are multiple components
+   *                  with the same output data type.
+   * @return component id
+   */
+  //const char* FindComponentType( AliHLTComponent_DataType dtype,
+  //                               const char* prevType = NULL )
+  //  { return NULL;}
+
+  /**
+   * Create a component of the given name (ID).
+   * @param componentID  ID of the component to create
+   * @param pEnv         environment for the component
+   * @param argc         number of arguments in @ref argv
+   * @param argv         argument array like in main()
+   * @param component    reference to receive the create component instance
+   * @return component pointer in @ref component, neg. error code if failed
+   */
+  int CreateComponent( const char* componentID, void* pEnv, 
+                      int argc, const char** argv, AliHLTComponent*& component );
+
+  /**
+   * Create a component of the given name (ID).
+   * Introduced for backward compatibility.
+   * @param componentID  ID of the component to create
+   * @param pEnv         environment for the component
+   * @param component    reference to receive the create component instance
+   * @return component pointer in @ref component, neg. error code if failed
+   */
+  int CreateComponent( const char* componentID, void* pEnv, 
+                      AliHLTComponent*& component ) 
+    {
+    return CreateComponent( componentID, pEnv, 0, NULL, component );
+    }
+
+  /**
+   * Print registered components to stdout.
+   * @return none
    */
   void List();
+
+  /**
+   * Announce version and compilation info of the base library.
+   */
+  int AnnounceVersion();
+
  protected:
 
  private:
-  /* find a component
-     return index
-  */
+  /**
+   * Find a component.
+   * @param componentID  ID of the component to find
+   * @return index, neg. error code if failed
+   */
   int FindComponentIndex(const char* componentID);
 
-  /* find a component
-     return descriptor
-  */
+  /**
+   * Find a component.
+   * @param componentID  ID of the component to find
+   * @return descriptor
+   */
   AliHLTComponent* FindComponent(const char* componentID);
 
+  /**
+   * Insert component to the list
+   * @param pSample      sample object of the component
+   * @return neg. error code if failed
+   */
   int InsertComponent(AliHLTComponent* pSample);
 
-  // close all libraries
+  /**
+   * Close all libraries.
+   * @return neg. error code if failed
+   */
   int UnloadLibraries();
 
-  /* list of registered components
-   */
+  /** list of registered components */
   vector<AliHLTComponent*> fComponentList;
-
-  /* list of scheduled components
-   */
+  /** list of scheduled components */
   vector<AliHLTComponent*> fScheduleList;
-
-  /* list of libraries
-   */
+  /** list of libraries */
   vector<AliHLTLibHandle> fLibraryList;
-
+  /** running environment for the component */
   AliHLTComponentEnvironment fEnvironment;
 
-  ClassDef(AliHLTComponentHandler, 0)
+  ClassDef(AliHLTComponentHandler, 0);
 
-    };
+};
 #endif