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