/* Copyright(c) 1998-1999, ALICE Experiment at CERN, All rights reserved. *
* See cxx source for full Copyright notice */
-/* AliHLTDataBuffer
- handling of data buffers for the HLT
- */
-
-#include <cerrno>
+/** @file AliHLTDataBuffer.h
+ @author Matthias Richter
+ @date
+ @brief Handling of Data Buffers for HLT components.
+ @note The class is used in Offline (AliRoot) context
+*/
+
+// see below for class documentation
+// or
+// refer to README to build package
+// or
+// visit http://web.ift.uib.no/~kjeks/doc/alice-hlt
+
+#include <vector>
+#include "TObject.h"
#include "AliHLTLogging.h"
#include "AliHLTDataTypes.h"
-#include "AliHLTDefinitions.h"
#include "AliHLTComponent.h"
-#include "TObject.h"
-#include "TList.h"
-/* internal data structure
+class AliHLTConsumerDescriptor;
+class AliHLTTask;
+
+/** list of AliHLTConsumerDescriptor pointers */
+typedef vector<AliHLTConsumerDescriptor*> AliHLTConsumerDescriptorPList;
+
+typedef AliHLTUInt8_t* AliHLTUInt8Pointer_t;
+
+/**
+ * @class AliHLTDataBuffer
+ * @brief Handling of data buffers for the HLT.
+ *
+ * The class provides handling of data buffers for HLT tasks. Each task gets
+ * its own Data Buffer instance. The buffer is grouped into different data
+ * segments according to the output of the component.<br>
+ * The Data Buffer keeps control over the data requests of the 'child'
+ * components. Each component can subscribe to a certain segment of the data
+ * buffer. It's state is then changed from 'reserved' to 'active'. After the
+ * data processing, the component has to release the segment and it's state is
+ * set to 'processed'. If all components have requested and released their data,
+ * the Raw Buffer is released and pushed back in the list of available buffers.
+ *
+ * @note This class is only used for the @ref alihlt_system.
+ *
+ * @ingroup alihlt_system
*/
-struct AliHLTDataSegment {
- AliHLTComponent_DataType fDataType; // the data type of this buffer
- Int_t fSegmentOffset; // offset in byte within the data buffer
- Int_t fSegmentSize; // size of the actual content
- AliHLTUInt32_t fSpecification; // data specification
-};
-
-/* internal data structure
- */
-struct AliHLTRawBuffer {
- AliHLTUInt32_t fSize; // size of the buffer
- AliHLTUInt32_t fTotalSize; // total size of the buffer, including safety margin
- void* fPtr; // the buffer
-};
-
-/* internal data structure
- * there is unfortunately no unique determination of the data type from the component
- * itself possible, thats way both component and data type have to be initialized
- * and are stored in a compound
- */
-class AliHLTConsumerDescriptor : public TObject, public AliHLTLogging {
- private:
- AliHLTComponent* fpConsumer;
- AliHLTComponent_DataType fDataType;
- AliHLTDataSegment* fpSegment;
-
+class AliHLTDataBuffer : public TObject, public AliHLTLogging
+{
public:
- AliHLTConsumerDescriptor();
- AliHLTConsumerDescriptor(AliHLTComponent* pConsumer, AliHLTComponent_DataType datatype);
- ~AliHLTConsumerDescriptor();
-
- AliHLTComponent* GetComponent() {return fpConsumer;}
- AliHLTComponent_DataType GetDataType() {return fDataType;}
+ //////////////////////////////////////////////////////////////////////////////
+ // constructors and destructors
- int SetActiveDataSegment(AliHLTDataSegment* pSegment);
- int CheckActiveDataSegment(AliHLTUInt32_t offset, AliHLTUInt32_t size);
- int ReleaseActiveDataSegment();
-};
-
-class AliHLTDataBuffer : public AliHLTLogging, public TObject {
- public:
+ /* standard constructor
+ */
AliHLTDataBuffer();
+ /** destructor */
virtual ~AliHLTDataBuffer();
- ////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+ //////////////////////////////////////////////////////////////////////////////
// initialization
- /* add component to the list of consumers
- * parameter:
- * pConsumer - a consumer of type AliHLTComponent
- * datatype - data type of the segement, the consumer is registered for
+ /**
+ * Add component to the list of consumers
+ * @param pConsumer - a consumer of type AliHLTComponent
*/
- int SetConsumer(AliHLTComponent* pConsumer, AliHLTComponent_DataType datatype);
+ int SetConsumer(AliHLTComponent* pConsumer);
- ////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+ //////////////////////////////////////////////////////////////////////////////
// component to component communication
- /* subscribe to a segment of the data buffer
- * the function prepares the block descriptor for subsequent use with the AliHLTComponent::ProcessEvent
- * method
- * parameter:
- * datatype - type of the data segment
- * pConsumer - the component which subscribes to the buffer
- * pBlockDesc - pointer to receive the prepared block descriptor
- * return: >0 if success, negative error code if failed
+ /**
+ * Determine the number of matching data blocks for the component and a
+ * consumer component. <br>
+ * The first approach will support only one output data type for processing
+ * components.
+ * @param pConsumer the component which subscribes to the buffer
+ * @param tgtList (optional) the list to receive the data types
+ * @return: number of data blocks which match the input data types
+ * of the consumer, neg. error code if failed <br>
+ * -EINVAL invalid parameter <br>
*/
- int Subscribe(AliHLTComponent_DataType datatype, const AliHLTComponent* pConsumer, AliHLTComponent_BlockData* pBlockDesc);
-
- /* release an instance of the data buffer
- * resets the variables of the block descriptor
- * parameter:
- * pBlockDesc - descriptor of the data segment
- * pConsumer - the component which subscribes to the buffer
- * return: >0 if success, negative error code if failed
+ int FindMatchingDataBlocks(const AliHLTComponent* pConsumer,
+ AliHLTComponentDataTypeList* tgtList=NULL);
+
+ /**
+ * Subscribe to a segment of the data buffer.
+ * The function prepares the block descriptor for subsequent use with the
+ * AliHLTComponent::ProcessEvent method, the method can prepare several block
+ * descriptors up to the array size specified by iArraySize. The return value
+ * is independent from the array size the number of block descriptors which
+ * would have been prepared if there was enough space in the array<br>
+ * The method is used by the consumer component.
+ * @param pConsumer the component which subscribes to the buffer
+ * @param blockDescList block descriptor vector to be filled
+ * @return: number of matching data blocks, neg. error code if failed<br>
+ * -EACCESS the consumer state can't be changed (activated)
+ * -EBADF unresolved data segments <br>
+ * -ENOENT consumer component not found <br>
+ * -ENODATA data buffer does not have raw data <br>
+ * -EINVAL invalid parameter <br>
*/
- int Release(AliHLTComponent_BlockData* pBlockDesc, const AliHLTComponent* pConsumer);
-
- /* get a target buffer if minimum size iMinSize
+ int Subscribe(const AliHLTComponent* pConsumer,
+ AliHLTComponentBlockDataList& blockDescList);
+
+ /**
+ * Release an instance of the data buffer.
+ * Resets the variables of the block descriptor.
+ * If all buffer segments are released, the Data Buffer is reseted
+ * and the Raw Buffer released.<br>
+ * The method is used by the consumer component.
+ * @param pBlockDesc descriptor of the data segment
+ * @param pConsumer the component which subscribes to the buffer
+ * @param pOwnerTask task owning this buffer
+ * @return: >0 if success, negative error code if failed <br>
+ * -EACCESS the consumer state can not be changed (de-activated)
+ * -ENOENT consumer has not subscribed to the buffer <br>
+ * -EINVAL invalid parameter <br>
+ */
+ int Release(AliHLTComponentBlockData* pBlockDesc, const AliHLTComponent* pConsumer,
+ const AliHLTTask* pOwnerTask);
+
+ /**
+ * Register an input data block for forwarding.
+ * Consumer of this data buffer subscribe to forwarded data blocks in te same way.
+ * Forwarded data blocks are released when the last consumer has released the
+ * blocks.
+ * @param pSrcTask original source task of the data block
+ * @param pBlockDesc descriptor of the data segment
+ */
+ int Forward(AliHLTTask* pSrcTask, AliHLTComponentBlockData* pBlockDesc);
+
+ /**
+ * Get a target buffer of minimum size iMinSize.
+ * The method is used by the component which owns the Data Buffer to
+ * allocate a buffer for the data it is going to produce.
+ * @param iMinSize minumum size of the requested buffer
+ * @return: pointer to target buffer if
*/
AliHLTUInt8_t* GetTargetBuffer(int iMinSize);
- /* set the segments for the data buffer
- * this is usually done after the component has written the data to the buffer
- * parameter:
- * pTgt - the target buffer the segments refer to
- * arraySegments - the output block descriptors of the component
- * iSize - size of the array
+ /**
+ * Set the segments for the data buffer.
+ * This is usually done after the component has written the data to the buffer,
+ * which was requested by the @ref GetTargetBuffer method. The component might
+ * produce different types of data, for each type a segment has to be defined
+ * which describes the data inside the buffer.<br>
+ * The @ref AliHLTComponentBlockData segment descriptor comes directly from
+ * the @ref AliHLTComponent::ProcessEvent method.
+ * @param pTgt the target buffer which the segments refer to
+ * @param arraySegments the output block descriptors of the component
+ * @param iSize size of the array
*/
- int SetSegments(AliHLTUInt8_t* pTgt, AliHLTComponent_BlockData* arraySegments, int iSize);
+ int SetSegments(AliHLTUInt8_t* pTgt, AliHLTComponentBlockData* arraySegments, int iSize);
- /* check if the data buffer is empty
+ /**
+ * Check if the data buffer is empty.
+ * @return 1 if empty, 0 if not
*/
int IsEmpty();
- /* get the total and maximum size of the buffer
- * lets see if this is needed later
+ /**
+ * Get the total and maximum size of the buffer.
+ * Lets see if this is needed later
*/
//int GetTotalSize();
- /* get the number of segments
+ /**
+ * Get the number of segments
+ * @return number of segments
*/
int GetNofSegments();
- /* get the number of consumers
+ /**
+ * Get the total number of consumers.
+ * This gives the number of consumers regardless of their state.
+ * @return number of consumers
*/
int GetNofConsumers();
- /* get the number of consumers
+ /**
+ * Get the number of consumers which still need to be processed during
+ * the current event.
+ * @return number of consumers
+ */
+ int GetNofPendingConsumers();
+
+ /**
+ * Get the number of consumers currently under processing.
+ * @return number of active consumers
*/
int GetNofActiveConsumers();
+ /**
+ * Check if a consumer is already in the list
+ * @param pConsumer pointer to consumer component
+ * @param bAllLists search in all lists if 1
+ * search only in fConsumer list if 0
+ * @return 1 if found, 0 if not
+ */
+ int FindConsumer(AliHLTComponent* pConsumer, int bAllLists=1);
+
+ /**
+ * Public method to reset the buffer.
+ * Eventually with some additional checks. In normal operation,
+ * an external reset should not be necessary.
+ */
+ int Reset();
+
+ /**
+ * Set local logging level
+ * logging filter for individual object
+ */
+ void SetLocalLoggingLevel(AliHLTComponentLogSeverity level)
+ {fgLogging.SetLocalLoggingLevel(level); AliHLTLogging::SetLocalLoggingLevel(level);}
+
+ /**
+ * @class AliHLTDataSegment
+ * @brief Descriptor of a data segment within the buffer.
+ */
+ class AliHLTDataSegment {
+ friend class AliHLTDataBuffer;
+ friend class AliHLTConsumerDescriptor;
+ public:
+ AliHLTDataSegment()
+ :
+ fDataType(kAliHLTVoidDataType),
+ fPtr(NULL),
+ fSegmentOffset(0),
+ fSegmentSize(0),
+ fSpecification(0)
+ {
+ }
+
+ AliHLTDataSegment(AliHLTUInt8_t* ptr, AliHLTUInt32_t offset, AliHLTUInt32_t size)
+ :
+ fDataType(kAliHLTVoidDataType),
+ fPtr(ptr),
+ fSegmentOffset(offset),
+ fSegmentSize(size),
+ fSpecification(0)
+ {
+ }
+
+ AliHLTDataSegment(void* ptr, AliHLTUInt32_t offset, AliHLTUInt32_t size)
+ :
+ fDataType(kAliHLTVoidDataType),
+ fPtr((AliHLTUInt8_t*)ptr),
+ fSegmentOffset(offset),
+ fSegmentSize(size),
+ fSpecification(0)
+ {
+ }
+
+ AliHLTDataSegment(void* ptr, AliHLTUInt32_t offset, AliHLTUInt32_t size, AliHLTComponentDataType dt, AliHLTUInt32_t spec)
+ :
+ fDataType(dt),
+ fPtr((AliHLTUInt8_t*)ptr),
+ fSegmentOffset(offset),
+ fSegmentSize(size),
+ fSpecification(spec)
+ {
+ }
+
+ AliHLTUInt8_t* GetPtr() const {return (AliHLTUInt8_t*)*this;}
+
+ AliHLTUInt32_t GetSize() const {return fSegmentSize;}
+
+ int operator==(const AliHLTDataSegment& seg) const
+ {
+ return (fPtr+fSegmentOffset==seg.fPtr+seg.fSegmentOffset) && (fSegmentSize==seg.fSegmentSize);
+ }
+ operator AliHLTUInt8_t*() const {return fPtr+fSegmentOffset;}
+
+ private:
+ /** the data type of this segment */
+ AliHLTComponentDataType fDataType; // see above
+ /** pointer to the buffer */
+ AliHLTUInt8Pointer_t fPtr; //!transient
+ /** offset in byte within the data buffer */
+ AliHLTUInt32_t fSegmentOffset; // see above
+ /** size of the actual content */
+ AliHLTUInt32_t fSegmentSize; // see above
+ /** data specification */
+ AliHLTUInt32_t fSpecification; // see above
+ };
+
+ /**
+ * @class AliHLTRawBuffer
+ * @brief Descriptor of the raw data buffer which can host several segments.
+ */
+ class AliHLTRawBuffer {
+ public:
+ /** standard constructor */
+ AliHLTRawBuffer() : fSize(0), fTotalSize(0), fPtr(NULL) {}
+ /** constructor */
+ AliHLTRawBuffer(AliHLTUInt32_t size);
+ /** destructor */
+ virtual ~AliHLTRawBuffer();
+
+ /**
+ * Use a fraction of the buffer.
+ * @param size size in bytes to be used
+ * @return pointer to buffer
+ */
+ AliHLTUInt8_t* UseBuffer(AliHLTUInt32_t size);
+
+ /**
+ * Check whether buffer fits for a request.
+ * @param size size of the request in bytes
+ * @return 1 if buffer is big enough, 0 if not
+ */
+ int CheckSize(AliHLTUInt32_t size) const;
+
+ /**
+ * Get used size of the buffer
+ */
+ AliHLTUInt32_t GetUsedSize() const {return fSize;}
+
+ /**
+ * Get total size of the buffer
+ */
+ AliHLTUInt32_t GetTotalSize() const {return fTotalSize;}
+
+ /**
+ * Get pointer of data buffer
+ */
+ AliHLTUInt8_t* GetPointer() const {return fPtr;}
+
+ /**
+ * Write check pattern
+ */
+ int WritePattern(const char* pattern, int size);
+
+ /**
+ * Check pattern
+ */
+ int CheckPattern(const char* pattern, int size) const;
+
+ /**
+ * Reset buffer.
+ * Data buffer remains allocated, used size set to 0
+ */
+ int Reset();
+
+ int operator==(void*) const;
+ int operator==(AliHLTUInt8_t* ptr) const {return fPtr==ptr;}
+ int operator<=(void*) const;
+ int operator>(void*) const;
+ int operator-(void*) const;
+
+ operator void*() const {return fPtr;}
+ operator AliHLTUInt8_t*() const {return fPtr;}
+
+ private:
+ /** copy constructor prohibited */
+ AliHLTRawBuffer(const AliHLTRawBuffer&);
+ /** assignment operator prohibited */
+ AliHLTRawBuffer& operator=(const AliHLTRawBuffer&);
+
+ /** size of the currently occupied partition of the buffer */
+ AliHLTUInt32_t fSize; // see above
+ /** total size of the buffer, including safety margin */
+ AliHLTUInt32_t fTotalSize; // see above
+ /** the buffer */
+ AliHLTUInt8_t* fPtr; //! transient
+ };
+
private:
- AliHLTDataSegment* FindDataSegment(AliHLTComponent_DataType datatype);
+ /** copy constructor prohibited */
+ AliHLTDataBuffer(const AliHLTDataBuffer&);
+ /** assignment operator prohibited */
+ AliHLTDataBuffer& operator=(const AliHLTDataBuffer&);
+
+ /* lets see if this is needed
+ AliHLTDataSegment* FindDataSegment(AliHLTComponentDataType datatype);
+ */
+
+ /**
+ * Find those data segments which match the input types of a component.
+ * @param pConsumer the component which subscribes to the buffer
+ * @param tgtList the list to receive the data segment descriptors
+ * @return: number of data blocks which match the input data types
+ * of the consumer, neg. error code if failed <br>
+ * -EINVAL invalid parameter <br>
+ */
+ int FindMatchingDataSegments(const AliHLTComponent* pConsumer,
+ vector<AliHLTDataBuffer::AliHLTDataSegment>& tgtList);
- /* reset the data buffer
- * removes all condumers back to the fConsumers list
+ /**
+ * Reset the data buffer.
+ * Removes all consumers back to the @ref fConsumers list, deletes
+ * segments and releases the Raw Buffer.
*/
int ResetDataBuffer();
+ //////////////////////////////////////////////////////////////////////////////
- ////////////////////////////////////////////////////////////////////////////////////////////////////////////////
// the data description
- vector<AliHLTDataSegment> fSegments;// the data segments within this buffer
- vector<AliHLTConsumerDescriptor*> fConsumers; // the list of all consumers which are going to subscribe to the buffer
- vector<AliHLTConsumerDescriptor*> fActiveConsumers; // the list of all consumers which are currently subscribed to the buffer
- vector<AliHLTConsumerDescriptor*> fReleasedConsumers; // the list of all consumers which are already released for the current event
+ // the data segments within this buffer
+ vector<AliHLTDataSegment> fSegments; // see above
+
+ // the list of all consumers which are going to subscribe to the buffer
+ AliHLTConsumerDescriptorPList fConsumers; // see above
+ // the list of all consumers which are currently subscribed to the buffer
+ AliHLTConsumerDescriptorPList fActiveConsumers; // see above
+ // the list of all consumers which are already released for the current event
+ AliHLTConsumerDescriptorPList fReleasedConsumers; // see above
+
+ // the buffer instance
+ AliHLTRawBuffer* fpBuffer; //! transient
- AliHLTRawBuffer* fpBuffer; // the buffer instance
+ // flags indicating the state of the buffer
+ AliHLTUInt32_t fFlags; // see above
- AliHLTUInt32_t fFlags; // flags indicating the state of the buffer
+ /** list of tasks with forwarded data blocks */
+ vector<AliHLTTask*> fForwardedSegmentSources; //! transient
- ////////////////////////////////////////////////////////////////////////////////////////////////////////////////
- // global buffer handling
+ /** list of forwarded block descriptors */
+ vector<AliHLTDataSegment> fForwardedSegments; //! transient
- /* create a raw buffer of a certain size
- * the function tries to find a buffer of the given size (or a little bit bigger) from the list of free buffers
- * if no buffer is available, a new one is created
+ //////////////////////////////////////////////////////////////////////////////
+ // global buffer handling, internal use only
+
+ /**
+ * Create a raw buffer of a certain size.
+ * The function tries to find a buffer of the given size (or a bit bigger by a
+ * certain margin @ref fgMargin) from the list of free buffers.
+ * If no buffer is available, a new one is created and added to the buffer handling.
+ * @param size min. size of the requested buffer
+ * @return pointer to raw buffer
*/
static AliHLTRawBuffer* CreateRawBuffer(AliHLTUInt32_t size);
- /* mark a buffer as free
+ /**
+ * Mark a buffer as free.
+ * After the Data Buffer has finnished using the raw buffer, it is released
+ * and added to the list of available buffers.
+ * @param pBuffer the raw buffer to release
+ * @return >=0 if succeeded, neg. error code if failed
*/
static int ReleaseRawBuffer(AliHLTRawBuffer* pBuffer);
- /* deletes all the raw buffers
+ /**
+ * Deletes all the raw buffers.
+ * When the last Data Buffer object is destructed, all raw data buffers are
+ * relesed.
*/
static int DeleteRawBuffers();
- static int fNofInstances;
- static vector<AliHLTRawBuffer*> fFreeBuffers;
- static vector<AliHLTRawBuffer*> fActiveBuffers;
- static AliHLTUInt32_t fMargin;
-
- /*
+ /**
+ * Number of instances of AliHLTDataBuffer.
+ * The statice variable is incremented and decremented in the constructor/
+ * destructor. All internal data structures are cleaned up when the last
+ * instance is exiting.
*/
- AliHLTConsumerDescriptor* FindConsumer(const AliHLTComponent* pConsumer, AliHLTComponent_DataType datatype, vector<AliHLTConsumerDescriptor*> &pList);
-
- int ChangeConsumerState(AliHLTConsumerDescriptor* pDesc, vector<AliHLTConsumerDescriptor*> &srcList, vector<AliHLTConsumerDescriptor*> &tgtList);
+ static int fgNofInstances; // see above
+ /** global list of free raw buffers */
+ static vector<AliHLTRawBuffer*> fgFreeBuffers; // see above
+ /** global list of currently active raw buffers */
+ static vector<AliHLTRawBuffer*> fgActiveBuffers; // see above
+ /** determines the raw buffer size margin at buffer requests */
+ static AliHLTUInt32_t fgMargin; // see above
+
+ /** global instance to HLT logging class for static methods */
+ static AliHLTLogging fgLogging; // see above
+
+ /** size of the safety pattern */
+ static const Int_t fgkSafetyPatternSize; // see above
+
+ /** the safety pattern */
+ static const char fgkSafetyPattern[]; //!transient
+
+ //////////////////////////////////////////////////////////////////////////////
+ // internal helper functions
+
+ /**
+ * Find the consumer descriptor for a certain component and data type in
+ * a list of consumers.<br>
+ * <b>Note:</b> There are three lists which contain the consumers in the
+ * different states.
+ * @param pConsumer pointer to consumer component
+ * @param list list where to search for the consumer
+ */
+ AliHLTConsumerDescriptor* FindConsumer(const AliHLTComponent* pConsumer,
+ AliHLTConsumerDescriptorPList &list) const;
+
+ /**
+ * Change the state of a consumer.
+ * The state of a consumer is determined by the list it is strored in, the
+ * method moves a consumer from the source to the target list.
+ * @param pDesc pointer to consumer descriptor
+ * @param srcList list where the consumer is currently to be found
+ * @param tgtList list where to move the consumer
+ */
+ int ChangeConsumerState(AliHLTConsumerDescriptor* pDesc,
+ AliHLTConsumerDescriptorPList &srcList,
+ AliHLTConsumerDescriptorPList &tgtList);
+ /**
+ * Cleanup a consumer list.
+ * Release all allocated data structures. <b>Note:</b> Not the component itself!
+ */
int CleanupConsumerList();
ClassDef(AliHLTDataBuffer, 0)
};
+
#endif // ALIHLTDATABUFFER_H
git://git.uio.no / u / mrichter / AliRoot.git / blobdiff