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