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