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