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