corrected README
[u/mrichter/AliRoot.git] / HLT / BASE / AliHLTDataBuffer.h
CommitLineData
3f2a1b1c 1// @(#) $Id$
2
3#ifndef ALIHLTDATABUFFER_H
4#define ALIHLTDATABUFFER_H
5/* Copyright(c) 1998-1999, ALICE Experiment at CERN, All rights reserved. *
6 * See cxx source for full Copyright notice */
7
3f2a1b1c 8
9#include <cerrno>
10#include "AliHLTLogging.h"
11#include "AliHLTDataTypes.h"
12#include "AliHLTDefinitions.h"
13#include "AliHLTComponent.h"
14#include "TObject.h"
15#include "TList.h"
16
0c0c9d99 17/* @name internal data structures
18 */
19
20/* @struct AliHLTDataSegment
21 * @brief descriptor of a data segment within the buffer
22 * @ingroup AliHLTbase
3f2a1b1c 23 */
24struct AliHLTDataSegment {
0c0c9d99 25 AliHLTDataSegment()
26 {
27 //fDataType=0;
28 fSegmentOffset=0;
29 fSegmentSize=0;
30 fSpecification=0;
31 }
32 AliHLTDataSegment(AliHLTUInt32_t offset, AliHLTUInt32_t size)
33 {
34 //fDataType=0;
35 fSegmentOffset=offset;
36 fSegmentSize=size;
37 fSpecification=0;
38 }
3f2a1b1c 39 AliHLTComponent_DataType fDataType; // the data type of this buffer
0c0c9d99 40 AliHLTUInt32_t fSegmentOffset; // offset in byte within the data buffer
41 AliHLTUInt32_t fSegmentSize; // size of the actual content
3f2a1b1c 42 AliHLTUInt32_t fSpecification; // data specification
43};
44
0c0c9d99 45/* @struct AliHLTRawBuffer
46 * @brief descriptor of the raw data buffer which can host several segments
47 * @ingroup AliHLTbase
3f2a1b1c 48 */
49struct AliHLTRawBuffer {
0c0c9d99 50 AliHLTUInt32_t fSize; // size of the buffer
51 AliHLTUInt32_t fTotalSize; // total size of the buffer, including safety margin
3f2a1b1c 52 void* fPtr; // the buffer
53};
54
0c0c9d99 55/* @struct AliHLTConsumerDescriptor
56 * @brief there is unfortunately no unique determination of the data type from the component
57 * itself possible, thats why both component and data type have to be initialized
58 * and are stored in a compound. The class is intended to make bookkeeping easier
59 * @ingroup AliHLTbase
3f2a1b1c 60 */
0c0c9d99 61class AliHLTConsumerDescriptor : public AliHLTLogging, public TObject {
3f2a1b1c 62 private:
63 AliHLTComponent* fpConsumer;
0c0c9d99 64 vector<AliHLTDataSegment> fSegments;
3f2a1b1c 65
66 public:
0c0c9d99 67 /** standard constructur */
3f2a1b1c 68 AliHLTConsumerDescriptor();
0c0c9d99 69 /** constructur
70 * @param pConsumer pointer to the consumer component
71 */
72 AliHLTConsumerDescriptor(AliHLTComponent* pConsumer);
3f2a1b1c 73 ~AliHLTConsumerDescriptor();
74
0c0c9d99 75 /**
76 * Get the component of this descriptor
77 * @return pointer to the component
78 */
3f2a1b1c 79 AliHLTComponent* GetComponent() {return fpConsumer;}
3f2a1b1c 80
0c0c9d99 81 /**
82 * Set an active data segment
83 * the pointer will be handled in a container, not allocation, copy or cleanup
bfccbf68 84 * @param offset offset of the segment in the buffer
85 * @param size size of the segment in the buffer
0c0c9d99 86 * @return >=0 if succeeded
87 */
88 int SetActiveDataSegment(AliHLTUInt32_t offset, AliHLTUInt32_t size);
89
90 /**
91 * check whether there is an active data segment of certain size with certain offset
92 * @param offset offset of the data segment in the data buffer
93 * @param size size of the data segment in the data buffer
94 * @return > if existend, 0 if not
95 */
3f2a1b1c 96 int CheckActiveDataSegment(AliHLTUInt32_t offset, AliHLTUInt32_t size);
0c0c9d99 97
98 /** find an active data segment of certain size with certain offset
99 * will see if this is necessary
100 * @param offset offset of the data segment in the data buffer
101 * @param size size of the data segment in the data buffer
102 * @return offset of the data segment
103 */
104 //AliHLTUInt32_t FindActiveDataSegment(AliHLTUInt32_t offset, AliHLTUInt32_t size);
105
106 /** get the number of active segments for this consumer
107 * @return number of active segments
108 */
109 int GetNofActiveSegments() {return fSegments.size();};
110
111 /**
112 */
113 int ReleaseActiveDataSegment(AliHLTUInt32_t offset, AliHLTUInt32_t size);
114
115 //ClassDef(AliHLTConsumerDescriptor, 0)
3f2a1b1c 116};
117
0c0c9d99 118/**
bfccbf68 119 * @class AliHLTDataBuffer
120 * @brief Handling of data buffers for the HLT.
0c0c9d99 121 * @note Definition:
122 * The class provides handling of data buffers for HLT components. Each component gets its
123 * own Data Buffer instance. The buffer is grouped into different data segments according
124 * to the output of the component.<br>
125 * The Data Buffer keeps control over the data requests of the 'child' componets. Each
126 * component can subscribe to a certain segment of the data buffer. It's state is that
127 * changed from 'reserved' to 'active'. After the data processing the component has to
128 * release the segment and it's state is set to 'processed'.
129 * If all components have requested and released their data, the Raw Buffer is released
130 * and pushed back in the list of available buffers.
131 * @ingroup AliHLTbase
132 */
3f2a1b1c 133class AliHLTDataBuffer : public AliHLTLogging, public TObject {
134 public:
0c0c9d99 135 ////////////////////////////////////////////////////////////////////////////////////////////////////////////////
136 // condtructors and destructors
137
138 /* standard constructor
139 */
3f2a1b1c 140 AliHLTDataBuffer();
0c0c9d99 141
3f2a1b1c 142 virtual ~AliHLTDataBuffer();
143
144 ////////////////////////////////////////////////////////////////////////////////////////////////////////////////
145 // initialization
146
0c0c9d99 147 /**
148 * Add component to the list of consumers
149 * @param pConsumer - a consumer of type AliHLTComponent
3f2a1b1c 150 */
0c0c9d99 151 int SetConsumer(AliHLTComponent* pConsumer);
3f2a1b1c 152
153 ////////////////////////////////////////////////////////////////////////////////////////////////////////////////
154 // component to component communication
155
0c0c9d99 156 /**
157 * Determine the number of matching data blocks for the component and a consumer
158 * component. <br>
159 * The first approach will support only one output data type for processing components.
160 * @param pConsumer the component which subscribes to the buffer
161 * @param tgtList (optional) the list to receive the data types
162 * @return: number of data blocks which match the input data types
163 * of the consumer, neg. error code if failed <br>
164 * -EINVAL invalid parameter <br>
3f2a1b1c 165 */
0c0c9d99 166 int FindMatchingDataBlocks(const AliHLTComponent* pConsumer, vector<AliHLTComponent_DataType>* tgtList=NULL);
167
168 /**
169 * Subscribe to a segment of the data buffer.
170 * The function prepares the block descriptor for subsequent use with the AliHLTComponent::ProcessEvent
bfccbf68 171 * method, the method can prepare several block descriptors up to the array size specified by
0c0c9d99 172 * iArraySize. The return value is independent from the array size the number of block descriptors
173 * which would have been prepared if there was enough space in the array<br>
174 * The method is used by the consumer component.
175 * @param pConsumer the component which subscribes to the buffer
176 * @param arrayBlockDesc pointer to block descriptor to be filled
177 * @param iArraySize size of the block descriptor array
178 * @return: number of matching data blocks if success, negative error code if failed<br>
179 * -EACCESS the state of the consumer can not be changed (activated)
180 * -EBADF unresolved data segments <br>
181 * -ENOENT consumer component not found <br>
182 * -ENODATA data buffer does not have raw data <br>
183 * -EINVAL invalid parameter <br>
184 */
185 int Subscribe(const AliHLTComponent* pConsumer, AliHLTComponent_BlockData* arrayBlockDesc, int iArraySize);
186
187 /**
188 * Release an instance of the data buffer.
189 * Resets the variables of the block descriptor.
190 * If all buffer segments are released, the Data Buffer is reseted
191 * and the Raw Buffer released.<br>
192 * The method is used by the consumer component.
193 * @param pBlockDesc descriptor of the data segment
194 * @param pConsumer the component which subscribes to the buffer
195 * @return: >0 if success, negative error code if failed <br>
196 * -EACCESS the state of the consumer can not be changed (de-activated)
197 * -ENOENT consumer component has not subscribed to the buffer <br>
198 * -EINVAL invalid parameter <br>
3f2a1b1c 199 */
200 int Release(AliHLTComponent_BlockData* pBlockDesc, const AliHLTComponent* pConsumer);
201
0c0c9d99 202 /**
203 * Get a target buffer of minimum size iMinSize.
204 * The method is used by the component which owns the Data Buffer to
205 * allocate a buffer for the data it is going to produce.
206 * @param iMinSize minumum size of the requested buffer
207 * @return: pointer to target buffer if
3f2a1b1c 208 */
209 AliHLTUInt8_t* GetTargetBuffer(int iMinSize);
210
0c0c9d99 211 /**
212 * Set the segments for the data buffer.
213 * This is usually done after the component has written the data to the buffer,
214 * which was requested by the @ref GetTargetBuffer method. The component might
215 * produce different types of data, for each type a segment has to be defined
216 * which describes the data inside the bauffer.<br>
217 * The @ref AliHLTComponent_BlockData segment descriptor comes directly from the
218 * @ref AliHLTComponent::ProcessEvent method.
219 * @param pTgt the target buffer which the segments refer to
220 * @param arraySegments the output block descriptors of the component
221 * @param iSize size of the array
3f2a1b1c 222 */
223 int SetSegments(AliHLTUInt8_t* pTgt, AliHLTComponent_BlockData* arraySegments, int iSize);
224
0c0c9d99 225 /**
226 * Check if the data buffer is empty.
227 * @return 1 if empty, 0 if not
3f2a1b1c 228 */
229 int IsEmpty();
230
0c0c9d99 231 /**
232 * Get the total and maximum size of the buffer.
233 * Lets see if this is needed later
3f2a1b1c 234 */
235 //int GetTotalSize();
236
0c0c9d99 237 /**
238 * Get the number of segments
239 * @return number of segments
3f2a1b1c 240 */
241 int GetNofSegments();
242
0c0c9d99 243 /**
244 * Get the number of consumers
245 * @return number of consumers
3f2a1b1c 246 */
247 int GetNofConsumers();
248
0c0c9d99 249 /**
250 * Get the number of active consumers
251 * @return number of active consumers
3f2a1b1c 252 */
253 int GetNofActiveConsumers();
254
255 private:
0c0c9d99 256 /* lets see if this is needed
3f2a1b1c 257 AliHLTDataSegment* FindDataSegment(AliHLTComponent_DataType datatype);
0c0c9d99 258 */
259
260 /**
261 * Find those data segments which match the input types of a component.
262 * @param pConsumer the component which subscribes to the buffer
263 * @param tgtList the list to receive the data segment descriptors
264 * @return: number of data blocks which match the input data types
265 * of the consumer, neg. error code if failed <br>
266 * -EINVAL invalid parameter <br>
267 */
268 int FindMatchingDataSegments(const AliHLTComponent* pConsumer, vector<AliHLTDataSegment>& tgtList);
3f2a1b1c 269
0c0c9d99 270 /**
271 * Reset the data buffer.
272 * Removes all consumers back to the @ref fConsumers list
273 * and releases the Raw Buffer.
3f2a1b1c 274 */
275 int ResetDataBuffer();
276
277
278 ////////////////////////////////////////////////////////////////////////////////////////////////////////////////
279 // the data description
3f2a1b1c 280
0c0c9d99 281 // the data segments within this buffer
282 vector<AliHLTDataSegment> fSegments;
3f2a1b1c 283
0c0c9d99 284 // the list of all consumers which are going to subscribe to the buffer
285 vector<AliHLTConsumerDescriptor*> fConsumers;
286 // the list of all consumers which are currently subscribed to the buffer
287 vector<AliHLTConsumerDescriptor*> fActiveConsumers;
288 // the list of all consumers which are already released for the current event
289 vector<AliHLTConsumerDescriptor*> fReleasedConsumers;
3f2a1b1c 290
0c0c9d99 291 // the buffer instance
292 AliHLTRawBuffer* fpBuffer;
3f2a1b1c 293
0c0c9d99 294 // flags indicating the state of the buffer
295 AliHLTUInt32_t fFlags;
3f2a1b1c 296
0c0c9d99 297 ////////////////////////////////////////////////////////////////////////////////////////////////////////////////
298 // global buffer handling, internal use only
299
300 /**
301 * Create a raw buffer of a certain size.
302 * The function tries to find a buffer of the given size (or a bit bigger by a
303 * certain margin @ref fMargin) from the list of free buffers.
304 * If no buffer is available, a new one is created and added to the buffer handling.
305 * @param size min. size of the requested buffer
306 * @return pointer to raw buffer
3f2a1b1c 307 */
308 static AliHLTRawBuffer* CreateRawBuffer(AliHLTUInt32_t size);
309
0c0c9d99 310 /**
311 * Mark a buffer as free.
312 * After the Data Buffer has finnished using the raw buffer, it is released and
313 * added to the list of available buffers.
314 * @param pBuffer the raw buffer to release
315 * @return >=0 if succeeded, neg. error code if failed
3f2a1b1c 316 */
317 static int ReleaseRawBuffer(AliHLTRawBuffer* pBuffer);
318
0c0c9d99 319 /**
320 * Deletes all the raw buffers.
321 * When the last Data Buffer object is destructed, all raw data buffers are relesed.
3f2a1b1c 322 */
323 static int DeleteRawBuffers();
324
0c0c9d99 325 /**
326 * Number of instances of AliHLTDataBuffer.
327 * The statice variable is incremented and decremented in the constructor/destructor.
328 * All internal data structures are cleaned up when the last instance is exiting.
329 */
3f2a1b1c 330 static int fNofInstances;
0c0c9d99 331 /** global list of free raw buffers */
3f2a1b1c 332 static vector<AliHLTRawBuffer*> fFreeBuffers;
0c0c9d99 333 /** global list of currently active raw buffers */
3f2a1b1c 334 static vector<AliHLTRawBuffer*> fActiveBuffers;
0c0c9d99 335 /** determines the raw buffer size margin at buffer requests */
3f2a1b1c 336 static AliHLTUInt32_t fMargin;
337
0c0c9d99 338 /** global instance to HLT logging class for static methods */
339 static AliHLTLogging fgLogging;
3f2a1b1c 340
0c0c9d99 341 ////////////////////////////////////////////////////////////////////////////////////////////////////////////////
342 // internal helper functions
343
344 /**
345 * Find the consumer descriptor for a certain component and data type in
346 * a list of consumers.<br>
347 * <b>Note:</b> There are three lists which contain the consumers in the different states.
348 * @param pConsumer pointer to consumer component
349 * @param list list where to search for the consumer
350 */
351 AliHLTConsumerDescriptor* FindConsumer(const AliHLTComponent* pConsumer, vector<AliHLTConsumerDescriptor*> &list);
352
353 /**
354 * Change the state of a consumer.
355 * The state of a consumer is determined by the list it is strored in, the method moves a consumer from
356 * the source to the target list.
357 * @param pDesc pointer to consumer descriptor
358 * @param srcList list where the consumer is currently to be found
359 * @param tgtList list where to move the consumer
360 */
3f2a1b1c 361 int ChangeConsumerState(AliHLTConsumerDescriptor* pDesc, vector<AliHLTConsumerDescriptor*> &srcList, vector<AliHLTConsumerDescriptor*> &tgtList);
362
0c0c9d99 363 /**
364 * Cleanup a consumer list.
365 * Release all allocated data structures. <b>Note:</b> Not the component itself!
366 */
3f2a1b1c 367 int CleanupConsumerList();
368
369 ClassDef(AliHLTDataBuffer, 0)
370};
371#endif // ALIHLTDATABUFFER_H