TPC default configuration
[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
b22e91eb 8/** @file AliHLTDataBuffer.h
9 @author Matthias Richter
10 @date
11 @brief Handling of Data Buffers for HLT components.
12 @note The class is used in Offline (AliRoot) context
13*/
3f2a1b1c 14
30338a30 15// see below for class documentation
16// or
17// refer to README to build package
18// or
19// visit http://web.ift.uib.no/~kjeks/doc/alice-hlt
20
8ede8717 21#include <vector>
3f2a1b1c 22#include "AliHLTLogging.h"
23#include "AliHLTDataTypes.h"
3f2a1b1c 24#include "TObject.h"
3f2a1b1c 25
b22e91eb 26class AliHLTComponent;
6235cd38 27class AliHLTConsumerDescriptor;
3f2a1b1c 28
0c0c9d99 29/**
bfccbf68 30 * @class AliHLTDataBuffer
31 * @brief Handling of data buffers for the HLT.
b22e91eb 32 *
70ed7d01 33 * The class provides handling of data buffers for HLT tasks. Each task gets
34 * its own Data Buffer instance. The buffer is grouped into different data
35 * segments according to the output of the component.<br>
36 * The Data Buffer keeps control over the data requests of the 'child'
37 * components. Each component can subscribe to a certain segment of the data
38 * buffer. It's state is then changed from 'reserved' to 'active'. After the
39 * data processing, the component has to release the segment and it's state is
40 * set to 'processed'. If all components have requested and released their data,
41 * the Raw Buffer is released and pushed back in the list of available buffers.
b22e91eb 42 *
43 * @note This class is only used for the @ref alihlt_system.
44 *
45 * @ingroup alihlt_system
0c0c9d99 46 */
6235cd38 47class AliHLTDataBuffer : public TObject, public AliHLTLogging
48{
3f2a1b1c 49 public:
70ed7d01 50 //////////////////////////////////////////////////////////////////////////////
6235cd38 51 // constructors and destructors
0c0c9d99 52
53 /* standard constructor
54 */
3f2a1b1c 55 AliHLTDataBuffer();
85869391 56 /** not a valid copy constructor, defined according to effective C++ style */
57 AliHLTDataBuffer(const AliHLTDataBuffer&);
58 /** not a valid assignment op, but defined according to effective C++ style */
59 AliHLTDataBuffer& operator=(const AliHLTDataBuffer&);
60 /** destructor */
3f2a1b1c 61 virtual ~AliHLTDataBuffer();
62
70ed7d01 63 //////////////////////////////////////////////////////////////////////////////
3f2a1b1c 64 // initialization
65
0c0c9d99 66 /**
67 * Add component to the list of consumers
68 * @param pConsumer - a consumer of type AliHLTComponent
3f2a1b1c 69 */
0c0c9d99 70 int SetConsumer(AliHLTComponent* pConsumer);
3f2a1b1c 71
70ed7d01 72 //////////////////////////////////////////////////////////////////////////////
3f2a1b1c 73 // component to component communication
74
0c0c9d99 75 /**
70ed7d01 76 * Determine the number of matching data blocks for the component and a
77 * consumer component. <br>
78 * The first approach will support only one output data type for processing
79 * components.
0c0c9d99 80 * @param pConsumer the component which subscribes to the buffer
81 * @param tgtList (optional) the list to receive the data types
82 * @return: number of data blocks which match the input data types
83 * of the consumer, neg. error code if failed <br>
84 * -EINVAL invalid parameter <br>
3f2a1b1c 85 */
70ed7d01 86 int FindMatchingDataBlocks(const AliHLTComponent* pConsumer,
87 vector<AliHLTComponentDataType>* tgtList=NULL);
0c0c9d99 88
89 /**
90 * Subscribe to a segment of the data buffer.
70ed7d01 91 * The function prepares the block descriptor for subsequent use with the
92 * AliHLTComponent::ProcessEvent method, the method can prepare several block
93 * descriptors up to the array size specified by iArraySize. The return value
94 * is independent from the array size the number of block descriptors which
95 * would have been prepared if there was enough space in the array<br>
0c0c9d99 96 * The method is used by the consumer component.
97 * @param pConsumer the component which subscribes to the buffer
98 * @param arrayBlockDesc pointer to block descriptor to be filled
99 * @param iArraySize size of the block descriptor array
70ed7d01 100 * @return: number of matching data blocks, neg. error code if failed<br>
101 * -EACCESS the consumer state can't be changed (activated)
0c0c9d99 102 * -EBADF unresolved data segments <br>
103 * -ENOENT consumer component not found <br>
104 * -ENODATA data buffer does not have raw data <br>
105 * -EINVAL invalid parameter <br>
106 */
70ed7d01 107 int Subscribe(const AliHLTComponent* pConsumer,
108 AliHLTComponentBlockData* arrayBlockDesc,
109 int iArraySize);
0c0c9d99 110
111 /**
112 * Release an instance of the data buffer.
113 * Resets the variables of the block descriptor.
114 * If all buffer segments are released, the Data Buffer is reseted
115 * and the Raw Buffer released.<br>
116 * The method is used by the consumer component.
117 * @param pBlockDesc descriptor of the data segment
118 * @param pConsumer the component which subscribes to the buffer
119 * @return: >0 if success, negative error code if failed <br>
70ed7d01 120 * -EACCESS the consumer state can not be changed (de-activated)
121 * -ENOENT consumer has not subscribed to the buffer <br>
0c0c9d99 122 * -EINVAL invalid parameter <br>
3f2a1b1c 123 */
8ede8717 124 int Release(AliHLTComponentBlockData* pBlockDesc, const AliHLTComponent* pConsumer);
3f2a1b1c 125
0c0c9d99 126 /**
127 * Get a target buffer of minimum size iMinSize.
128 * The method is used by the component which owns the Data Buffer to
129 * allocate a buffer for the data it is going to produce.
130 * @param iMinSize minumum size of the requested buffer
131 * @return: pointer to target buffer if
3f2a1b1c 132 */
133 AliHLTUInt8_t* GetTargetBuffer(int iMinSize);
134
0c0c9d99 135 /**
136 * Set the segments for the data buffer.
137 * This is usually done after the component has written the data to the buffer,
138 * which was requested by the @ref GetTargetBuffer method. The component might
139 * produce different types of data, for each type a segment has to be defined
2d7ff710 140 * which describes the data inside the buffer.<br>
70ed7d01 141 * The @ref AliHLTComponentBlockData segment descriptor comes directly from
142 * the @ref AliHLTComponent::ProcessEvent method.
0c0c9d99 143 * @param pTgt the target buffer which the segments refer to
144 * @param arraySegments the output block descriptors of the component
145 * @param iSize size of the array
3f2a1b1c 146 */
8ede8717 147 int SetSegments(AliHLTUInt8_t* pTgt, AliHLTComponentBlockData* arraySegments, int iSize);
3f2a1b1c 148
0c0c9d99 149 /**
150 * Check if the data buffer is empty.
151 * @return 1 if empty, 0 if not
3f2a1b1c 152 */
153 int IsEmpty();
154
0c0c9d99 155 /**
156 * Get the total and maximum size of the buffer.
157 * Lets see if this is needed later
3f2a1b1c 158 */
159 //int GetTotalSize();
160
0c0c9d99 161 /**
162 * Get the number of segments
163 * @return number of segments
3f2a1b1c 164 */
165 int GetNofSegments();
166
0c0c9d99 167 /**
168 * Get the number of consumers
169 * @return number of consumers
3f2a1b1c 170 */
171 int GetNofConsumers();
172
0c0c9d99 173 /**
174 * Get the number of active consumers
175 * @return number of active consumers
3f2a1b1c 176 */
177 int GetNofActiveConsumers();
178
9ce4bf4a 179 /**
180 * Check if a consumer is already in the list
181 * @param pConsumer pointer to consumer component
182 * @param bAllLists search in all lists if 1
183 * search only in fConsumer list if 0
184 * @return 1 if found, 0 if not
185 */
186 int FindConsumer(AliHLTComponent* pConsumer, int bAllLists=1);
187
188 /**
189 * Public method to reset the buffer.
190 * Eventually with some additional checks. In normal operation,
191 * an external reset should not be necessary.
192 */
193 int Reset();
194
6235cd38 195 /**
965919c8 196 * @class AliHLTDataSegment
6235cd38 197 * @brief Descriptor of a data segment within the buffer.
198 */
66043029 199 class AliHLTDataSegment {
5df0cbb9 200 friend class AliHLTDataBuffer;
201 friend class AliHLTConsumerDescriptor;
66043029 202 public:
6235cd38 203 AliHLTDataSegment()
204 :
205 fDataType(),
206 fSegmentOffset(0),
207 fSegmentSize(0),
208 fSpecification(0)
209 {
210 memset(&fDataType, 0, sizeof(AliHLTComponentDataType));
211 }
212 AliHLTDataSegment(AliHLTUInt32_t offset, AliHLTUInt32_t size)
213 :
214 fDataType(),
215 fSegmentOffset(offset),
216 fSegmentSize(size),
217 fSpecification(0)
218 {
219 memset(&fDataType, 0, sizeof(AliHLTComponentDataType));
220 }
5df0cbb9 221 private:
6235cd38 222 /** the data type of this segment */
223 AliHLTComponentDataType fDataType; // see above
224 /** offset in byte within the data buffer */
225 AliHLTUInt32_t fSegmentOffset; // see above
226 /** size of the actual content */
227 AliHLTUInt32_t fSegmentSize; // see above
228 /** data specification */
229 AliHLTUInt32_t fSpecification; // see above
230 };
231
232 /**
965919c8 233 * @class AliHLTRawBuffer
6235cd38 234 * @brief Descriptor of the raw data buffer which can host several segments.
235 */
66043029 236 class AliHLTRawBuffer {
5df0cbb9 237 friend class AliHLTDataBuffer;
66043029 238 public:
239 /** standard constructor */
240 AliHLTRawBuffer() : fSize(0), fTotalSize(0), fPtr(NULL) {}
241 /** not a valid copy constructor, defined according to effective C++ style */
242 AliHLTRawBuffer(const AliHLTRawBuffer&) : fSize(0), fTotalSize(0), fPtr(NULL) {}
243 /** not a valid assignment op, but defined according to effective C++ style */
5df0cbb9 244 AliHLTRawBuffer& operator=(const AliHLTRawBuffer&) {return *this;}
66043029 245 /** standard destructor */
246 virtual ~AliHLTRawBuffer() {}
1e6e67ec 247
248 int operator==(void*);
249 int operator==(AliHLTUInt8_t* ptr) {return fPtr==ptr;}
250 int operator<=(void*);
251 int operator>(void*);
252 int operator-(void*);
253
254 operator void*() {return fPtr;}
255 operator AliHLTUInt8_t*() {return fPtr;}
256
5df0cbb9 257 private:
6235cd38 258 /** size of the currently occupied partition of the buffer */
259 AliHLTUInt32_t fSize; // see above
260 /** total size of the buffer, including safety margin */
261 AliHLTUInt32_t fTotalSize; // see above
262 /** the buffer */
1e6e67ec 263 AliHLTUInt8_t* fPtr; //! transient
6235cd38 264 };
265
3f2a1b1c 266 private:
0c0c9d99 267 /* lets see if this is needed
6235cd38 268 AliHLTDataSegment* FindDataSegment(AliHLTComponentDataType datatype);
0c0c9d99 269 */
270
271 /**
272 * Find those data segments which match the input types of a component.
273 * @param pConsumer the component which subscribes to the buffer
274 * @param tgtList the list to receive the data segment descriptors
275 * @return: number of data blocks which match the input data types
276 * of the consumer, neg. error code if failed <br>
277 * -EINVAL invalid parameter <br>
278 */
90ebac25 279 int FindMatchingDataSegments(const AliHLTComponent* pConsumer,
280 vector<AliHLTDataBuffer::AliHLTDataSegment>& tgtList);
3f2a1b1c 281
0c0c9d99 282 /**
283 * Reset the data buffer.
9ce4bf4a 284 * Removes all consumers back to the @ref fConsumers list, deletes
285 * segments and releases the Raw Buffer.
3f2a1b1c 286 */
287 int ResetDataBuffer();
288
70ed7d01 289 //////////////////////////////////////////////////////////////////////////////
290
3f2a1b1c 291 // the data description
3f2a1b1c 292
0c0c9d99 293 // the data segments within this buffer
70ed7d01 294 vector<AliHLTDataSegment> fSegments; // see above
3f2a1b1c 295
0c0c9d99 296 // the list of all consumers which are going to subscribe to the buffer
70ed7d01 297 vector<AliHLTConsumerDescriptor*> fConsumers; // see above
0c0c9d99 298 // the list of all consumers which are currently subscribed to the buffer
70ed7d01 299 vector<AliHLTConsumerDescriptor*> fActiveConsumers; // see above
0c0c9d99 300 // the list of all consumers which are already released for the current event
70ed7d01 301 vector<AliHLTConsumerDescriptor*> fReleasedConsumers; // see above
3f2a1b1c 302
0c0c9d99 303 // the buffer instance
70ed7d01 304 AliHLTRawBuffer* fpBuffer; //! transient
3f2a1b1c 305
0c0c9d99 306 // flags indicating the state of the buffer
70ed7d01 307 AliHLTUInt32_t fFlags; // see above
3f2a1b1c 308
70ed7d01 309 //////////////////////////////////////////////////////////////////////////////
0c0c9d99 310 // global buffer handling, internal use only
311
312 /**
313 * Create a raw buffer of a certain size.
314 * The function tries to find a buffer of the given size (or a bit bigger by a
9ddaea75 315 * certain margin @ref fgMargin) from the list of free buffers.
0c0c9d99 316 * If no buffer is available, a new one is created and added to the buffer handling.
317 * @param size min. size of the requested buffer
318 * @return pointer to raw buffer
3f2a1b1c 319 */
320 static AliHLTRawBuffer* CreateRawBuffer(AliHLTUInt32_t size);
321
0c0c9d99 322 /**
323 * Mark a buffer as free.
70ed7d01 324 * After the Data Buffer has finnished using the raw buffer, it is released
325 * and added to the list of available buffers.
0c0c9d99 326 * @param pBuffer the raw buffer to release
327 * @return >=0 if succeeded, neg. error code if failed
3f2a1b1c 328 */
329 static int ReleaseRawBuffer(AliHLTRawBuffer* pBuffer);
330
0c0c9d99 331 /**
332 * Deletes all the raw buffers.
70ed7d01 333 * When the last Data Buffer object is destructed, all raw data buffers are
334 * relesed.
3f2a1b1c 335 */
336 static int DeleteRawBuffers();
337
0c0c9d99 338 /**
339 * Number of instances of AliHLTDataBuffer.
70ed7d01 340 * The statice variable is incremented and decremented in the constructor/
341 * destructor. All internal data structures are cleaned up when the last
342 * instance is exiting.
0c0c9d99 343 */
70ed7d01 344 static int fgNofInstances; // see above
0c0c9d99 345 /** global list of free raw buffers */
70ed7d01 346 static vector<AliHLTRawBuffer*> fgFreeBuffers; // see above
0c0c9d99 347 /** global list of currently active raw buffers */
70ed7d01 348 static vector<AliHLTRawBuffer*> fgActiveBuffers; // see above
0c0c9d99 349 /** determines the raw buffer size margin at buffer requests */
70ed7d01 350 static AliHLTUInt32_t fgMargin; // see above
3f2a1b1c 351
0c0c9d99 352 /** global instance to HLT logging class for static methods */
70ed7d01 353 static AliHLTLogging fgLogging; // see above
3f2a1b1c 354
8451168b 355 /** size of the safety pattern */
356 static const Int_t fgkSafetyPatternSize; // see above
357
358 /** the safety pattern */
359 static const char fgkSafetyPattern[]; //!transient
360
70ed7d01 361 //////////////////////////////////////////////////////////////////////////////
0c0c9d99 362 // internal helper functions
363
364 /**
365 * Find the consumer descriptor for a certain component and data type in
366 * a list of consumers.<br>
70ed7d01 367 * <b>Note:</b> There are three lists which contain the consumers in the
368 * different states.
0c0c9d99 369 * @param pConsumer pointer to consumer component
370 * @param list list where to search for the consumer
371 */
70ed7d01 372 AliHLTConsumerDescriptor* FindConsumer(const AliHLTComponent* pConsumer,
373 vector<AliHLTConsumerDescriptor*> &list) const;
0c0c9d99 374
375 /**
376 * Change the state of a consumer.
70ed7d01 377 * The state of a consumer is determined by the list it is strored in, the
378 * method moves a consumer from the source to the target list.
0c0c9d99 379 * @param pDesc pointer to consumer descriptor
380 * @param srcList list where the consumer is currently to be found
381 * @param tgtList list where to move the consumer
382 */
70ed7d01 383 int ChangeConsumerState(AliHLTConsumerDescriptor* pDesc,
384 vector<AliHLTConsumerDescriptor*> &srcList,
385 vector<AliHLTConsumerDescriptor*> &tgtList);
3f2a1b1c 386
0c0c9d99 387 /**
388 * Cleanup a consumer list.
389 * Release all allocated data structures. <b>Note:</b> Not the component itself!
390 */
3f2a1b1c 391 int CleanupConsumerList();
392
393 ClassDef(AliHLTDataBuffer, 0)
394};
6235cd38 395
3f2a1b1c 396#endif // ALIHLTDATABUFFER_H