HLT/BASE/AliHLTComponent.h

   1 // @(#) $Id$
   2
   3 #ifndef ALIHLTCOMPONENT_H
   4 #define ALIHLTCOMPONENT_H
   5 /* Copyright(c) 1998-1999, ALICE Experiment at CERN, All rights reserved. *
   6  * See cxx source for full Copyright notice                               */
   7
   8 /** @file   AliHLTComponent.h
   9     @author Matthias Richter, Timm Steinbeck
  10     @date
  11     @brief  Base class declaration for HLT components.
  12     @note   The class is both used in Online (PubSub) and Offline (AliRoot)
  13             context
  14                                                                           */
  15 /**
  16  * @defgroup alihlt_component Component handling of the HLT module
  17  * This section describes the the component handling for the HLT module.
  18  */
  19
  20 #include <vector>
  21 #include "AliHLTLogging.h"
  22 #include "AliHLTDataTypes.h"
  23 #include "AliHLTDefinitions.h"
  24 #include "TObject.h"
  25
  26 class AliHLTComponentHandler;
  27
  28 /**
  29  * @class AliHLTComponent
  30  * Base class of HLT data processing components.
  31  * The class provides a common interface for HLT data processing components.
  32  * The interface can be accessed from the online HLT framework or the AliRoot
  33  * offline analysis framework.
  34  * Components can be of type
  35  * - @ref kSource:    components which only produce data
  36  * - @ref kProcessor: components which consume and produce data
  37  * - @ref kSink:      components which only consume data
  38  *
  39  * where data production and consumption refer to the analysis data stream.<br>
  40  *
  41  * In order to adapt to different environments (on-line/off-line), the component
  42  * gets an environment structure with function pointers. The base class provides
  43  * member functions for those environment dependend functions. The member
  44  * functions are used by the component implementation and are re-mapped to the
  45  * corresponding functions.
  46  * @ingroup alihlt_component
  47  */
  48 class AliHLTComponent : public AliHLTLogging {
  49  public:
  50   /** standard constructor */
  51   AliHLTComponent();
  52   /** standard destructor */
  53   virtual ~AliHLTComponent();
  54
  55   /** component type definitions */
  56   enum TComponentType { kUnknown=0, kSource=1, kProcessor=2, kSink=3 };
  57
  58   /**
  59    * Init function to prepare data processing.
  60    * Initialization of common data structures for a sequence of events.
  61    * The call is redirected to the internal method @ref DoInit which can be
  62    * overridden by the child class.<br>
  63    * During Init also the environment structure is passed to the component.
  64    * @param environ        environment pointer with environment dependend function
  65    *                       calls
  66    * @param environ_param  additionel parameter for function calls, the pointer
  67    *                       is passed as it is
  68    * @param argc           size of the argument array
  69    * @param argv           agument array for component initialization
  70    */
  71   virtual int Init( AliHLTComponentEnvironment* environ, void* environ_param, int argc, const char** argv );
  72
  73   /**
  74    * Clean-up function to terminate data processing.
  75    * Clean-up of common data structures after data processing.
  76    * The call is redirected to the internal method @ref DoDeinit which can be
  77    * overridden by the child class.
  78    */
  79   virtual int Deinit();
  80
  81   /**
  82    * Processing of one event.
  83    * The method is pure virtual and implemented by the child classes
  84    * - @ref AliHLTProcessor
  85    * - @ref AliHLTDataSource
  86    * - @ref AliHLTDataSink
  87    *
  88    * @param evtData
  89    * @param blocks
  90    * @param trigData
  91    * @param outputPtr
  92    * @param size
  93    * @param outputBlockCnt
  94    * @param outputBlocks
  95    * @param edd
  96    * @return neg. error code if failed
  97    */
  98   virtual int ProcessEvent( const AliHLTComponentEventData& evtData, const AliHLTComponentBlockData* blocks,
  99                             AliHLTComponentTriggerData& trigData, AliHLTUInt8_t* outputPtr,
 100                             AliHLTUInt32_t& size, AliHLTUInt32_t& outputBlockCnt,
 101                             AliHLTComponentBlockData*& outputBlocks,
 102                             AliHLTComponentEventDoneData*& edd ) = 0;
 103
 104   // Information member functions for registration.
 105
 106   /**
 107    * Get the type of the component.
 108    * The function is pure virtual and must be implemented by the child class.
 109    * @return component type id
 110    */
 111   virtual TComponentType GetComponentType() = 0; // Source, sink, or processor
 112
 113   /**
 114    * Get the id of the component.
 115    * Each component is identified by a unique id.
 116    * The function is pure virtual and must be implemented by the child class.
 117    * @return component id (string)
 118    */
 119   virtual const char* GetComponentID() = 0;
 120
 121   /**
 122    * Get the input data types of the component.
 123    * The function is pure virtual and must be implemented by the child class.
 124    * @return list of data types in the vector reference
 125    */
 126   virtual void GetInputDataTypes( vector<AliHLTComponentDataType>& ) = 0;
 127
 128   /**
 129    * Get the output data type of the component.
 130    * The function is pure virtual and must be implemented by the child class.
 131    * @return output data type
 132    */
 133   virtual AliHLTComponentDataType GetOutputDataType() = 0;
 134
 135   /**
 136    * Get a ratio by how much the data volume is shrinked or enhanced.
 137    * The function is pure virtual and must be implemented by the child class.
 138    * @param constBase        <i>return</i>: additive part, independent of the
 139    *                                   input data volume
 140    * @param inputMultiplier  <i>return</i>: multiplication ratio
 141    * @return values in the reference variables
 142    */
 143   virtual void GetOutputDataSize( unsigned long& constBase, double& inputMultiplier ) = 0;
 144
 145   /**
 146    * Spawn function.
 147    * Each component must implement a spawn function to create a new instance of
 148    * the class. Basically the function must return <i>new <b>my_class_name</b></i>.
 149    * @return new class instance
 150    */
 151   virtual AliHLTComponent* Spawn() = 0;
 152
 153   /**
 154    * Find matching data types between this component and a consumer component.
 155    * Currently, a component can produce only one type of data. This restriction is most
 156    * likely to be abolished in the future.
 157    * @param pConsumer a component and consumer of the data produced by this component
 158    * @param tgtList   reference to a vector list to receive the matching data types.
 159    * @return >= 0 success, neg. error code if failed
 160    */
 161   int FindMatchingDataTypes(AliHLTComponent* pConsumer, vector<AliHLTComponentDataType>* tgtList);
 162
 163   /**
 164    * Set the global component handler.
 165    * The static method is needed for the automatic registration of components.
 166    */
 167   static int SetGlobalComponentHandler(AliHLTComponentHandler* pCH, int bOverwrite=0);
 168
 169   /**
 170    * Clear the global component handler.
 171    * The static method is needed for the automatic registration of components.
 172    */
 173   static int UnsetGlobalComponentHandler();
 174
 175  protected:
 176
 177   /**
 178    * Fill AliHLTComponentBlockData structure with default values.
 179    * @param blockData   reference to data structure
 180    */
 181   void FillBlockData( AliHLTComponentBlockData& blockData ) {
 182     blockData.fStructSize = sizeof(blockData);
 183     FillShmData( blockData.fShmKey );
 184     blockData.fOffset = ~(AliHLTUInt32_t)0;
 185     blockData.fPtr = NULL;
 186     blockData.fSize = 0;
 187     FillDataType( blockData.fDataType );
 188     blockData.fSpecification = ~(AliHLTUInt32_t)0;
 189   }
 190
 191   /**
 192    * Fill AliHLTComponentShmData structure with default values.
 193    * @param shmData   reference to data structure
 194    */
 195   void FillShmData( AliHLTComponentShmData& shmData ) {
 196     shmData.fStructSize = sizeof(shmData);
 197     shmData.fShmType = gkAliHLTComponentInvalidShmType;
 198     shmData.fShmID = gkAliHLTComponentInvalidShmID;
 199   }
 200
 201   /**
 202    * Fill AliHLTComponentDataType structure with default values.
 203    * @param dataType   reference to data structure
 204    */
 205   void FillDataType( AliHLTComponentDataType& dataType ) {
 206     dataType.fStructSize = sizeof(dataType);
 207     memset( dataType.fID, '*', 8 );
 208     memset( dataType.fOrigin, '*', 4 );
 209   }
 210
 211   /**
 212    * Default method for the internal initialization.
 213    * The method is called by @ref Init
 214    */
 215   virtual int DoInit( int argc, const char** argv );
 216
 217   /**
 218    * Default method for the internal clean-up.
 219    * The method is called by @ref Deinit
 220    */
 221   virtual int DoDeinit();
 222
 223   /**
 224    * General memory allocation method.
 225    * All memory which is going to be used 'outside' of the interface must
 226    * be provided by the framework (online or offline).
 227    * The method is redirected to a function provided by the current
 228    * framework. Function pointers are transferred via the @ref
 229    * AliHLTComponentEnvironment structure.
 230    */
 231   void* AllocMemory( unsigned long size );
 232
 233   /**
 234    * Helper function to create a monolithic BlockData description block out
 235    * of a list BlockData descriptors.
 236    * For convenience, inside the interface vector lists are used, to make the
 237    * interface pure C style, monilithic blocks must be exchanged.
 238    * The method is redirected to a function provided by the current
 239    * framework. Function pointers are transferred via the @ref
 240    * AliHLTComponentEnvironment structure.
 241    */
 242   int MakeOutputDataBlockList( const vector<AliHLTComponentBlockData>& blocks, AliHLTUInt32_t* blockCount,
 243                                AliHLTComponentBlockData** outputBlocks );
 244
 245   /**
 246    * Fill the EventDoneData structure.
 247    * The method is redirected to a function provided by the current
 248    * framework. Function pointers are transferred via the @ref
 249    * AliHLTComponentEnvironment structure.
 250    */
 251   int GetEventDoneData( unsigned long size, AliHLTComponentEventDoneData** edd );
 252
 253   /**
 254    * Helper function to convert the data type to a string.
 255    */
 256   void DataType2Text( const AliHLTComponentDataType& type, char output[14] );
 257
 258  private:
 259   /** The global component handler instance */
 260   static AliHLTComponentHandler* fpComponentHandler;
 261   /** The environment where the component is running in */
 262   AliHLTComponentEnvironment fEnvironment;
 263
 264   /**
 265    * Set by ProcessEvent before the processing starts (e.g. before calling
 266    * @ref AliHLTProcessor::DoEvent)
 267    */
 268   AliHLTEventID_t fCurrentEvent;
 269
 270   ClassDef(AliHLTComponent, 0)
 271 };
 272 #endif