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 pure virtual and implemented by the child classes
  98    * - @ref AliHLTProcessor
  99    * - @ref AliHLTDataSource
 100    * - @ref AliHLTDataSink
 101    *
 102    * @param evtData
 103    * @param blocks
 104    * @param trigData
 105    * @param outputPtr
 106    * @param size
 107    * @param outputBlockCnt  out: size of the output block array, set by the component
 108    * @param outputBlocks    out: the output block array is allocated internally
 109    * @param edd
 110    * @return neg. error code if failed
 111    */
 112   virtual int ProcessEvent( const AliHLTComponentEventData& evtData, const AliHLTComponentBlockData* blocks,
 113                             AliHLTComponentTriggerData& trigData, AliHLTUInt8_t* outputPtr,
 114                             AliHLTUInt32_t& size, AliHLTUInt32_t& outputBlockCnt,
 115                             AliHLTComponentBlockData*& outputBlocks,
 116                             AliHLTComponentEventDoneData*& edd ) = 0;
 117
 118   // Information member functions for registration.
 119
 120   /**
 121    * Get the type of the component.
 122    * The function is pure virtual and must be implemented by the child class.
 123    * @return component type id
 124    */
 125   virtual TComponentType GetComponentType() = 0; // Source, sink, or processor
 126
 127   /**
 128    * Get the id of the component.
 129    * Each component is identified by a unique id.
 130    * The function is pure virtual and must be implemented by the child class.
 131    * @return component id (string)
 132    */
 133   virtual const char* GetComponentID() = 0;
 134
 135   /**
 136    * Get the input data types of the component.
 137    * The function is pure virtual and must be implemented by the child class.
 138    * @return list of data types in the vector reference
 139    */
 140   virtual void GetInputDataTypes( vector<AliHLTComponentDataType>& ) = 0;
 141
 142   /**
 143    * Get the output data type of the component.
 144    * The function is pure virtual and must be implemented by the child class.
 145    * @return output data type
 146    */
 147   virtual AliHLTComponentDataType GetOutputDataType() = 0;
 148
 149   /**
 150    * Get a ratio by how much the data volume is shrinked or enhanced.
 151    * The function is pure virtual and must be implemented by the child class.
 152    * @param constBase        <i>return</i>: additive part, independent of the
 153    *                                   input data volume
 154    * @param inputMultiplier  <i>return</i>: multiplication ratio
 155    * @return values in the reference variables
 156    */
 157   virtual void GetOutputDataSize( unsigned long& constBase, double& inputMultiplier ) = 0;
 158
 159   /**
 160    * Spawn function.
 161    * Each component must implement a spawn function to create a new instance of
 162    * the class. Basically the function must return <i>new <b>my_class_name</b></i>.
 163    * @return new class instance
 164    */
 165   virtual AliHLTComponent* Spawn() = 0;
 166
 167   /**
 168    * Find matching data types between this component and a consumer component.
 169    * Currently, a component can produce only one type of data. This restriction is most
 170    * likely to be abolished in the future.
 171    * @param pConsumer a component and consumer of the data produced by this component
 172    * @param tgtList   reference to a vector list to receive the matching data types.
 173    * @return >= 0 success, neg. error code if failed
 174    */
 175   int FindMatchingDataTypes(AliHLTComponent* pConsumer, vector<AliHLTComponentDataType>* tgtList);
 176
 177   /**
 178    * Set the global component handler.
 179    * The static method is needed for the automatic registration of components.
 180    */
 181   static int SetGlobalComponentHandler(AliHLTComponentHandler* pCH, int bOverwrite=0);
 182
 183   /**
 184    * Clear the global component handler.
 185    * The static method is needed for the automatic registration of components.
 186    */
 187   static int UnsetGlobalComponentHandler();
 188
 189   /**
 190    * Helper function to convert the data type to a string.
 191    */
 192   static string DataType2Text( const AliHLTComponentDataType& type );
 193
 194   /**
 195    * helper function to initialize AliHLTComponentEventData structure
 196    */
 197   static void FillEventData(AliHLTComponentEventData& evtData);
 198
 199   /**
 200    * Print info on an AliHLTComponentDataType structure
 201    * This is just a helper function to examine an @ref AliHLTComponentDataType
 202    * structur.
 203    */
 204   void PrintComponentDataTypeInfo(const AliHLTComponentDataType& dt);
 205
 206  protected:
 207
 208   /**
 209    * Fill AliHLTComponentBlockData structure with default values.
 210    * @param blockData   reference to data structure
 211    */
 212   void FillBlockData( AliHLTComponentBlockData& blockData );
 213
 214   /**
 215    * Fill AliHLTComponentShmData structure with default values.
 216    * @param shmData   reference to data structure
 217    */
 218   void FillShmData( AliHLTComponentShmData& shmData );
 219
 220   /**
 221    * Fill AliHLTComponentDataType structure with default values.
 222    * @param dataType   reference to data structure
 223    */
 224   void FillDataType( AliHLTComponentDataType& dataType );
 225
 226   /**
 227    * Copy data type structure
 228    * Copies the value an AliHLTComponentDataType structure to another one
 229    * @param[out] tgtdt   target structure
 230    * @param[in] srcdt   source structure
 231    */
 232   void CopyDataType(AliHLTComponentDataType& tgtdt, const AliHLTComponentDataType& srcdt);
 233
 234   /**
 235    * Set the ID and Origin of an AliHLTComponentDataType structure.
 236    * The function sets the fStructureSize member and copies the strings
 237    * to the ID and Origin. Only characters from the valid part of the string
 238    * are copied, the rest is fille with 0's.
 239    * Please note that the fID and fOrigin members are not strings, just arrays of
 240    * chars of size @ref kAliHLTComponentDataTypefIDsize and
 241    * @ref kAliHLTComponentDataTypefOriginSize respectively and not necessarily with
 242    * a terminating zero.
 243    * @param tgtdt   target data type structure
 244    * @param id      ID string
 245    * @param origin  Origin string
 246    */
 247   void SetDataType(AliHLTComponentDataType& tgtdt, const char* id, const char* origin);
 248
 249   /**
 250    * Default method for the internal initialization.
 251    * The method is called by @ref Init
 252    */
 253   virtual int DoInit( int argc, const char** argv );
 254
 255   /**
 256    * Default method for the internal clean-up.
 257    * The method is called by @ref Deinit
 258    */
 259   virtual int DoDeinit();
 260
 261   /**
 262    * General memory allocation method.
 263    * All memory which is going to be used 'outside' of the interface must
 264    * be provided by the framework (online or offline).
 265    * The method is redirected to a function provided by the current
 266    * framework. Function pointers are transferred via the @ref
 267    * AliHLTComponentEnvironment structure.
 268    */
 269   void* AllocMemory( unsigned long size );
 270
 271   /**
 272    * Helper function to create a monolithic BlockData description block out
 273    * of a list BlockData descriptors.
 274    * For convenience, inside the interface vector lists are used, to make the
 275    * interface pure C style, monilithic blocks must be exchanged.
 276    * The method is redirected to a function provided by the current
 277    * framework. Function pointers are transferred via the @ref
 278    * AliHLTComponentEnvironment structure.
 279    */
 280   int MakeOutputDataBlockList( const vector<AliHLTComponentBlockData>& blocks, AliHLTUInt32_t* blockCount,
 281                                AliHLTComponentBlockData** outputBlocks );
 282
 283   /**
 284    * Fill the EventDoneData structure.
 285    * The method is redirected to a function provided by the current
 286    * framework. Function pointers are transferred via the @ref
 287    * AliHLTComponentEnvironment structure.
 288    */
 289   int GetEventDoneData( unsigned long size, AliHLTComponentEventDoneData** edd );
 290
 291   /**
 292    * Helper function to convert the data type to a string.
 293    */
 294   void DataType2Text(const AliHLTComponentDataType& type, char output[kAliHLTComponentDataTypefIDsize+kAliHLTComponentDataTypefOriginSize+2]);
 295
 296  private:
 297   /** The global component handler instance */
 298   static AliHLTComponentHandler* fpComponentHandler;
 299   /** The environment where the component is running in */
 300   AliHLTComponentEnvironment fEnvironment;
 301
 302   /**
 303    * Set by ProcessEvent before the processing starts (e.g. before calling
 304    * @ref AliHLTProcessor::DoEvent)
 305    */
 306   AliHLTEventID_t fCurrentEvent;
 307
 308   ClassDef(AliHLTComponent, 0)
 309 };
 310 #endif