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 */
8 /** @file AliHLTDataBuffer.h
9 @author Matthias Richter
11 @brief Handling of Data Buffers for HLT components.
12 @note The class is used in Offline (AliRoot) context
15 // see below for class documentation
17 // refer to README to build package
19 // visit http://web.ift.uib.no/~kjeks/doc/alice-hlt
23 #include "AliHLTLogging.h"
24 #include "AliHLTDataTypes.h"
25 #include "AliHLTComponent.h"
27 class AliHLTConsumerDescriptor;
29 /** list of AliHLTConsumerDescriptor pointers */
30 typedef vector<AliHLTConsumerDescriptor*> AliHLTConsumerDescriptorPList;
33 * @class AliHLTDataBuffer
34 * @brief Handling of data buffers for the HLT.
36 * The class provides handling of data buffers for HLT tasks. Each task gets
37 * its own Data Buffer instance. The buffer is grouped into different data
38 * segments according to the output of the component.<br>
39 * The Data Buffer keeps control over the data requests of the 'child'
40 * components. Each component can subscribe to a certain segment of the data
41 * buffer. It's state is then changed from 'reserved' to 'active'. After the
42 * data processing, the component has to release the segment and it's state is
43 * set to 'processed'. If all components have requested and released their data,
44 * the Raw Buffer is released and pushed back in the list of available buffers.
46 * @note This class is only used for the @ref alihlt_system.
48 * @ingroup alihlt_system
50 class AliHLTDataBuffer : public TObject, public AliHLTLogging
53 //////////////////////////////////////////////////////////////////////////////
54 // constructors and destructors
56 /* standard constructor
60 virtual ~AliHLTDataBuffer();
62 //////////////////////////////////////////////////////////////////////////////
66 * Add component to the list of consumers
67 * @param pConsumer - a consumer of type AliHLTComponent
69 int SetConsumer(AliHLTComponent* pConsumer);
71 //////////////////////////////////////////////////////////////////////////////
72 // component to component communication
75 * Determine the number of matching data blocks for the component and a
76 * consumer component. <br>
77 * The first approach will support only one output data type for processing
79 * @param pConsumer the component which subscribes to the buffer
80 * @param tgtList (optional) the list to receive the data types
81 * @return: number of data blocks which match the input data types
82 * of the consumer, neg. error code if failed <br>
83 * -EINVAL invalid parameter <br>
85 int FindMatchingDataBlocks(const AliHLTComponent* pConsumer,
86 AliHLTComponentDataTypeList* tgtList=NULL);
89 * Subscribe to a segment of the data buffer.
90 * The function prepares the block descriptor for subsequent use with the
91 * AliHLTComponent::ProcessEvent method, the method can prepare several block
92 * descriptors up to the array size specified by iArraySize. The return value
93 * is independent from the array size the number of block descriptors which
94 * would have been prepared if there was enough space in the array<br>
95 * The method is used by the consumer component.
96 * @param pConsumer the component which subscribes to the buffer
97 * @param arrayBlockDesc pointer to block descriptor to be filled
98 * @param iArraySize size of the block descriptor array
99 * @return: number of matching data blocks, neg. error code if failed<br>
100 * -EACCESS the consumer state can't be changed (activated)
101 * -EBADF unresolved data segments <br>
102 * -ENOENT consumer component not found <br>
103 * -ENODATA data buffer does not have raw data <br>
104 * -EINVAL invalid parameter <br>
106 int Subscribe(const AliHLTComponent* pConsumer,
107 AliHLTComponentBlockData* arrayBlockDesc,
111 * Release an instance of the data buffer.
112 * Resets the variables of the block descriptor.
113 * If all buffer segments are released, the Data Buffer is reseted
114 * and the Raw Buffer released.<br>
115 * The method is used by the consumer component.
116 * @param pBlockDesc descriptor of the data segment
117 * @param pConsumer the component which subscribes to the buffer
118 * @return: >0 if success, negative error code if failed <br>
119 * -EACCESS the consumer state can not be changed (de-activated)
120 * -ENOENT consumer has not subscribed to the buffer <br>
121 * -EINVAL invalid parameter <br>
123 int Release(AliHLTComponentBlockData* pBlockDesc, const AliHLTComponent* pConsumer);
126 * Get a target buffer of minimum size iMinSize.
127 * The method is used by the component which owns the Data Buffer to
128 * allocate a buffer for the data it is going to produce.
129 * @param iMinSize minumum size of the requested buffer
130 * @return: pointer to target buffer if
132 AliHLTUInt8_t* GetTargetBuffer(int iMinSize);
135 * Set the segments for the data buffer.
136 * This is usually done after the component has written the data to the buffer,
137 * which was requested by the @ref GetTargetBuffer method. The component might
138 * produce different types of data, for each type a segment has to be defined
139 * which describes the data inside the buffer.<br>
140 * The @ref AliHLTComponentBlockData segment descriptor comes directly from
141 * the @ref AliHLTComponent::ProcessEvent method.
142 * @param pTgt the target buffer which the segments refer to
143 * @param arraySegments the output block descriptors of the component
144 * @param iSize size of the array
146 int SetSegments(AliHLTUInt8_t* pTgt, AliHLTComponentBlockData* arraySegments, int iSize);
149 * Check if the data buffer is empty.
150 * @return 1 if empty, 0 if not
155 * Get the total and maximum size of the buffer.
156 * Lets see if this is needed later
158 //int GetTotalSize();
161 * Get the number of segments
162 * @return number of segments
164 int GetNofSegments();
167 * Get the total number of consumers.
168 * This gives the number of consumers regardless of their state.
169 * @return number of consumers
171 int GetNofConsumers();
174 * Get the number of consumers which still need to be processed during
176 * @return number of consumers
178 int GetNofPendingConsumers();
181 * Get the number of consumers currently under processing.
182 * @return number of active consumers
184 int GetNofActiveConsumers();
187 * Check if a consumer is already in the list
188 * @param pConsumer pointer to consumer component
189 * @param bAllLists search in all lists if 1
190 * search only in fConsumer list if 0
191 * @return 1 if found, 0 if not
193 int FindConsumer(AliHLTComponent* pConsumer, int bAllLists=1);
196 * Public method to reset the buffer.
197 * Eventually with some additional checks. In normal operation,
198 * an external reset should not be necessary.
203 * Set local logging level
204 * logging filter for individual object
206 void SetLocalLoggingLevel(AliHLTComponentLogSeverity level)
207 {fgLogging.SetLocalLoggingLevel(level); AliHLTLogging::SetLocalLoggingLevel(level);}
210 * @class AliHLTDataSegment
211 * @brief Descriptor of a data segment within the buffer.
213 class AliHLTDataSegment {
214 friend class AliHLTDataBuffer;
215 friend class AliHLTConsumerDescriptor;
224 memset(&fDataType, 0, sizeof(AliHLTComponentDataType));
226 AliHLTDataSegment(AliHLTUInt32_t offset, AliHLTUInt32_t size)
229 fSegmentOffset(offset),
233 memset(&fDataType, 0, sizeof(AliHLTComponentDataType));
237 /** the data type of this segment */
238 AliHLTComponentDataType fDataType; // see above
239 /** offset in byte within the data buffer */
240 AliHLTUInt32_t fSegmentOffset; // see above
241 /** size of the actual content */
242 AliHLTUInt32_t fSegmentSize; // see above
243 /** data specification */
244 AliHLTUInt32_t fSpecification; // see above
248 * @class AliHLTRawBuffer
249 * @brief Descriptor of the raw data buffer which can host several segments.
251 class AliHLTRawBuffer {
253 /** standard constructor */
254 AliHLTRawBuffer() : fSize(0), fTotalSize(0), fPtr(NULL) {}
256 AliHLTRawBuffer(AliHLTUInt32_t size);
258 virtual ~AliHLTRawBuffer();
261 * Use a fraction of the buffer.
262 * @param size size in bytes to be used
263 * @return pointer to buffer
265 AliHLTUInt8_t* UseBuffer(AliHLTUInt32_t size);
268 * Check whether buffer fits for a request.
269 * @param size size of the request in bytes
270 * @return 1 if buffer is big enough, 0 if not
272 int CheckSize(AliHLTUInt32_t size) const;
275 * Get used size of the buffer
277 AliHLTUInt32_t GetUsedSize() const {return fSize;}
280 * Get total size of the buffer
282 AliHLTUInt32_t GetTotalSize() const {return fTotalSize;}
285 * Get pointer of data buffer
287 AliHLTUInt8_t* GetPointer() const {return fPtr;}
290 * Write check pattern
292 int WritePattern(const char* pattern, int size);
297 int CheckPattern(const char* pattern, int size) const;
301 * Data buffer remains allocated, used size set to 0
305 int operator==(void*) const;
306 int operator==(AliHLTUInt8_t* ptr) const {return fPtr==ptr;}
307 int operator<=(void*) const;
308 int operator>(void*) const;
309 int operator-(void*) const;
311 operator void*() const {return fPtr;}
312 operator AliHLTUInt8_t*() const {return fPtr;}
315 /** copy constructor prohibited */
316 AliHLTRawBuffer(const AliHLTRawBuffer&);
317 /** assignment operator prohibited */
318 AliHLTRawBuffer& operator=(const AliHLTRawBuffer&);
320 /** size of the currently occupied partition of the buffer */
321 AliHLTUInt32_t fSize; // see above
322 /** total size of the buffer, including safety margin */
323 AliHLTUInt32_t fTotalSize; // see above
325 AliHLTUInt8_t* fPtr; //! transient
329 /** copy constructor prohibited */
330 AliHLTDataBuffer(const AliHLTDataBuffer&);
331 /** assignment operator prohibited */
332 AliHLTDataBuffer& operator=(const AliHLTDataBuffer&);
334 /* lets see if this is needed
335 AliHLTDataSegment* FindDataSegment(AliHLTComponentDataType datatype);
339 * Find those data segments which match the input types of a component.
340 * @param pConsumer the component which subscribes to the buffer
341 * @param tgtList the list to receive the data segment descriptors
342 * @return: number of data blocks which match the input data types
343 * of the consumer, neg. error code if failed <br>
344 * -EINVAL invalid parameter <br>
346 int FindMatchingDataSegments(const AliHLTComponent* pConsumer,
347 vector<AliHLTDataBuffer::AliHLTDataSegment>& tgtList);
350 * Reset the data buffer.
351 * Removes all consumers back to the @ref fConsumers list, deletes
352 * segments and releases the Raw Buffer.
354 int ResetDataBuffer();
356 //////////////////////////////////////////////////////////////////////////////
358 // the data description
360 // the data segments within this buffer
361 vector<AliHLTDataSegment> fSegments; // see above
363 // the list of all consumers which are going to subscribe to the buffer
364 AliHLTConsumerDescriptorPList fConsumers; // see above
365 // the list of all consumers which are currently subscribed to the buffer
366 AliHLTConsumerDescriptorPList fActiveConsumers; // see above
367 // the list of all consumers which are already released for the current event
368 AliHLTConsumerDescriptorPList fReleasedConsumers; // see above
370 // the buffer instance
371 AliHLTRawBuffer* fpBuffer; //! transient
373 // flags indicating the state of the buffer
374 AliHLTUInt32_t fFlags; // see above
376 //////////////////////////////////////////////////////////////////////////////
377 // global buffer handling, internal use only
380 * Create a raw buffer of a certain size.
381 * The function tries to find a buffer of the given size (or a bit bigger by a
382 * certain margin @ref fgMargin) from the list of free buffers.
383 * If no buffer is available, a new one is created and added to the buffer handling.
384 * @param size min. size of the requested buffer
385 * @return pointer to raw buffer
387 static AliHLTRawBuffer* CreateRawBuffer(AliHLTUInt32_t size);
390 * Mark a buffer as free.
391 * After the Data Buffer has finnished using the raw buffer, it is released
392 * and added to the list of available buffers.
393 * @param pBuffer the raw buffer to release
394 * @return >=0 if succeeded, neg. error code if failed
396 static int ReleaseRawBuffer(AliHLTRawBuffer* pBuffer);
399 * Deletes all the raw buffers.
400 * When the last Data Buffer object is destructed, all raw data buffers are
403 static int DeleteRawBuffers();
406 * Number of instances of AliHLTDataBuffer.
407 * The statice variable is incremented and decremented in the constructor/
408 * destructor. All internal data structures are cleaned up when the last
409 * instance is exiting.
411 static int fgNofInstances; // see above
412 /** global list of free raw buffers */
413 static vector<AliHLTRawBuffer*> fgFreeBuffers; // see above
414 /** global list of currently active raw buffers */
415 static vector<AliHLTRawBuffer*> fgActiveBuffers; // see above
416 /** determines the raw buffer size margin at buffer requests */
417 static AliHLTUInt32_t fgMargin; // see above
419 /** global instance to HLT logging class for static methods */
420 static AliHLTLogging fgLogging; // see above
422 /** size of the safety pattern */
423 static const Int_t fgkSafetyPatternSize; // see above
425 /** the safety pattern */
426 static const char fgkSafetyPattern[]; //!transient
428 //////////////////////////////////////////////////////////////////////////////
429 // internal helper functions
432 * Find the consumer descriptor for a certain component and data type in
433 * a list of consumers.<br>
434 * <b>Note:</b> There are three lists which contain the consumers in the
436 * @param pConsumer pointer to consumer component
437 * @param list list where to search for the consumer
439 AliHLTConsumerDescriptor* FindConsumer(const AliHLTComponent* pConsumer,
440 AliHLTConsumerDescriptorPList &list) const;
443 * Change the state of a consumer.
444 * The state of a consumer is determined by the list it is strored in, the
445 * method moves a consumer from the source to the target list.
446 * @param pDesc pointer to consumer descriptor
447 * @param srcList list where the consumer is currently to be found
448 * @param tgtList list where to move the consumer
450 int ChangeConsumerState(AliHLTConsumerDescriptor* pDesc,
451 AliHLTConsumerDescriptorPList &srcList,
452 AliHLTConsumerDescriptorPList &tgtList);
455 * Cleanup a consumer list.
456 * Release all allocated data structures. <b>Note:</b> Not the component itself!
458 int CleanupConsumerList();
460 ClassDef(AliHLTDataBuffer, 0)
463 #endif // ALIHLTDATABUFFER_H