4 #ifndef ALIHLTDATABUFFER_H
5 #define ALIHLTDATABUFFER_H
6 //* This file is property of and copyright by the *
7 //* ALICE Experiment at CERN, All rights reserved. *
8 //* See cxx source for full Copyright notice *
10 // @file AliHLTDataBuffer.h
11 // @author Matthias Richter
13 // @brief Handling of Data Buffers for HLT components.
14 // @note The class is used in Offline (AliRoot) context
18 #include "AliHLTLogging.h"
19 #include "AliHLTDataTypes.h"
20 #include "AliHLTComponent.h"
24 class AliHLTConsumerDescriptor;
27 /** list of AliHLTConsumerDescriptor pointers */
28 typedef vector<AliHLTConsumerDescriptor*> AliHLTConsumerDescriptorPList;
30 typedef AliHLTUInt8_t* AliHLTUInt8Pointer_t;
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 blockDescList block descriptor vector to be filled
98 * @return: number of matching data blocks, neg. error code if failed<br>
99 * -EACCESS the consumer state can't be changed (activated)
100 * -EBADF unresolved data segments <br>
101 * -ENOENT consumer component not found <br>
102 * -ENODATA data buffer does not have raw data <br>
103 * -EINVAL invalid parameter <br>
105 int Subscribe(const AliHLTComponent* pConsumer,
106 AliHLTComponentBlockDataList& blockDescList);
109 * Release an instance of the data buffer.
110 * Resets the variables of the block descriptor.
111 * If all buffer segments are released, the Data Buffer is reseted
112 * and the Raw Buffer released.<br>
113 * The method is used by the consumer component.
114 * @param pBlockDesc descriptor of the data segment
115 * @param pConsumer the component which subscribes to the buffer
116 * @param pOwnerTask task owning this buffer
117 * @return: >0 if success, negative error code if failed <br>
118 * -EACCESS the consumer state can not be changed (de-activated)
119 * -ENOENT consumer has not subscribed to the buffer <br>
120 * -EINVAL invalid parameter <br>
122 int Release(AliHLTComponentBlockData* pBlockDesc, const AliHLTComponent* pConsumer,
123 const AliHLTTask* pOwnerTask);
126 * Release a forwarded data block.
128 int ReleaseForwardedBlock(AliHLTComponentBlockData* pBlockDesc,
129 const AliHLTTask* pOwnerTask);
132 * Register an input data block for forwarding.
133 * Consumer of this data buffer subscribe to forwarded data blocks in te same way.
134 * Forwarded data blocks are released when the last consumer has released the
136 * @param pSrcTask original source task of the data block
137 * @param pBlockDesc descriptor of the data segment
139 int Forward(AliHLTTask* pSrcTask, AliHLTComponentBlockData* pBlockDesc);
142 * Get a target buffer of minimum size iMinSize.
143 * The method is used by the component which owns the Data Buffer to
144 * allocate a buffer for the data it is going to produce.
145 * @param iMinSize minumum size of the requested buffer
146 * @return: pointer to target buffer if
148 AliHLTUInt8_t* GetTargetBuffer(int iMinSize);
151 * Set the segments for the data buffer.
152 * This is usually done after the component has written the data to the buffer,
153 * which was requested by the @ref GetTargetBuffer method. The component might
154 * produce different types of data, for each type a segment has to be defined
155 * which describes the data inside the buffer.<br>
156 * The @ref AliHLTComponentBlockData segment descriptor comes directly from
157 * the @ref AliHLTComponent::ProcessEvent method.
158 * @param pTgt the target buffer which the segments refer to
159 * @param arraySegments the output block descriptors of the component
160 * @param iSize size of the array
162 int SetSegments(AliHLTUInt8_t* pTgt, AliHLTComponentBlockData* arraySegments, int iSize);
165 * Check if the data buffer is empty.
166 * @return 1 if empty, 0 if not
171 * Get the total and maximum size of the buffer.
172 * Lets see if this is needed later
174 //int GetTotalSize();
177 * Get the number of segments including the forwarded data blocks.
178 * @return number of segments
180 int GetNofSegments() const;
183 * Get the total number of consumers.
184 * This gives the number of consumers regardless of their state.
185 * @return number of consumers
187 int GetNofConsumers() const;
190 * Get the number of consumers which still need to be processed during
192 * @return number of consumers
194 int GetNofPendingConsumers() const;
197 * Get the number of consumers currently under processing.
198 * @return number of active consumers
200 int GetNofActiveConsumers() const;
203 * Check if a consumer is already in the list
204 * @param pConsumer pointer to consumer component
205 * @param bAllLists search in all lists if 1
206 * search only in fConsumer list if 0
207 * @return 1 if found, 0 if not
209 int FindConsumer(const AliHLTComponent* pConsumer, int bAllLists=1);
212 * Public method to reset the buffer.
213 * Eventually with some additional checks. In normal operation,
214 * an external reset should not be necessary.
219 * Print info about the buffer
221 virtual void Print(const char* option) const;
224 * Set local logging level
225 * logging filter for individual object
227 void SetLocalLoggingLevel(AliHLTComponentLogSeverity level)
228 {fgLogging.SetLocalLoggingLevel(level); AliHLTLogging::SetLocalLoggingLevel(level);}
231 * Print summary of the global buffer management.
233 static int PrintStatistics();
236 * Set the global event count.
237 * The event count is deployed to find buffers which have not been used
238 * for a while. In such a case to policy to find an appropriate buffer is
241 static int SetGlobalEventCount(AliHLTUInt32_t eventCount) {fgEventCount=eventCount; return 0;}
244 * @class AliHLTDataSegment
245 * @brief Descriptor of a data segment within the buffer.
247 class AliHLTDataSegment {
248 friend class AliHLTDataBuffer; // TODO: implement some getters/setters
252 fDataType(kAliHLTVoidDataType),
260 AliHLTDataSegment(AliHLTUInt8_t* ptr, AliHLTUInt32_t offset, AliHLTUInt32_t size)
262 fDataType(kAliHLTVoidDataType),
264 fSegmentOffset(offset),
270 AliHLTDataSegment(void* ptr, AliHLTUInt32_t offset, AliHLTUInt32_t size)
272 fDataType(kAliHLTVoidDataType),
273 fPtr(reinterpret_cast<AliHLTUInt8_t*>(ptr)),
274 fSegmentOffset(offset),
280 AliHLTDataSegment(void* ptr, AliHLTUInt32_t offset, AliHLTUInt32_t size, AliHLTComponentDataType dt, AliHLTUInt32_t spec)
283 fPtr(reinterpret_cast<AliHLTUInt8_t*>(ptr)),
284 fSegmentOffset(offset),
290 AliHLTDataSegment(const AliHLTDataSegment& src)
292 fDataType(src.fDataType),
294 fSegmentOffset(src.fSegmentOffset),
295 fSegmentSize(src.fSegmentSize),
296 fSpecification(src.fSpecification)
298 // AliHLTDataSegment just stores external pointers and properties
301 AliHLTDataSegment& operator=(const AliHLTDataSegment& src)
303 // AliHLTDataSegment just stores external pointers and properties
304 if (this==&src) return *this;
305 fDataType=src.fDataType;
307 fSegmentOffset=src.fSegmentOffset;
308 fSegmentSize=src.fSegmentSize;
309 fSpecification=src.fSpecification;
313 virtual ~AliHLTDataSegment() {}
315 AliHLTUInt8_t* GetPtr() const {return (AliHLTUInt8_t*)*this;}
317 AliHLTUInt32_t GetSize() const {return fSegmentSize;}
319 int operator==(const AliHLTDataSegment& seg) const
321 return (fPtr+fSegmentOffset==seg.fPtr+seg.fSegmentOffset) && (fSegmentSize==seg.fSegmentSize);
323 operator AliHLTUInt8_t*() const {return fPtr+fSegmentOffset;}
325 virtual void Print(const char* option) const;
328 /** the data type of this segment */
329 AliHLTComponentDataType fDataType; // see above
330 /** pointer to the buffer */
331 AliHLTUInt8Pointer_t fPtr; //!transient
332 /** offset in byte within the data buffer */
333 AliHLTUInt32_t fSegmentOffset; // see above
334 /** size of the actual content */
335 AliHLTUInt32_t fSegmentSize; // see above
336 /** data specification */
337 AliHLTUInt32_t fSpecification; // see above
342 * @class AliHLTForwardedDataSegment
343 * @brief Descriptor of a forwarded data segment.
344 * Contains in addition information about the parent of this forwarded
345 * block and the original data type and specification
347 class AliHLTForwardedDataSegment : public AliHLTDataSegment {
348 friend class AliHLTDataBuffer; // TODO: implement some getters/setters
350 AliHLTForwardedDataSegment()
351 : AliHLTDataSegment()
357 AliHLTForwardedDataSegment(AliHLTDataSegment& mySegment, AliHLTDataSegment& parentSegment, AliHLTTask* parentTask)
358 : AliHLTDataSegment(mySegment)
359 , fParentSegment(parentSegment)
360 , fParentTask(parentTask)
364 AliHLTForwardedDataSegment(const AliHLTForwardedDataSegment& src)
365 : AliHLTDataSegment(src),
366 fParentSegment(src.fParentSegment),
367 fParentTask(src.fParentTask)
369 // AliHLTForwardedDataSegment just stores external pointers and properties
372 AliHLTForwardedDataSegment& operator=(const AliHLTForwardedDataSegment& src)
374 // AliHLTForwardedDataSegment just stores external pointers and properties
375 AliHLTDataSegment::operator=(src);
376 fParentSegment=src.fParentSegment;
377 fParentTask=src.fParentTask;
381 virtual ~AliHLTForwardedDataSegment() {}
383 virtual void Print(const char* option) const;
386 /// description of the original segment
387 AliHLTDataSegment fParentSegment; // see above
389 AliHLTTask* fParentTask; //!transient
392 typedef vector<AliHLTDataBuffer::AliHLTDataSegment> AliHLTDataSegmentList;
394 class AliHLTRawBuffer;
395 typedef vector<AliHLTRawBuffer*> AliHLTRawBufferPList;
398 * @class AliHLTRawPage
399 * Memory allocation is organized in pages of a fixed size. Within a
400 * page, AliHLTRawBuffer chunks are created.
402 class AliHLTRawPage : public AliHLTLogging {
404 /** standard constructor */
405 AliHLTRawPage() : fSize(0), fPtr(NULL), fFreeBuffers(), fUsedBuffers() {}
407 AliHLTRawPage(AliHLTUInt32_t pagesize);
409 virtual ~AliHLTRawPage();
411 /** alloc a buffer of specified size from the global pages*/
412 static AliHLTRawBuffer* GlobalAlloc(AliHLTUInt32_t size, int verbosity=0);
413 /** find buffer in the global pages */
414 static AliHLTRawPage* FindPage(AliHLTRawBuffer* buffer);
415 /** cleanup the global pages */
416 static int GlobalClean();
417 /** adjust global page size */
418 static void SetGlobalPageSize(AliHLTUInt32_t size) {fgGlobalPageSize=size;}
419 /** find next page after prev, or first page */
420 static AliHLTRawPage* NextPage(const AliHLTRawPage* prev=NULL);
422 /** alloc a buffer of specified size */
423 AliHLTRawBuffer* Alloc(AliHLTUInt32_t size);
424 /** free a buffer and merge consecutive free buffers */
425 int Free(AliHLTRawBuffer* pBuffer);
426 /** set the size of a raw buffer and release the remaining part */
427 int SetSize(const AliHLTRawBuffer* pBuffer, AliHLTUInt32_t size);
428 /// check if the buffer is in this page
429 bool HasBuffer(const AliHLTRawBuffer* pBuffer);
431 AliHLTUInt32_t Size() const {return fSize;}
432 AliHLTUInt32_t Capacity() const;
433 bool IsUsed() const {return fUsedBuffers.size()>0;}
434 bool IsFragmented() const {return (fFreeBuffers.size()+fUsedBuffers.size())>1;}
437 * Print page information
439 virtual void Print(const char* option);
442 /** copy constructor prohibited */
443 AliHLTRawPage(const AliHLTRawPage&);
444 /** assignment operator prohibited */
445 AliHLTRawPage& operator=(const AliHLTRawPage&);
447 /// list of global pages
448 static vector<AliHLTDataBuffer::AliHLTRawPage*> fgGlobalPages; //! transient
449 /// pages size of global pages
450 static AliHLTUInt32_t fgGlobalPageSize; //! transient
453 AliHLTUInt32_t fSize; // see above
454 /** the memory segment */
455 AliHLTUInt8_t* fPtr; //! transient
457 /** list of free buffers */
458 AliHLTRawBufferPList fFreeBuffers; //! transient
459 /** list of used buffers */
460 AliHLTRawBufferPList fUsedBuffers; //! transient
464 * @class AliHLTRawBuffer
465 * @brief Descriptor of the raw data buffer which can host several segments.
467 class AliHLTRawBuffer {
469 /** standard constructor */
470 AliHLTRawBuffer() : fSize(0), fTotalSize(0), fExternalPtr(NULL), fPtr(NULL), fLastEventCount(0) {}
472 AliHLTRawBuffer(AliHLTUInt32_t size);
474 AliHLTRawBuffer(AliHLTUInt32_t size, AliHLTUInt8_t* buffer);
476 virtual ~AliHLTRawBuffer();
479 * Use a fraction of the buffer.
480 * @param size size in bytes to be used
481 * @return pointer to buffer
483 AliHLTUInt8_t* UseBuffer(AliHLTUInt32_t size);
486 * split a buffer at specified size
487 * only possible for buffers with external memory
489 AliHLTRawBuffer* Split(AliHLTUInt32_t size);
492 * Check whether buffer fits for a request.
493 * A buffer fits if it is at least of the requested size and at most
494 * the requested size plus a margin. The margin increases with the
495 * number of events the buffer has not been used.
496 * @param size size of the request in bytes
497 * @return 1 if buffer is big enough, 0 if not
499 int CheckSize(AliHLTUInt32_t size) const;
502 * Get used size of the buffer
504 AliHLTUInt32_t GetUsedSize() const {return fSize;}
507 * Get total size of the buffer
509 AliHLTUInt32_t GetTotalSize() const {return fTotalSize;}
512 * Get pointer of data buffer
514 AliHLTUInt8_t* GetPointer() const {return fPtr;}
517 * Write check pattern
519 int WritePattern(const char* pattern, int size);
524 int CheckPattern(const char* pattern, int size) const;
528 * Data buffer remains allocated, used size set to 0
533 * Merge buffer with succeeding buffer.
534 * Only possible if the buffers are consecutive with out any gap.
536 int Merge(const AliHLTRawBuffer& succ);
539 * Print buffer information
541 virtual void Print(const char* option) const;
543 int operator==(void* ptr) const;
544 int operator==(AliHLTUInt8_t* ptr) const {return fPtr==ptr;}
545 int operator<(void* ptr) const;
546 int operator<=(void* ptr) const;
547 int operator>(void* ptr) const;
548 int operator-(void* ptr) const;
549 int operator<(const AliHLTRawBuffer& op) const;
550 int operator<=(const AliHLTRawBuffer& op) const;
551 int operator>(const AliHLTRawBuffer& op) const;
553 operator void*() const {return fPtr;}
554 operator AliHLTUInt8_t*() const {return fPtr;}
557 /** copy constructor prohibited */
558 AliHLTRawBuffer(const AliHLTRawBuffer&);
559 /** assignment operator prohibited */
560 AliHLTRawBuffer& operator=(const AliHLTRawBuffer&);
562 /** size of the currently occupied partition of the buffer */
563 AliHLTUInt32_t fSize; // see above
564 /** total size of the buffer, including safety margin */
565 AliHLTUInt32_t fTotalSize; // see above
566 /** optional external buffer */
567 AliHLTUInt8_t* fExternalPtr; //! transient
568 /** the buffer, external or allocated */
569 AliHLTUInt8_t* fPtr; //! transient
570 /** last event count where the buffer has been used */
571 AliHLTUInt32_t fLastEventCount; //! transient
575 /** copy constructor prohibited */
576 AliHLTDataBuffer(const AliHLTDataBuffer&);
577 /** assignment operator prohibited */
578 AliHLTDataBuffer& operator=(const AliHLTDataBuffer&);
580 /* lets see if this is needed
581 AliHLTDataSegment* FindDataSegment(AliHLTComponentDataType datatype);
585 * Find those data segments which match the input types of a component.
586 * @param pConsumer the component which subscribes to the buffer
587 * @param tgtList the list to receive the data segment descriptors
588 * @return: number of data blocks which match the input data types
589 * of the consumer, neg. error code if failed <br>
590 * -EINVAL invalid parameter <br>
592 int FindMatchingDataSegments(const AliHLTComponent* pConsumer,
593 AliHLTDataSegmentList& tgtList);
596 // 2010-02-01 make function protected in order to be used from unit test
598 * Reset the data buffer.
599 * Removes all consumers back to the @ref fConsumers list, deletes
600 * segments and releases the Raw Buffer.
602 int ResetDataBuffer();
605 //////////////////////////////////////////////////////////////////////////////
607 // the data description
609 // the data segments within this buffer
610 vector<AliHLTDataSegment> fSegments; // see above
612 // the list of all consumers which are going to subscribe to the buffer
613 AliHLTConsumerDescriptorPList fConsumers; // see above
614 // the list of all consumers which are currently subscribed to the buffer
615 AliHLTConsumerDescriptorPList fActiveConsumers; // see above
616 // the list of all consumers which are already released for the current event
617 AliHLTConsumerDescriptorPList fReleasedConsumers; // see above
619 // the buffer instance
620 AliHLTRawBuffer* fpBuffer; //! transient
622 // flags indicating the state of the buffer
623 AliHLTUInt32_t fFlags; // see above
625 /** list of tasks with forwarded data blocks */
626 vector<AliHLTTask*> fForwardedSegmentSources; //! transient
628 /** list of forwarded block descriptors */
629 vector<AliHLTDataSegment> fForwardedSegments; //! transient
631 //////////////////////////////////////////////////////////////////////////////
632 // global buffer handling, internal use only
635 * Create a raw buffer of a certain size.
636 * The function tries to find a buffer of the given size (or a bit bigger by a
637 * certain margin @ref fgMargin) from the list of free buffers.
638 * If no buffer is available, a new one is created and added to the buffer handling.
639 * @param size min. size of the requested buffer
640 * @return pointer to raw buffer
642 static AliHLTRawBuffer* CreateRawBuffer(AliHLTUInt32_t size);
645 * Set the data size of a raw buffer after it has been filled by
648 int SetRawBufferDataSize(AliHLTRawBuffer* pBuffer, AliHLTUInt32_t size) const;
651 * Mark a buffer as free.
652 * After the Data Buffer has finnished using the raw buffer, it is released
653 * and added to the list of available buffers.
654 * @param pBuffer the raw buffer to release
655 * @return >=0 if succeeded, neg. error code if failed
657 static int ReleaseRawBuffer(AliHLTRawBuffer* pBuffer);
660 * Deletes all the raw buffers.
661 * When the last Data Buffer object is destructed, all raw data buffers are
664 static int DeleteRawBuffers();
667 * Number of instances of AliHLTDataBuffer.
668 * The statice variable is incremented and decremented in the constructor/
669 * destructor. All internal data structures are cleaned up when the last
670 * instance is exiting.
672 static int fgNofInstances; // see above
673 /** global list of free raw buffers */
674 static vector<AliHLTRawBuffer*> fgFreeBuffers; // see above
675 /** global list of currently active raw buffers */
676 static vector<AliHLTRawBuffer*> fgActiveBuffers; // see above
677 /** determines the raw buffer size margin at buffer requests */
678 static AliHLTUInt32_t fgMargin; // see above
680 /** global instance to HLT logging class for static methods */
681 static AliHLTLogging fgLogging; // see above
683 /** size of the safety pattern */
684 static const Int_t fgkSafetyPatternSize; // see above
686 /** the safety pattern */
687 static const char fgkSafetyPattern[]; //!transient
689 static AliHLTUInt32_t fgEventCount; //!transient
691 //////////////////////////////////////////////////////////////////////////////
692 // internal helper functions
695 * Find the consumer descriptor for a certain component and data type in
696 * a list of consumers.<br>
697 * <b>Note:</b> There are three lists which contain the consumers in the
699 * @param pConsumer pointer to consumer component
700 * @param list list where to search for the consumer
702 AliHLTConsumerDescriptor* FindConsumer(const AliHLTComponent* pConsumer,
703 AliHLTConsumerDescriptorPList &list) const;
706 * Change the state of a consumer.
707 * The state of a consumer is determined by the list it is strored in, the
708 * method moves a consumer from the source to the target list.
709 * @param pDesc pointer to consumer descriptor
710 * @param srcList list where the consumer is currently to be found
711 * @param tgtList list where to move the consumer
713 int ChangeConsumerState(AliHLTConsumerDescriptor* pDesc,
714 AliHLTConsumerDescriptorPList &srcList,
715 AliHLTConsumerDescriptorPList &tgtList);
718 * Cleanup a consumer list.
719 * Release all allocated data structures. <b>Note:</b> Not the component itself!
721 int CleanupConsumerList();
723 ClassDef(AliHLTDataBuffer, 1)
726 #endif // ALIHLTDATABUFFER_H