added code documentation for BASE, SampleLib, TPCLib and build system
[u/mrichter/AliRoot.git] / HLT / BASE / AliHLTComponent.h
... / ...
CommitLineData
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
25class 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 */
47class 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