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