documentation
authorrichterm <richterm@f7af4fe6-9843-0410-8265-dc069ae4e863>
Wed, 5 Jul 2006 14:32:41 +0000 (14:32 +0000)
committerrichterm <richterm@f7af4fe6-9843-0410-8265-dc069ae4e863>
Wed, 5 Jul 2006 14:32:41 +0000 (14:32 +0000)
HLT/BASE/AliHLTComponent.cxx
HLT/BASE/AliHLTComponent.h
HLT/BASE/AliHLTConfiguration.h
HLT/BASE/AliHLTDataBuffer.h
HLT/BASE/AliHLTProcessor.cxx
HLT/BASE/AliHLTProcessor.h
HLT/BASE/AliHLTSystem.h
HLT/BASE/Makefile

index 58ba921..3a97092 100644 (file)
@@ -5,7 +5,6 @@
  *                                                                        *
  * Authors: Matthias Richter <Matthias.Richter@ift.uib.no>                *
  *          Timm Steinbeck <timm@kip.uni-heidelberg.de>                   *
- *          Artur Szostak <artursz@iafrica.com>                           *
  *          for The ALICE Off-line Project.                               *
  *                                                                        *
  * Permission to use, copy, modify and distribute this software and its   *
  * provided "as is" without express or implied warranty.                  *
  **************************************************************************/
 
-///////////////////////////////////////////////////////////////////////////////
-//                                                                           //
-// base class for HLT components                                             //
-//                                                                           //
-///////////////////////////////////////////////////////////////////////////////
+/** @file   AliHLTComponent.cxx
+    @author Matthias Richter, Timm Steinbeck
+    @date   
+    @brief  Base class implementation for HLT components. */
 
 #if __GNUC__>= 3
 using namespace std;
index ce825f6..a8a3a32 100644 (file)
@@ -5,9 +5,10 @@
 /* Copyright(c) 1998-1999, ALICE Experiment at CERN, All rights reserved. *
  * See cxx source for full Copyright notice                               */
 
-/* AliHLTComponent
-   base class for HLT components
- */
+/** @file   AliHLTComponent.h
+    @author Matthias Richter, Timm Steinbeck
+    @date   
+    @brief  Base class declaration for HLT components. */
 
 #include <cerrno>
 #include "AliHLTLogging.h"
 
 class AliHLTComponentHandler;
 
+/**
+ * @class AliHLTComponent
+ * Base class of HLT data processing components.
+ * The class provides a common interface for HLT data processing components.
+ * The interface can be accessed from the online HLT framework or the AliRoot
+ * offline analysis framework.
+ * Components can be of type 
+ * - @ref kSource:    components which only produce data 
+ * - @ref kProcessor: components which consume and produce data
+ * - @ref kSink:      components which only consume data
+ *
+ * where data production and consumption refer to the analysis data stream.<br>
+ *
+ * In order to adapt to different environments (on-line/off-line), the component
+ * gets an environment structure with function pointers. The base class provides
+ * member functions for those environment dependend functions. The member 
+ * functions are used by the component implementation and are re-mapped to the
+ * corresponding functions.
+ * @ingroup AliHLTbase
+ */
 class AliHLTComponent : public AliHLTLogging {
  public:
+  /** standard constructor */
   AliHLTComponent();
+  /** standard destructor */
   virtual ~AliHLTComponent();
 
+  /** component type definitions */
   enum TComponentType { kUnknown=0, kSource=1, kProcessor=2, kSink=3 };
+
+  /**
+   * Init function to prepare data processing.
+   * Initialization of common data structures for a sequence of events.
+   * The call is redirected to the internal method @ref DoInit which can be
+   * overridden by the child class.<br>
+   * During Init also the environment structure is passed to the component.
+   * @param environ        environment pointer with environment dependend function
+   *                       calls
+   * @param environ_param  additionel parameter for function calls, the pointer
+   *                       is passed as it is
+   * @param argc           size of the argument array
+   * @param argv           agument array for component initialization
+   */
   virtual int Init( AliHLTComponentEnvironment* environ, void* environ_param, int argc, const char** argv );
+
+  /**
+   * Clean-up function to terminate data processing.
+   * Clean-up of common data structures after data processing.
+   * The call is redirected to the internal method @ref DoDeinit which can be
+   * overridden by the child class.
+   */
   virtual int Deinit();
+
+  /**
+   * Processing of one event.
+   * The method is pure virtual and implemented by the child classes 
+   * - @ref AliHLTProcessor
+   * - @ref AliHLTDataSource
+   * - @ref AliHLTDataSink
+   *
+   * @param evtData
+   * @param blocks
+   * @param trigData
+   * @param outputPtr
+   * @param size
+   * @param outputBlockCnt
+   * @param outputBlocks
+   * @param edd
+   * @return neg. error code if failed
+   */
   virtual int ProcessEvent( const AliHLTComponent_EventData& evtData, const AliHLTComponent_BlockData* blocks, 
                            AliHLTComponent_TriggerData& trigData, AliHLTUInt8_t* outputPtr, 
                            AliHLTUInt32_t& size, AliHLTUInt32_t& outputBlockCnt, 
@@ -32,17 +95,68 @@ class AliHLTComponent : public AliHLTLogging {
                            AliHLTComponent_EventDoneData*& edd ) = 0;
 
   // Information member functions for registration.
+
+  /**
+   * Get the type of the component.
+   * The function is pure virtual and must be implemented by the child class.
+   * @return component type id
+   */
   virtual TComponentType GetComponentType() = 0; // Source, sink, or processor
+
+  /**
+   * Get the id of the component.
+   * Each component is identified by a unique id.
+   * The function is pure virtual and must be implemented by the child class.
+   * @return component id (string)
+   */
   virtual const char* GetComponentID() = 0;
+
+  /**
+   * Get the input data types of the component.
+   * The function is pure virtual and must be implemented by the child class.
+   * @return list of data types in the vector reference
+   */
   virtual void GetInputDataTypes( vector<AliHLTComponent_DataType>& ) = 0;
+
+  /**
+   * Get the output data type of the component.
+   * The function is pure virtual and must be implemented by the child class.
+   * @return output data type
+   */
   virtual AliHLTComponent_DataType GetOutputDataType() = 0;
+
+  /**
+   * Get a ratio by how much the data volume is shrinked or enhanced.
+   * The function is pure virtual and must be implemented by the child class.
+   * @param constBase        <i>return</i>: additive part, independent of the
+   *                                   input data volume  
+   * @param inputMultiplier  <i>return</i>: multiplication ratio
+   * @return values in the reference variables
+   */
   virtual void GetOutputDataSize( unsigned long& constBase, double& inputMultiplier ) = 0;
 
-  // Spawn function, return new class instance
+  /**
+   * Spawn function.
+   * Each component must implement a spawn function to create a new instance of 
+   * the class. Basically the function must return <i>new <b>my_class_name</b></i>.
+   * @return new class instance
+   */
   virtual AliHLTComponent* Spawn() = 0;
 
+  /**
+   * Find matching data types between this component and a consumer component.
+   * Currently, a component can produce only one type of data. This restriction is most
+   * likely to be abolished in the future.
+   * @param pConsumer a component and consumer of the data produced by this component
+   * @param tgtList   reference to a vector list to receive the matching data types.
+   * @return >= 0 success, neg. error code if failed
+   */ 
   int FindMatchingDataTypes(AliHLTComponent* pConsumer, vector<AliHLTComponent_DataType>* tgtList);
  
+  /**
+   * Set the global component handler.
+   * The static method is needed for the automatic registration of components. 
+   */
   static int SetGlobalComponentHandler(AliHLTComponentHandler* pCH, int bOverwrite=0) {
     int iResult=0;
     if (fpComponentHandler==NULL || bOverwrite!=0)
@@ -51,12 +165,21 @@ class AliHLTComponent : public AliHLTLogging {
       iResult=-EPERM;
     return iResult;
   }
+
+  /**
+   * Clear the global component handler.
+   * The static method is needed for the automatic registration of components. 
+   */
   static int UnsetGlobalComponentHandler() {
     return SetGlobalComponentHandler(NULL,1);
   }
+
  protected:
 
-  // Fill various structures with default values.
+  /**
+   * Fill AliHLTComponent_BlockData structure with default values.
+   * @param blockData   reference to data structure
+   */
   void FillBlockData( AliHLTComponent_BlockData& blockData ) {
     blockData.fStructSize = sizeof(blockData);
     FillShmData( blockData.fShmKey );
@@ -66,31 +189,66 @@ class AliHLTComponent : public AliHLTLogging {
     FillDataType( blockData.fDataType );
     blockData.fSpecification = ~(AliHLTUInt32_t)0;
   }
+
+  /**
+   * Fill AliHLTComponent_ShmData structure with default values.
+   * @param shmData   reference to data structure
+   */
   void FillShmData( AliHLTComponent_ShmData& shmData ) {
     shmData.fStructSize = sizeof(shmData);
     shmData.fShmType = gkAliHLTComponent_InvalidShmType;
     shmData.fShmID = gkAliHLTComponent_InvalidShmID;
   }
+
+  /**
+   * Fill AliHLTComponent_DataType structure with default values.
+   * @param dataType   reference to data structure
+   */
   void FillDataType( AliHLTComponent_DataType& dataType ) {
     dataType.fStructSize = sizeof(dataType);
     memset( dataType.fID, '*', 8 );
     memset( dataType.fOrigin, '*', 4 );
   }
   
+  /**
+   * Default method for the internal initialization.
+   * The method is called by @ref Init
+   */
   virtual int DoInit( int argc, const char** argv ){
     return 0;
   }
 
+  /**
+   * Default method for the internal clean-up.
+   * The method is called by @ref Deinit
+   */
   virtual int DoDeinit(){
     return 0;
   }
 
+  /**
+   * General memory allocation method.
+   * All memory which is going to be used 'outside' of the interface must
+   * be provided by the framework (online or offline).
+   * The method is redirected to a function provided by the current
+   * framework. Function pointers are transferred via the @ref
+   * AliHLTComponentEnvironment structure.
+   */
   void* AllocMemory( unsigned long size ) {
     if (fEnvironment.fAllocMemoryFunc)
       return (*fEnvironment.fAllocMemoryFunc)(fEnvironment.fParam, size );
     return NULL;
   }
 
+  /**
+   * Helper function to create a monolithic BlockData description block out
+   * of a list BlockData descriptors.
+   * For convenience, inside the interface vector lists are used, to make the
+   * interface pure C style, monilithic blocks must be exchanged. 
+   * The method is redirected to a function provided by the current
+   * framework. Function pointers are transferred via the @ref
+   * AliHLTComponentEnvironment structure.
+   */
   int MakeOutputDataBlockList( const vector<AliHLTComponent_BlockData>& blocks, AliHLTUInt32_t* blockCount,
                               AliHLTComponent_BlockData** outputBlocks );
 /*  { */
@@ -99,6 +257,12 @@ class AliHLTComponent : public AliHLTLogging {
 /*     return -ENOSYS; */
 /*   } */
 
+  /**
+   * Fill the EventDoneData structure.
+   * The method is redirected to a function provided by the current
+   * framework. Function pointers are transferred via the @ref
+   * AliHLTComponentEnvironment structure.
+   */
   int GetEventDoneData( unsigned long size, AliHLTComponent_EventDoneData** edd ) {
     if (fEnvironment.fGetEventDoneDataFunc)
       return (*fEnvironment.fGetEventDoneDataFunc)(fEnvironment.fParam, fCurrentEvent, size, edd );
@@ -106,13 +270,22 @@ class AliHLTComponent : public AliHLTLogging {
   }
 
 
+  /**
+   * Helper function to convert the data type to a string.
+   */
   void DataType2Text( const AliHLTComponent_DataType& type, char output[14] );
 
  private:
+  /** The global component handler instance */
   static AliHLTComponentHandler* fpComponentHandler;
+  /** The environment where the component is running in */
   AliHLTComponentEnvironment fEnvironment;
 
-  AliHLTEventID_t fCurrentEvent; // Set by ProcessEvent before actual processing starts (e.g. before calling AliHLTProcessor::DoEvent)
+  /** 
+   * Set by ProcessEvent before the processing starts (e.g. before calling 
+   * @ref AliHLTProcessor::DoEvent)
+   */
+  AliHLTEventID_t fCurrentEvent;
 
   ClassDef(AliHLTComponent, 0)
 };
index d0e8e96..22ee981 100644 (file)
@@ -22,6 +22,8 @@ class AliHLTConfigurationHandler;
 
 /**
  * @class AliHLTConfiguration
+ * @brief Description of HLT processing chains.
+ * @note Definition:
  * This class describes a certain configuration af an HLT processing step
  * by the following parameters:
  * - a unique id string/name
@@ -30,12 +32,12 @@ class AliHLTConfigurationHandler;
  * - the arguments, which are passed to the component when it is initialized
  *
  * The setup of a configuration requires simply the creation of a global object
- * of @class AliHLTConfiguration. The Configuration is automatically registered
- * in the list of available configurations maintained by the @class
+ * of @ref AliHLTConfiguration. The Configuration is automatically registered
+ * in the list of available configurations maintained by the @ref
  * AliHLTConfigurationHandler. The list is used by to resolve the dependencies
  * on other configurations. Hierarchies can be built up in an easy way.
  *
- * A configuration is interpreted by the @class AliHLTConfigurationHandler and
+ * A configuration is interpreted by the @ref AliHLTConfigurationHandler and
  * transformed into a Task List.
  * @ingroup AliHLTbase
  */
@@ -267,7 +269,7 @@ class AliHLTTask : public TObject, public AliHLTLogging {
   AliHLTComponent* GetComponent() const;
 
   /**
-   * Find a dependency with a certain <i>name/id<i>. 
+   * Find a dependency with a certain <i>name id</i>. 
    * Searches in the list of dependencies for a task.
    * @param id      the id of the <b>CONFIGURATION</b><br>
    *                <b>NOTE:</b> the id does NOT specify a COMPONENT
index 84d1148..a0f71e1 100644 (file)
@@ -81,7 +81,8 @@ class AliHLTConsumerDescriptor : public AliHLTLogging, public TObject {
   /**
    * Set an active data segment
    * the pointer will be handled in a container, not allocation, copy or cleanup
-   * @param pSegment pointer to the segment instance
+   * @param offset  offset of the segment in the buffer
+   * @param size    size of the segment in the buffer
    * @return >=0 if succeeded
    */
   int SetActiveDataSegment(AliHLTUInt32_t offset, AliHLTUInt32_t size);
@@ -115,7 +116,8 @@ class AliHLTConsumerDescriptor : public AliHLTLogging, public TObject {
 };
 
 /**
- * @class AliHLTDataBuffer handling of data buffers for the HLT
+ * @class AliHLTDataBuffer
+ * @brief  Handling of data buffers for the HLT.
  * @note Definition:
  * The class provides handling of data buffers for HLT components. Each component gets its
  * own Data Buffer instance. The buffer is grouped into different data segments according
@@ -145,7 +147,6 @@ class AliHLTDataBuffer : public AliHLTLogging, public TObject {
   /**
    * Add component to the list of consumers
    * @param pConsumer - a consumer of type AliHLTComponent
-   * @param datatype - data type of the segement, the consumer is registered for
    */
   int SetConsumer(AliHLTComponent* pConsumer);
 
@@ -167,7 +168,7 @@ class AliHLTDataBuffer : public AliHLTLogging, public TObject {
   /**
    * Subscribe to a segment of the data buffer.
    * The function prepares the block descriptor for subsequent use with the AliHLTComponent::ProcessEvent
-   * method, the method can prepare several block descriptors up to the array size specified by @param
+   * method, the method can prepare several block descriptors up to the array size specified by
    * iArraySize. The return value is independent from the array size the number of block descriptors 
    * which would have been prepared if there was enough space in the array<br>
    * The method is used by the consumer component.
index 4eccd9a..5bb45d8 100644 (file)
@@ -5,7 +5,6 @@
  *                                                                        *
  * Authors: Matthias Richter <Matthias.Richter@ift.uib.no>                *
  *          Timm Steinbeck <timm@kip.uni-heidelberg.de>                   *
- *          Artur Szostak <artursz@iafrica.com>                           *
  *          for The ALICE Off-line Project.                               *
  *                                                                        *
  * Permission to use, copy, modify and distribute this software and its   *
  * provided "as is" without express or implied warranty.                  *
  **************************************************************************/
 
-///////////////////////////////////////////////////////////////////////////////
-//                                                                           //
-// base class for HLT analysis components                                             //
-//                                                                           //
-///////////////////////////////////////////////////////////////////////////////
+/** @file   AliHLTProcessor.cxx
+    @author Matthias Richter, Timm Steinbeck
+    @date   
+    @brief  Base class implementation for HLT analysis components. */
 
 #if __GNUC__>= 3
 using namespace std;
@@ -69,4 +67,3 @@ int AliHLTProcessor::ProcessEvent( const AliHLTComponent_EventData& evtData, con
   edd = NULL;
   return iResult;
 }
-
index 3820976..6eca643 100644 (file)
@@ -5,40 +5,81 @@
 /* Copyright(c) 1998-1999, ALICE Experiment at CERN, All rights reserved. *
  * See cxx source for full Copyright notice                               */
 
-/* AliHLTProcessor
-   base class for HLT processing components
- */
+/** @file   AliHLTProcessor.h
+    @author Matthias Richter, Timm Steinbeck
+    @date   
+    @brief  Base class declaration for HLT analysis components. */
 
 #include "AliHLTComponent.h"
 
+/**
+ * @class AliHLTProcessor
+ * Base class of HLT data analysis components.
+ * The class provides a common interface for the implementation of HLT data
+ * analysis components. The child class must implement the functions:
+ * - DoInit (optional)
+ * - DoDeinit (optional)
+ * - DoEvent
+ * - GetComponentID
+ * - GetInputDataTypes
+ * - GetOutputDataType
+ * - GetOutputDataSize
+ * - Spawn
+ *
+ * @ingroup AliHLTbase
+ */
 class AliHLTProcessor : public AliHLTComponent {
  public:
+  /** standard constructor */
   AliHLTProcessor();
+  /** standard destructor */
   virtual ~AliHLTProcessor();
 
+  /* depricated */
   int Init( AliHLTComponentEnvironment* environ, void* environ_param, int argc, const char** argv );
+  /* depricated */
   int Deinit();
-  int ProcessEvent( const AliHLTComponent_EventData& evtData, const AliHLTComponent_BlockData* blocks, 
-                   AliHLTComponent_TriggerData& trigData, AliHLTUInt8_t* outputPtr, 
-                   AliHLTUInt32_t& size, AliHLTUInt32_t& outputBlockCnt, 
+
+  /**
+   * Event processing function.
+   * The method is called by the framework to process one event. After 
+   * preparation of data structures. The call is redirected to DoEvent.
+   * @return neg. error code if failed 
+   */
+  int ProcessEvent( const AliHLTComponent_EventData& evtData,
+                   const AliHLTComponent_BlockData* blocks, 
+                   AliHLTComponent_TriggerData& trigData,
+                   AliHLTUInt8_t* outputPtr, 
+                   AliHLTUInt32_t& size,
+                   AliHLTUInt32_t& outputBlockCnt, 
                    AliHLTComponent_BlockData*& outputBlocks,
                    AliHLTComponent_EventDoneData*& edd );
 
   // Information member functions for registration.
+
+  /**
+   * Return @ref AliHLTComponent::kProcessor type as component type.
+   * @return component type id
+   */
   TComponentType GetComponentType() { return AliHLTComponent::kProcessor;}
 
  private:
-  virtual int DoInit( int argc, const char** argv ){
-    return 0;
-  }
-
-  virtual int DoDeinit(){
-    return 0;
-  }
-  virtual int DoEvent( const AliHLTComponent_EventData& evtData, const AliHLTComponent_BlockData* blocks, 
-                      AliHLTComponent_TriggerData& trigData, AliHLTUInt8_t* outputPtr, 
-                      AliHLTUInt32_t& size, vector<AliHLTComponent_BlockData>& outputBlocks ) = 0;
-
+  /**
+   * Data processing method for the component.
+   * @param evtData       event data structure
+   * @param blocks        input data block descriptors
+   * @param trigData     trigger data structure
+   * @param outputPtr    pointer to target buffer
+   * @param size         <i>input</i>: size of target buffer
+   *                     <i>output</i>:size of produced data
+   * @param outputBlocks  list to receive output block descriptors
+   */
+  virtual int DoEvent( const AliHLTComponent_EventData& evtData,
+                      const AliHLTComponent_BlockData* blocks, 
+                      AliHLTComponent_TriggerData& trigData,
+                      AliHLTUInt8_t* outputPtr, 
+                      AliHLTUInt32_t& size,
+                      vector<AliHLTComponent_BlockData>& outputBlocks ) = 0;
 
   ClassDef(AliHLTProcessor, 0)
 };
index 3cb07e3..931836b 100644 (file)
@@ -19,29 +19,51 @@ class AliHLTConfiguration;
 class AliHLTConfigurationHandler;
 class AliHLTTask;
 
+/**
+ * @class AliHLTSystem
+ * Main class for the HLT integration into AliRoot.
+ * The class handles a list of configurations. Configurations are translated
+ * into task lists which can be executed. 
+ *
+ */
 class AliHLTSystem : public AliHLTLogging {
  public:
+  /** default constructor */
   AliHLTSystem();
+  /** destructor */
   virtual ~AliHLTSystem();
 
-  /* this will change later
+  /**
+   * Pointer to an instance of @ref AliHLTComponentHandler.
    */
   AliHLTComponentHandler* fpComponentHandler;
+
+  /**
+   * Pointer to an instance of @ref AliHLTConfigurationHandler.
+   */
   AliHLTConfigurationHandler* fpConfigurationHandler;
 
-  /* add a configuration to the end of the list
+  /**
+   * Add a configuration to the end of the list.
+   * @param pConf    pointer to configuration to add
    */
   int AddConfiguration(AliHLTConfiguration* pConf);
 
-  /* add a configuration to the list after the specified configuration
+  /**
+   * Insert a configuration to the end of the list after the specified configuration.
+   * @param pConf    pointer to configuration to insert
+   * @param pPrec    pointer to configuration to insert the new one after
    */
   int InsertConfiguration(AliHLTConfiguration* pConf, AliHLTConfiguration* pPrec);
 
-  /* remove a configuration from the list
+  /**
+   * Remove a configuration from the list.
+   * @param pConf    pointer to configuration to delete
    */
   int DeleteConfiguration(AliHLTConfiguration* pConf);
 
-  /* build a task list from a configuration object
+  /**
+   * Build a task list from a configuration object.
    * This method is used to build the tasks from the 'master' configuration
    * objects which are added to the HLT system handler. This is an iterative
    * process since the task might depend upon other configurations. For each
@@ -49,27 +71,33 @@ class AliHLTSystem : public AliHLTLogging {
    * method will be called iteratively. Finally, after building all tasks which
    * the current one depends on have been created, the task is inserted to the
    * list of tasks with the InsertTask method.
+   * @param pConf    pointer to configuration to build the task list from
    */
   int BuildTaskList(AliHLTConfiguration* pConf);
 
-  /* clean the list of tasks and delete all the task objects
+  /**
+   * Clean the list of tasks and delete all the task objects.
    */
   int CleanTaskList();
 
-  /* insert a task to the task list
-   * the method first checks whether all dependencies are resolved (i.e. exist 
+  /**
+   * Insert a task to the task list.
+   * The method first checks whether all dependencies are resolved (i.e. exist 
    * already in the task list). During this iteration the cross links between the 
    * tasks are set as well. If all dependencies are resolved, the task is added
    * at the end of the list.
+   * @param pTask    pointer to task to add
    */
   int InsertTask(AliHLTTask* pTask);
 
-  /* find a task with an id
-   * NOTE: 'id' denotes a CONFIGURATION, not a COMPONENT
+  /**
+   * Find a task with an id.
+   * @param id       CONFIGURATION id (not a COMPONENT id!)
    */
   AliHLTTask* FindTask(const char* id);
 
-  /* print the task list
+  /**
+   * Print the task list.
    */
   void PrintTaskList();
 
index 6354e0b..6729cbe 100644 (file)
@@ -18,7 +18,8 @@ include $(ALIHLT_TOPDIR)/Makefile.conf
 SRCS   = AliHLTComponent.cxx AliHLTComponentHandler.cxx \
           AliHLTSystem.cxx AliHLT_C_Component_WrapperInterface.cxx \
          AliHLTProcessor.cxx AliHLTConfiguration.cxx \
-         AliHLTLogging.cxx AliHLTDataBuffer.cxx
+         AliHLTLogging.cxx AliHLTDataBuffer.cxx \
+         AliHLTDataSource.cxx AliHLTDataSink.cxx
 
 SRCS += $(EXTRA_SRCS)