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;
30 /** list of AliHLTConsumerDescriptor pointers */
31 typedef vector<AliHLTConsumerDescriptor*> AliHLTConsumerDescriptorPList;
33 typedef AliHLTUInt8_t* AliHLTUInt8Pointer_t;
36 * @class AliHLTDataBuffer
37 * @brief Handling of data buffers for the HLT.
39 * The class provides handling of data buffers for HLT tasks. Each task gets
40 * its own Data Buffer instance. The buffer is grouped into different data
41 * segments according to the output of the component.<br>
42 * The Data Buffer keeps control over the data requests of the 'child'
43 * components. Each component can subscribe to a certain segment of the data
44 * buffer. It's state is then changed from 'reserved' to 'active'. After the
45 * data processing, the component has to release the segment and it's state is
46 * set to 'processed'. If all components have requested and released their data,
47 * the Raw Buffer is released and pushed back in the list of available buffers.
49 * @note This class is only used for the @ref alihlt_system.
51 * @ingroup alihlt_system
53 class AliHLTDataBuffer : public TObject, public AliHLTLogging
56 //////////////////////////////////////////////////////////////////////////////
57 // constructors and destructors
59 /* standard constructor
63 virtual ~AliHLTDataBuffer();
65 //////////////////////////////////////////////////////////////////////////////
69 * Add component to the list of consumers
70 * @param pConsumer - a consumer of type AliHLTComponent
72 int SetConsumer(AliHLTComponent* pConsumer);
74 //////////////////////////////////////////////////////////////////////////////
75 // component to component communication
78 * Determine the number of matching data blocks for the component and a
79 * consumer component. <br>
80 * The first approach will support only one output data type for processing
82 * @param pConsumer the component which subscribes to the buffer
83 * @param tgtList (optional) the list to receive the data types
84 * @return: number of data blocks which match the input data types
85 * of the consumer, neg. error code if failed <br>
86 * -EINVAL invalid parameter <br>
88 int FindMatchingDataBlocks(const AliHLTComponent* pConsumer,
89 AliHLTComponentDataTypeList* tgtList=NULL);
92 * Subscribe to a segment of the data buffer.
93 * The function prepares the block descriptor for subsequent use with the
94 * AliHLTComponent::ProcessEvent method, the method can prepare several block
95 * descriptors up to the array size specified by iArraySize. The return value
96 * is independent from the array size the number of block descriptors which
97 * would have been prepared if there was enough space in the array<br>
98 * The method is used by the consumer component.
99 * @param pConsumer the component which subscribes to the buffer
100 * @param blockDescList block descriptor vector to be filled
101 * @return: number of matching data blocks, neg. error code if failed<br>
102 * -EACCESS the consumer state can't be changed (activated)
103 * -EBADF unresolved data segments <br>
104 * -ENOENT consumer component not found <br>
105 * -ENODATA data buffer does not have raw data <br>
106 * -EINVAL invalid parameter <br>
108 int Subscribe(const AliHLTComponent* pConsumer,
109 AliHLTComponentBlockDataList& blockDescList);
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 * @param pOwnerTask task owning this buffer
120 * @return: >0 if success, negative error code if failed <br>
121 * -EACCESS the consumer state can not be changed (de-activated)
122 * -ENOENT consumer has not subscribed to the buffer <br>
123 * -EINVAL invalid parameter <br>
125 int Release(AliHLTComponentBlockData* pBlockDesc, const AliHLTComponent* pConsumer,
126 const AliHLTTask* pOwnerTask);
129 * Release a forwarded data block.
131 int ReleaseForwardedBlock(AliHLTComponentBlockData* pBlockDesc,
132 const AliHLTTask* pOwnerTask);
135 * Register an input data block for forwarding.
136 * Consumer of this data buffer subscribe to forwarded data blocks in te same way.
137 * Forwarded data blocks are released when the last consumer has released the
139 * @param pSrcTask original source task of the data block
140 * @param pBlockDesc descriptor of the data segment
142 int Forward(AliHLTTask* pSrcTask, AliHLTComponentBlockData* pBlockDesc);
145 * Get a target buffer of minimum size iMinSize.
146 * The method is used by the component which owns the Data Buffer to
147 * allocate a buffer for the data it is going to produce.
148 * @param iMinSize minumum size of the requested buffer
149 * @return: pointer to target buffer if
151 AliHLTUInt8_t* GetTargetBuffer(int iMinSize);
154 * Set the segments for the data buffer.
155 * This is usually done after the component has written the data to the buffer,
156 * which was requested by the @ref GetTargetBuffer method. The component might
157 * produce different types of data, for each type a segment has to be defined
158 * which describes the data inside the buffer.<br>
159 * The @ref AliHLTComponentBlockData segment descriptor comes directly from
160 * the @ref AliHLTComponent::ProcessEvent method.
161 * @param pTgt the target buffer which the segments refer to
162 * @param arraySegments the output block descriptors of the component
163 * @param iSize size of the array
165 int SetSegments(AliHLTUInt8_t* pTgt, AliHLTComponentBlockData* arraySegments, int iSize);
168 * Check if the data buffer is empty.
169 * @return 1 if empty, 0 if not
174 * Get the total and maximum size of the buffer.
175 * Lets see if this is needed later
177 //int GetTotalSize();
180 * Get the number of segments including the forwarded data blocks.
181 * @return number of segments
183 int GetNofSegments();
186 * Get the total number of consumers.
187 * This gives the number of consumers regardless of their state.
188 * @return number of consumers
190 int GetNofConsumers();
193 * Get the number of consumers which still need to be processed during
195 * @return number of consumers
197 int GetNofPendingConsumers();
200 * Get the number of consumers currently under processing.
201 * @return number of active consumers
203 int GetNofActiveConsumers();
206 * Check if a consumer is already in the list
207 * @param pConsumer pointer to consumer component
208 * @param bAllLists search in all lists if 1
209 * search only in fConsumer list if 0
210 * @return 1 if found, 0 if not
212 int FindConsumer(const AliHLTComponent* pConsumer, int bAllLists=1);
215 * Public method to reset the buffer.
216 * Eventually with some additional checks. In normal operation,
217 * an external reset should not be necessary.
222 * Set local logging level
223 * logging filter for individual object
225 void SetLocalLoggingLevel(AliHLTComponentLogSeverity level)
226 {fgLogging.SetLocalLoggingLevel(level); AliHLTLogging::SetLocalLoggingLevel(level);}
229 * Print summary of the global buffer management.
231 static int PrintStatistics();
234 * Set the global event count.
235 * The event count is deployed to find buffers which have not been used
236 * for a while. In such a case to policy to find an appropriate buffer is
239 static int SetGlobalEventCount(AliHLTUInt32_t eventCount) {fgEventCount=eventCount; return 0;}
242 * @class AliHLTDataSegment
243 * @brief Descriptor of a data segment within the buffer.
245 class AliHLTDataSegment {
246 friend class AliHLTDataBuffer;
247 friend class AliHLTConsumerDescriptor;
251 fDataType(kAliHLTVoidDataType),
259 AliHLTDataSegment(AliHLTUInt8_t* ptr, AliHLTUInt32_t offset, AliHLTUInt32_t size)
261 fDataType(kAliHLTVoidDataType),
263 fSegmentOffset(offset),
269 AliHLTDataSegment(void* ptr, AliHLTUInt32_t offset, AliHLTUInt32_t size)
271 fDataType(kAliHLTVoidDataType),
272 fPtr((AliHLTUInt8_t*)ptr),
273 fSegmentOffset(offset),
279 AliHLTDataSegment(void* ptr, AliHLTUInt32_t offset, AliHLTUInt32_t size, AliHLTComponentDataType dt, AliHLTUInt32_t spec)
282 fPtr((AliHLTUInt8_t*)ptr),
283 fSegmentOffset(offset),
289 AliHLTUInt8_t* GetPtr() const {return (AliHLTUInt8_t*)*this;}
291 AliHLTUInt32_t GetSize() const {return fSegmentSize;}
293 int operator==(const AliHLTDataSegment& seg) const
295 return (fPtr+fSegmentOffset==seg.fPtr+seg.fSegmentOffset) && (fSegmentSize==seg.fSegmentSize);
297 operator AliHLTUInt8_t*() const {return fPtr+fSegmentOffset;}
300 /** the data type of this segment */
301 AliHLTComponentDataType fDataType; // see above
302 /** pointer to the buffer */
303 AliHLTUInt8Pointer_t fPtr; //!transient
304 /** offset in byte within the data buffer */
305 AliHLTUInt32_t fSegmentOffset; // see above
306 /** size of the actual content */
307 AliHLTUInt32_t fSegmentSize; // see above
308 /** data specification */
309 AliHLTUInt32_t fSpecification; // see above
312 class AliHLTRawBuffer;
313 typedef vector<AliHLTRawBuffer*> AliHLTRawBufferPList;
316 * @class AliHLTRawPage
317 * Memory allocation is organized in pages of a fixed size. Within a
318 * page, AliHLTRawBuffer chunks are created.
320 class AliHLTRawPage : public AliHLTLogging {
322 /** standard constructor */
323 AliHLTRawPage() : fSize(0), fPtr(NULL), fFreeBuffers(), fUsedBuffers() {}
325 AliHLTRawPage(AliHLTUInt32_t pagesize);
327 virtual ~AliHLTRawPage();
329 /** alloc a buffer of specified size from the global pages*/
330 static AliHLTRawBuffer* GlobalAlloc(AliHLTUInt32_t size, int verbosity=0);
331 /** find buffer in the global pages */
332 static AliHLTRawPage* FindPage(AliHLTRawBuffer* buffer);
333 /** cleanup the global pages */
334 static int GlobalClean();
335 /** adjust global page size */
336 static void SetGlobalPageSize(AliHLTUInt32_t size) {fgGlobalPageSize=size;}
337 /** find next page after prev, or first page */
338 static AliHLTRawPage* NextPage(AliHLTRawPage* prev=NULL);
340 /** alloc a buffer of specified size */
341 AliHLTRawBuffer* Alloc(AliHLTUInt32_t size);
342 /** free a buffer and merge consecutive free buffers */
343 int Free(AliHLTRawBuffer* pBuffer);
344 /** set the size of a raw buffer and release the remaining part */
345 int SetSize(AliHLTRawBuffer* pBuffer, AliHLTUInt32_t size);
346 /// check if the buffer is in this page
347 bool HasBuffer(AliHLTRawBuffer* pBuffer);
349 AliHLTUInt32_t Size() const {return fSize;}
350 AliHLTUInt32_t Capacity() const;
351 bool IsUsed() const {return fUsedBuffers.size()>0;}
352 bool IsFragmented() const {return (fFreeBuffers.size()+fUsedBuffers.size())>1;}
355 * Print page information
357 void Print(const char* option);
360 /** copy constructor prohibited */
361 AliHLTRawPage(const AliHLTRawPage&);
362 /** assignment operator prohibited */
363 AliHLTRawPage& operator=(const AliHLTRawPage&);
365 /// list of global pages
366 static vector<AliHLTDataBuffer::AliHLTRawPage*> fgGlobalPages; //! transient
367 /// pages size of global pages
368 static AliHLTUInt32_t fgGlobalPageSize; //! transient
371 AliHLTUInt32_t fSize; // see above
372 /** the memory segment */
373 AliHLTUInt8_t* fPtr; //! transient
375 /** list of free buffers */
376 AliHLTRawBufferPList fFreeBuffers; //! transient
377 /** list of used buffers */
378 AliHLTRawBufferPList fUsedBuffers; //! transient
382 * @class AliHLTRawBuffer
383 * @brief Descriptor of the raw data buffer which can host several segments.
385 class AliHLTRawBuffer {
387 /** standard constructor */
388 AliHLTRawBuffer() : fSize(0), fTotalSize(0), fExternalPtr(NULL), fPtr(NULL), fLastEventCount(0) {}
390 AliHLTRawBuffer(AliHLTUInt32_t size);
392 AliHLTRawBuffer(AliHLTUInt32_t size, AliHLTUInt8_t* buffer);
394 virtual ~AliHLTRawBuffer();
397 * Use a fraction of the buffer.
398 * @param size size in bytes to be used
399 * @return pointer to buffer
401 AliHLTUInt8_t* UseBuffer(AliHLTUInt32_t size);
404 * split a buffer at specified size
405 * only possible for buffers with external memory
407 AliHLTRawBuffer* Split(AliHLTUInt32_t size);
410 * Check whether buffer fits for a request.
411 * A buffer fits if it is at least of the requested size and at most
412 * the requested size plus a margin. The margin increases with the
413 * number of events the buffer has not been used.
414 * @param size size of the request in bytes
415 * @return 1 if buffer is big enough, 0 if not
417 int CheckSize(AliHLTUInt32_t size) const;
420 * Get used size of the buffer
422 AliHLTUInt32_t GetUsedSize() const {return fSize;}
425 * Get total size of the buffer
427 AliHLTUInt32_t GetTotalSize() const {return fTotalSize;}
430 * Get pointer of data buffer
432 AliHLTUInt8_t* GetPointer() const {return fPtr;}
435 * Write check pattern
437 int WritePattern(const char* pattern, int size);
442 int CheckPattern(const char* pattern, int size) const;
446 * Data buffer remains allocated, used size set to 0
451 * Merge buffer with succeeding buffer.
452 * Only possible if the buffers are consecutive with out any gap.
454 int Merge(const AliHLTRawBuffer& succ);
457 * Print buffer information
459 void Print(const char* option);
461 int operator==(void*) const;
462 int operator==(AliHLTUInt8_t* ptr) const {return fPtr==ptr;}
463 int operator<(void*) const;
464 int operator<=(void*) const;
465 int operator>(void*) const;
466 int operator-(void*) const;
467 int operator<(const AliHLTRawBuffer&) const;
468 int operator<=(const AliHLTRawBuffer&) const;
469 int operator>(const AliHLTRawBuffer&) const;
471 operator void*() const {return fPtr;}
472 operator AliHLTUInt8_t*() const {return fPtr;}
475 /** copy constructor prohibited */
476 AliHLTRawBuffer(const AliHLTRawBuffer&);
477 /** assignment operator prohibited */
478 AliHLTRawBuffer& operator=(const AliHLTRawBuffer&);
480 /** size of the currently occupied partition of the buffer */
481 AliHLTUInt32_t fSize; // see above
482 /** total size of the buffer, including safety margin */
483 AliHLTUInt32_t fTotalSize; // see above
484 /** optional external buffer */
485 AliHLTUInt8_t* fExternalPtr; //! transient
486 /** the buffer, external or allocated */
487 AliHLTUInt8_t* fPtr; //! transient
488 /** last event count where the buffer has been used */
489 AliHLTUInt32_t fLastEventCount; //! transient
493 /** copy constructor prohibited */
494 AliHLTDataBuffer(const AliHLTDataBuffer&);
495 /** assignment operator prohibited */
496 AliHLTDataBuffer& operator=(const AliHLTDataBuffer&);
498 /* lets see if this is needed
499 AliHLTDataSegment* FindDataSegment(AliHLTComponentDataType datatype);
503 * Find those data segments which match the input types of a component.
504 * @param pConsumer the component which subscribes to the buffer
505 * @param tgtList the list to receive the data segment descriptors
506 * @return: number of data blocks which match the input data types
507 * of the consumer, neg. error code if failed <br>
508 * -EINVAL invalid parameter <br>
510 int FindMatchingDataSegments(const AliHLTComponent* pConsumer,
511 vector<AliHLTDataBuffer::AliHLTDataSegment>& tgtList);
514 // 2010-02-01 make function protected in order to be used from unit test
516 * Reset the data buffer.
517 * Removes all consumers back to the @ref fConsumers list, deletes
518 * segments and releases the Raw Buffer.
520 int ResetDataBuffer();
523 //////////////////////////////////////////////////////////////////////////////
525 // the data description
527 // the data segments within this buffer
528 vector<AliHLTDataSegment> fSegments; // see above
530 // the list of all consumers which are going to subscribe to the buffer
531 AliHLTConsumerDescriptorPList fConsumers; // see above
532 // the list of all consumers which are currently subscribed to the buffer
533 AliHLTConsumerDescriptorPList fActiveConsumers; // see above
534 // the list of all consumers which are already released for the current event
535 AliHLTConsumerDescriptorPList fReleasedConsumers; // see above
537 // the buffer instance
538 AliHLTRawBuffer* fpBuffer; //! transient
540 // flags indicating the state of the buffer
541 AliHLTUInt32_t fFlags; // see above
543 /** list of tasks with forwarded data blocks */
544 vector<AliHLTTask*> fForwardedSegmentSources; //! transient
546 /** list of forwarded block descriptors */
547 vector<AliHLTDataSegment> fForwardedSegments; //! transient
549 //////////////////////////////////////////////////////////////////////////////
550 // global buffer handling, internal use only
553 * Create a raw buffer of a certain size.
554 * The function tries to find a buffer of the given size (or a bit bigger by a
555 * certain margin @ref fgMargin) from the list of free buffers.
556 * If no buffer is available, a new one is created and added to the buffer handling.
557 * @param size min. size of the requested buffer
558 * @return pointer to raw buffer
560 static AliHLTRawBuffer* CreateRawBuffer(AliHLTUInt32_t size);
563 * Set the data size of a raw buffer after it has been filled by
566 int SetRawBufferDataSize(AliHLTRawBuffer* pBuffer, AliHLTUInt32_t size) const;
569 * Mark a buffer as free.
570 * After the Data Buffer has finnished using the raw buffer, it is released
571 * and added to the list of available buffers.
572 * @param pBuffer the raw buffer to release
573 * @return >=0 if succeeded, neg. error code if failed
575 static int ReleaseRawBuffer(AliHLTRawBuffer* pBuffer);
578 * Deletes all the raw buffers.
579 * When the last Data Buffer object is destructed, all raw data buffers are
582 static int DeleteRawBuffers();
585 * Number of instances of AliHLTDataBuffer.
586 * The statice variable is incremented and decremented in the constructor/
587 * destructor. All internal data structures are cleaned up when the last
588 * instance is exiting.
590 static int fgNofInstances; // see above
591 /** global list of free raw buffers */
592 static vector<AliHLTRawBuffer*> fgFreeBuffers; // see above
593 /** global list of currently active raw buffers */
594 static vector<AliHLTRawBuffer*> fgActiveBuffers; // see above
595 /** determines the raw buffer size margin at buffer requests */
596 static AliHLTUInt32_t fgMargin; // see above
598 /** global instance to HLT logging class for static methods */
599 static AliHLTLogging fgLogging; // see above
601 /** size of the safety pattern */
602 static const Int_t fgkSafetyPatternSize; // see above
604 /** the safety pattern */
605 static const char fgkSafetyPattern[]; //!transient
607 static AliHLTUInt32_t fgEventCount; //!transient
609 //////////////////////////////////////////////////////////////////////////////
610 // internal helper functions
613 * Find the consumer descriptor for a certain component and data type in
614 * a list of consumers.<br>
615 * <b>Note:</b> There are three lists which contain the consumers in the
617 * @param pConsumer pointer to consumer component
618 * @param list list where to search for the consumer
620 AliHLTConsumerDescriptor* FindConsumer(const AliHLTComponent* pConsumer,
621 AliHLTConsumerDescriptorPList &list) const;
624 * Change the state of a consumer.
625 * The state of a consumer is determined by the list it is strored in, the
626 * method moves a consumer from the source to the target list.
627 * @param pDesc pointer to consumer descriptor
628 * @param srcList list where the consumer is currently to be found
629 * @param tgtList list where to move the consumer
631 int ChangeConsumerState(AliHLTConsumerDescriptor* pDesc,
632 AliHLTConsumerDescriptorPList &srcList,
633 AliHLTConsumerDescriptorPList &tgtList);
636 * Cleanup a consumer list.
637 * Release all allocated data structures. <b>Note:</b> Not the component itself!
639 int CleanupConsumerList();
641 ClassDef(AliHLTDataBuffer, 1)
644 #endif // ALIHLTDATABUFFER_H