HLT/BASE/AliHLTDataBuffer.h

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