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