corrections from previous commit
[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
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    * @ref 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