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 // see below for class documentation
  16 // or
  17 // refer to README to build package
  18 // or
  19 // visit http://web.ift.uib.no/~kjeks/doc/alice-hlt
  20
  21 #include <vector>
  22 #include "TObject.h"
  23 #include "AliHLTLogging.h"
  24 #include "AliHLTDataTypes.h"
  25 #include "AliHLTComponent.h"
  26
  27 class AliHLTConsumerDescriptor;
  28 class AliHLTTask;
  29
  30 /** list of AliHLTConsumerDescriptor pointers */
  31 typedef vector<AliHLTConsumerDescriptor*> AliHLTConsumerDescriptorPList;
  32
  33 typedef AliHLTUInt8_t* AliHLTUInt8Pointer_t;
  34
  35 /**
  36  * @class AliHLTDataBuffer
  37  * @brief  Handling of data buffers for the HLT.
  38  *
  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.
  48  *
  49  * @note This class is only used for the @ref alihlt_system.
  50  *
  51  * @ingroup alihlt_system
  52  */
  53 class AliHLTDataBuffer : public TObject, public AliHLTLogging
  54 {
  55  public:
  56   //////////////////////////////////////////////////////////////////////////////
  57   // constructors and destructors
  58
  59   /* standard constructor
  60    */
  61   AliHLTDataBuffer();
  62   /** destructor */
  63   virtual ~AliHLTDataBuffer();
  64
  65   //////////////////////////////////////////////////////////////////////////////
  66   // initialization
  67
  68   /**
  69    * Add component to the list of consumers
  70    * @param pConsumer - a consumer of type AliHLTComponent
  71    */
  72   int SetConsumer(AliHLTComponent* pConsumer);
  73
  74   //////////////////////////////////////////////////////////////////////////////
  75   // component to component communication
  76
  77   /**
  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
  81    * components.
  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>
  87    */
  88   int FindMatchingDataBlocks(const AliHLTComponent* pConsumer,
  89                              AliHLTComponentDataTypeList* tgtList=NULL);
  90
  91   /**
  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 arrayBlockDesc  pointer to block descriptor to be filled
 101    * @param iArraySize      size of the block descriptor array
 102    * @return: number of matching data blocks, neg. error code if failed<br>
 103    *          -EACCESS      the consumer state can't be changed (activated)
 104    *          -EBADF        unresolved data segments <br>
 105    *          -ENOENT       consumer component not found <br>
 106    *          -ENODATA      data buffer does not have raw data <br>
 107    *          -EINVAL       invalid parameter <br>
 108    */
 109   int Subscribe(const AliHLTComponent* pConsumer,
 110                 AliHLTComponentBlockDataList& blockDescList);
 111
 112   /**
 113    * Release an instance of the data buffer.
 114    * Resets the variables of the block descriptor.
 115    * If all buffer segments are released, the Data Buffer is reseted
 116    * and the Raw Buffer released.<br>
 117    * The method is used by the consumer component.
 118    * @param pBlockDesc      descriptor of the data segment
 119    * @param pConsumer       the component which subscribes to the buffer
 120    * @param pOwnerTask      task owning this buffer
 121    * @return: >0 if success, negative error code if failed <br>
 122    *          -EACCESS      the consumer state can not be changed (de-activated)
 123    *          -ENOENT       consumer has not subscribed to the buffer <br>
 124    *          -EINVAL       invalid parameter <br>
 125    */
 126   int Release(AliHLTComponentBlockData* pBlockDesc, const AliHLTComponent* pConsumer,
 127               const AliHLTTask* pOwnerTask);
 128
 129   /**
 130    * Register an input data block for forwarding.
 131    * Consumer of this data buffer subscribe to forwarded data blocks in te same way.
 132    * Forwarded data blocks are released when the last consumer has released the
 133    * blocks.
 134    * @param pSrcTask        original source task of the data block
 135    * @param pBlockDesc      descriptor of the data segment
 136    */
 137   int Forward(AliHLTTask* pSrcTask, AliHLTComponentBlockData* pBlockDesc);
 138
 139   /**
 140    * Get a target buffer of minimum size iMinSize.
 141    * The method is used by the component which owns the Data Buffer to
 142    * allocate a buffer for the data it is going to produce.
 143    * @param iMinSize        minumum size of the requested buffer
 144    * @return: pointer to target buffer if
 145    */
 146   AliHLTUInt8_t* GetTargetBuffer(int iMinSize);
 147
 148   /**
 149    * Set the segments for the data buffer.
 150    * This is usually done after the component has written the data to the buffer,
 151    * which was requested by the @ref GetTargetBuffer method. The component might
 152    * produce different types of data, for each type a segment has to be defined
 153    * which describes the data inside the buffer.<br>
 154    * The @ref AliHLTComponentBlockData segment descriptor comes directly from
 155    * the @ref AliHLTComponent::ProcessEvent method.
 156    * @param pTgt            the target buffer which the segments refer to
 157    * @param arraySegments   the output block descriptors of the component
 158    * @param iSize           size of the array
 159    */
 160   int SetSegments(AliHLTUInt8_t* pTgt, AliHLTComponentBlockData* arraySegments, int iSize);
 161
 162   /**
 163    * Check if the data buffer is empty.
 164    * @return 1 if empty, 0 if not
 165    */
 166   int IsEmpty();
 167
 168   /**
 169    * Get the total and maximum size of the buffer.
 170    * Lets see if this is needed later
 171    */
 172   //int GetTotalSize();
 173
 174   /**
 175    * Get the number of segments
 176    * @return number of segments
 177    */
 178   int GetNofSegments();
 179
 180   /**
 181    * Get the total number of consumers.
 182    * This gives the number of consumers regardless of their state.
 183    * @return number of consumers
 184    */
 185   int GetNofConsumers();
 186
 187   /**
 188    * Get the number of consumers which still need to be processed during
 189    * the current event.
 190    * @return number of consumers
 191    */
 192   int GetNofPendingConsumers();
 193
 194   /**
 195    * Get the number of consumers currently under processing.
 196    * @return number of active consumers
 197    */
 198   int GetNofActiveConsumers();
 199
 200   /**
 201    * Check if a consumer is already in the list
 202    * @param pConsumer   pointer to consumer component
 203    * @param bAllLists   search in all lists if 1
 204    *                    search only in fConsumer list if 0
 205    * @return 1 if found, 0 if not
 206    */
 207   int FindConsumer(AliHLTComponent* pConsumer, int bAllLists=1);
 208
 209   /**
 210    * Public method to reset the buffer.
 211    * Eventually with some additional checks. In normal operation,
 212    * an external reset should not be necessary.
 213    */
 214   int Reset();
 215
 216   /**
 217    * Set local logging level
 218    * logging filter for individual object
 219    */
 220   void SetLocalLoggingLevel(AliHLTComponentLogSeverity level)
 221   {fgLogging.SetLocalLoggingLevel(level); AliHLTLogging::SetLocalLoggingLevel(level);}
 222
 223   /**
 224    * @class AliHLTDataSegment
 225    * @brief  Descriptor of a data segment within the buffer.
 226    */
 227   class AliHLTDataSegment {
 228     friend class AliHLTDataBuffer;
 229     friend class AliHLTConsumerDescriptor;
 230   public:
 231     AliHLTDataSegment()
 232       :
 233       fDataType(kAliHLTVoidDataType),
 234       fPtr(NULL),
 235       fSegmentOffset(0),
 236       fSegmentSize(0),
 237       fSpecification(0)
 238     {
 239     }
 240
 241     AliHLTDataSegment(AliHLTUInt8_t* ptr, AliHLTUInt32_t offset, AliHLTUInt32_t size)
 242       :
 243       fDataType(kAliHLTVoidDataType),
 244       fPtr(ptr),
 245       fSegmentOffset(offset),
 246       fSegmentSize(size),
 247       fSpecification(0)
 248     {
 249     }
 250
 251     AliHLTDataSegment(void* ptr, AliHLTUInt32_t offset, AliHLTUInt32_t size)
 252       :
 253       fDataType(kAliHLTVoidDataType),
 254       fPtr((AliHLTUInt8_t*)ptr),
 255       fSegmentOffset(offset),
 256       fSegmentSize(size),
 257       fSpecification(0)
 258     {
 259     }
 260
 261     AliHLTDataSegment(void* ptr, AliHLTUInt32_t offset, AliHLTUInt32_t size, AliHLTComponentDataType dt, AliHLTUInt32_t spec)
 262       :
 263       fDataType(dt),
 264       fPtr((AliHLTUInt8_t*)ptr),
 265       fSegmentOffset(offset),
 266       fSegmentSize(size),
 267       fSpecification(spec)
 268     {
 269     }
 270
 271     AliHLTUInt8_t* GetPtr() const {return (AliHLTUInt8_t*)*this;}
 272
 273     AliHLTUInt32_t GetSize() const {return fSegmentSize;}
 274
 275     int operator==(const AliHLTDataSegment& seg) const
 276     {
 277       return (fPtr+fSegmentOffset==seg.fPtr+seg.fSegmentOffset) && (fSegmentSize==seg.fSegmentSize);
 278     }
 279     operator AliHLTUInt8_t*() const {return fPtr+fSegmentOffset;}
 280
 281   private:
 282     /** the data type of this segment */
 283     AliHLTComponentDataType fDataType;                             // see above
 284     /** pointer to the buffer */
 285     AliHLTUInt8Pointer_t fPtr;                                     //!transient
 286     /** offset in byte within the data buffer */
 287     AliHLTUInt32_t fSegmentOffset;                                 // see above
 288     /** size of the actual content */
 289     AliHLTUInt32_t fSegmentSize;                                   // see above
 290     /** data specification */
 291     AliHLTUInt32_t fSpecification;                                 // see above
 292   };
 293
 294   /**
 295    * @class AliHLTRawBuffer
 296    * @brief  Descriptor of the raw data buffer which can host several segments.
 297    */
 298   class AliHLTRawBuffer {
 299   public:
 300     /** standard constructor */
 301     AliHLTRawBuffer() : fSize(0), fTotalSize(0), fPtr(NULL) {}
 302     /** constructor */
 303     AliHLTRawBuffer(AliHLTUInt32_t size);
 304     /** destructor */
 305     virtual ~AliHLTRawBuffer();
 306
 307     /**
 308      * Use a fraction of the buffer.
 309      * @param size    size in bytes to be used
 310      * @return pointer to buffer
 311      */
 312     AliHLTUInt8_t* UseBuffer(AliHLTUInt32_t size);
 313
 314     /**
 315      * Check whether buffer fits for a request.
 316      * @param size    size of the request in bytes
 317      * @return 1 if buffer is big enough, 0 if not
 318      */
 319     int CheckSize(AliHLTUInt32_t size) const;
 320
 321     /**
 322      * Get used size of the buffer
 323      */
 324     AliHLTUInt32_t GetUsedSize() const {return fSize;}
 325
 326     /**
 327      * Get total size of the buffer
 328      */
 329     AliHLTUInt32_t GetTotalSize() const {return fTotalSize;}
 330
 331     /**
 332      * Get pointer of data buffer
 333      */
 334     AliHLTUInt8_t* GetPointer() const {return fPtr;}
 335
 336     /**
 337      * Write check pattern
 338      */
 339     int WritePattern(const char* pattern, int size);
 340
 341     /**
 342      * Check pattern
 343      */
 344     int CheckPattern(const char* pattern, int size) const;
 345
 346     /**
 347      * Reset buffer.
 348      * Data buffer remains allocated, used size set to 0
 349      */
 350     int Reset();
 351
 352     int operator==(void*) const;
 353     int operator==(AliHLTUInt8_t* ptr) const {return fPtr==ptr;}
 354     int operator<=(void*) const;
 355     int operator>(void*) const;
 356     int operator-(void*) const;
 357
 358     operator void*() const {return fPtr;}
 359     operator AliHLTUInt8_t*() const {return fPtr;}
 360
 361   private:
 362     /** copy constructor prohibited */
 363     AliHLTRawBuffer(const AliHLTRawBuffer&);
 364     /** assignment operator prohibited */
 365     AliHLTRawBuffer& operator=(const AliHLTRawBuffer&);
 366
 367     /** size of the currently occupied partition of the buffer */
 368     AliHLTUInt32_t fSize;                                          // see above
 369     /** total size of the buffer, including safety margin */
 370     AliHLTUInt32_t fTotalSize;                                     // see above
 371     /** the buffer */
 372     AliHLTUInt8_t* fPtr;                                           //! transient
 373   };
 374
 375  private:
 376   /** copy constructor prohibited */
 377   AliHLTDataBuffer(const AliHLTDataBuffer&);
 378   /** assignment operator prohibited */
 379   AliHLTDataBuffer& operator=(const AliHLTDataBuffer&);
 380
 381   /* lets see if this is needed
 382      AliHLTDataSegment* FindDataSegment(AliHLTComponentDataType datatype);
 383   */
 384
 385   /**
 386    * Find those data segments which match the input types of a component.
 387    * @param pConsumer       the component which subscribes to the buffer
 388    * @param tgtList         the list to receive the data segment descriptors
 389    * @return: number of data blocks which match the input data types
 390    *          of the consumer, neg. error code if failed <br>
 391    *          -EINVAL       invalid parameter <br>
 392    */
 393   int FindMatchingDataSegments(const AliHLTComponent* pConsumer,
 394                                vector<AliHLTDataBuffer::AliHLTDataSegment>& tgtList);
 395
 396   /**
 397    * Reset the data buffer.
 398    * Removes all consumers back to the @ref fConsumers list, deletes
 399    * segments and releases the Raw Buffer.
 400    */
 401   int ResetDataBuffer();
 402
 403   //////////////////////////////////////////////////////////////////////////////
 404
 405   // the data description
 406
 407   // the data segments within this buffer
 408   vector<AliHLTDataSegment> fSegments;                             // see above
 409
 410   // the list of all consumers which are going to subscribe to the buffer
 411   AliHLTConsumerDescriptorPList fConsumers;                         // see above
 412   // the list of all consumers which are currently subscribed to the buffer
 413   AliHLTConsumerDescriptorPList fActiveConsumers;                   // see above
 414   // the list of all consumers which are already released for the current event
 415   AliHLTConsumerDescriptorPList fReleasedConsumers;                 // see above
 416
 417   // the buffer instance
 418   AliHLTRawBuffer* fpBuffer;                                       //! transient
 419
 420   // flags indicating the state of the buffer
 421   AliHLTUInt32_t fFlags;                                           // see above
 422
 423   /** list of tasks with forwarded data blocks */
 424   vector<AliHLTTask*> fForwardedSegmentSources;                    //! transient
 425
 426   /** list of forwarded block descriptors */
 427   vector<AliHLTDataSegment> fForwardedSegments;                    //! transient
 428
 429   //////////////////////////////////////////////////////////////////////////////
 430   // global buffer handling, internal use only
 431
 432   /**
 433    * Create a raw buffer of a certain size.
 434    * The function tries to find a buffer of the given size (or a bit bigger by a
 435    * certain margin @ref fgMargin) from the list of free buffers.
 436    * If no buffer is available, a new one is created and added to the buffer handling.
 437    * @param size            min. size of the requested buffer
 438    * @return pointer to raw buffer
 439    */
 440   static AliHLTRawBuffer* CreateRawBuffer(AliHLTUInt32_t size);
 441
 442   /**
 443    * Mark a buffer as free.
 444    * After the Data Buffer has finnished using the raw buffer, it is released
 445    * and added to the list of available buffers.
 446    * @param pBuffer         the raw buffer to release
 447    * @return >=0 if succeeded, neg. error code if failed
 448    */
 449   static int ReleaseRawBuffer(AliHLTRawBuffer* pBuffer);
 450
 451   /**
 452    * Deletes all the raw buffers.
 453    * When the last Data Buffer object is destructed, all raw data buffers are
 454    * relesed.
 455    */
 456   static int DeleteRawBuffers();
 457
 458   /**
 459    * Number of instances of AliHLTDataBuffer.
 460    * The statice variable is incremented and decremented in the constructor/
 461    * destructor. All internal data structures are cleaned up when the last
 462    * instance is exiting.
 463    */
 464   static int fgNofInstances;                                       // see above
 465   /** global list of free raw buffers */
 466   static vector<AliHLTRawBuffer*> fgFreeBuffers;                   // see above
 467   /** global list of currently active raw buffers */
 468   static vector<AliHLTRawBuffer*> fgActiveBuffers;                 // see above
 469   /** determines the raw buffer size margin at buffer requests */
 470   static AliHLTUInt32_t fgMargin;                                  // see above
 471
 472   /** global instance to HLT logging class for static methods */
 473   static AliHLTLogging fgLogging;                                  // see above
 474
 475   /** size of the safety pattern */
 476   static const Int_t fgkSafetyPatternSize;                         // see above
 477
 478   /** the safety pattern */
 479   static const char fgkSafetyPattern[];                            //!transient
 480
 481   //////////////////////////////////////////////////////////////////////////////
 482   // internal helper functions
 483
 484   /**
 485    * Find the consumer descriptor for a certain component and data type in
 486    * a list of consumers.<br>
 487    * <b>Note:</b> There are three lists which contain the consumers in the
 488    * different states.
 489    * @param pConsumer       pointer to consumer component
 490    * @param list            list where to search for the consumer
 491    */
 492   AliHLTConsumerDescriptor* FindConsumer(const AliHLTComponent* pConsumer,
 493                                          AliHLTConsumerDescriptorPList &list) const;
 494
 495   /**
 496    * Change the state of a consumer.
 497    * The state of a consumer is determined by the list it is strored in, the
 498    * method moves a consumer from the source to the target list.
 499    * @param pDesc           pointer to consumer descriptor
 500    * @param srcList         list where the consumer is currently to be found
 501    * @param tgtList         list where to move the consumer
 502    */
 503   int ChangeConsumerState(AliHLTConsumerDescriptor* pDesc,
 504                           AliHLTConsumerDescriptorPList &srcList,
 505                           AliHLTConsumerDescriptorPList &tgtList);
 506
 507   /**
 508    * Cleanup a consumer list.
 509    * Release all allocated data structures. <b>Note:</b> Not the component itself!
 510    */
 511   int CleanupConsumerList();
 512
 513   ClassDef(AliHLTDataBuffer, 0)
 514 };
 515
 516 #endif // ALIHLTDATABUFFER_H