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