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    * @class AliHLTDataSegment
 230    * @brief  Descriptor of a data segment within the buffer.
 231    */
 232   class AliHLTDataSegment {
 233     friend class AliHLTDataBuffer;
 234     friend class AliHLTConsumerDescriptor;
 235   public:
 236     AliHLTDataSegment()
 237       :
 238       fDataType(kAliHLTVoidDataType),
 239       fPtr(NULL),
 240       fSegmentOffset(0),
 241       fSegmentSize(0),
 242       fSpecification(0)
 243     {
 244     }
 245
 246     AliHLTDataSegment(AliHLTUInt8_t* ptr, AliHLTUInt32_t offset, AliHLTUInt32_t size)
 247       :
 248       fDataType(kAliHLTVoidDataType),
 249       fPtr(ptr),
 250       fSegmentOffset(offset),
 251       fSegmentSize(size),
 252       fSpecification(0)
 253     {
 254     }
 255
 256     AliHLTDataSegment(void* ptr, AliHLTUInt32_t offset, AliHLTUInt32_t size)
 257       :
 258       fDataType(kAliHLTVoidDataType),
 259       fPtr((AliHLTUInt8_t*)ptr),
 260       fSegmentOffset(offset),
 261       fSegmentSize(size),
 262       fSpecification(0)
 263     {
 264     }
 265
 266     AliHLTDataSegment(void* ptr, AliHLTUInt32_t offset, AliHLTUInt32_t size, AliHLTComponentDataType dt, AliHLTUInt32_t spec)
 267       :
 268       fDataType(dt),
 269       fPtr((AliHLTUInt8_t*)ptr),
 270       fSegmentOffset(offset),
 271       fSegmentSize(size),
 272       fSpecification(spec)
 273     {
 274     }
 275
 276     AliHLTUInt8_t* GetPtr() const {return (AliHLTUInt8_t*)*this;}
 277
 278     AliHLTUInt32_t GetSize() const {return fSegmentSize;}
 279
 280     int operator==(const AliHLTDataSegment& seg) const
 281     {
 282       return (fPtr+fSegmentOffset==seg.fPtr+seg.fSegmentOffset) && (fSegmentSize==seg.fSegmentSize);
 283     }
 284     operator AliHLTUInt8_t*() const {return fPtr+fSegmentOffset;}
 285
 286   private:
 287     /** the data type of this segment */
 288     AliHLTComponentDataType fDataType;                             // see above
 289     /** pointer to the buffer */
 290     AliHLTUInt8Pointer_t fPtr;                                     //!transient
 291     /** offset in byte within the data buffer */
 292     AliHLTUInt32_t fSegmentOffset;                                 // see above
 293     /** size of the actual content */
 294     AliHLTUInt32_t fSegmentSize;                                   // see above
 295     /** data specification */
 296     AliHLTUInt32_t fSpecification;                                 // see above
 297   };
 298
 299   /**
 300    * @class AliHLTRawBuffer
 301    * @brief  Descriptor of the raw data buffer which can host several segments.
 302    */
 303   class AliHLTRawBuffer {
 304   public:
 305     /** standard constructor */
 306     AliHLTRawBuffer() : fSize(0), fTotalSize(0), fPtr(NULL) {}
 307     /** constructor */
 308     AliHLTRawBuffer(AliHLTUInt32_t size);
 309     /** destructor */
 310     virtual ~AliHLTRawBuffer();
 311
 312     /**
 313      * Use a fraction of the buffer.
 314      * @param size    size in bytes to be used
 315      * @return pointer to buffer
 316      */
 317     AliHLTUInt8_t* UseBuffer(AliHLTUInt32_t size);
 318
 319     /**
 320      * Check whether buffer fits for a request.
 321      * @param size    size of the request in bytes
 322      * @return 1 if buffer is big enough, 0 if not
 323      */
 324     int CheckSize(AliHLTUInt32_t size) const;
 325
 326     /**
 327      * Get used size of the buffer
 328      */
 329     AliHLTUInt32_t GetUsedSize() const {return fSize;}
 330
 331     /**
 332      * Get total size of the buffer
 333      */
 334     AliHLTUInt32_t GetTotalSize() const {return fTotalSize;}
 335
 336     /**
 337      * Get pointer of data buffer
 338      */
 339     AliHLTUInt8_t* GetPointer() const {return fPtr;}
 340
 341     /**
 342      * Write check pattern
 343      */
 344     int WritePattern(const char* pattern, int size);
 345
 346     /**
 347      * Check pattern
 348      */
 349     int CheckPattern(const char* pattern, int size) const;
 350
 351     /**
 352      * Reset buffer.
 353      * Data buffer remains allocated, used size set to 0
 354      */
 355     int Reset();
 356
 357     int operator==(void*) const;
 358     int operator==(AliHLTUInt8_t* ptr) const {return fPtr==ptr;}
 359     int operator<=(void*) const;
 360     int operator>(void*) const;
 361     int operator-(void*) const;
 362
 363     operator void*() const {return fPtr;}
 364     operator AliHLTUInt8_t*() const {return fPtr;}
 365
 366   private:
 367     /** copy constructor prohibited */
 368     AliHLTRawBuffer(const AliHLTRawBuffer&);
 369     /** assignment operator prohibited */
 370     AliHLTRawBuffer& operator=(const AliHLTRawBuffer&);
 371
 372     /** size of the currently occupied partition of the buffer */
 373     AliHLTUInt32_t fSize;                                          // see above
 374     /** total size of the buffer, including safety margin */
 375     AliHLTUInt32_t fTotalSize;                                     // see above
 376     /** the buffer */
 377     AliHLTUInt8_t* fPtr;                                           //! transient
 378   };
 379
 380  private:
 381   /** copy constructor prohibited */
 382   AliHLTDataBuffer(const AliHLTDataBuffer&);
 383   /** assignment operator prohibited */
 384   AliHLTDataBuffer& operator=(const AliHLTDataBuffer&);
 385
 386   /* lets see if this is needed
 387      AliHLTDataSegment* FindDataSegment(AliHLTComponentDataType datatype);
 388   */
 389
 390   /**
 391    * Find those data segments which match the input types of a component.
 392    * @param pConsumer       the component which subscribes to the buffer
 393    * @param tgtList         the list to receive the data segment descriptors
 394    * @return: number of data blocks which match the input data types
 395    *          of the consumer, neg. error code if failed <br>
 396    *          -EINVAL       invalid parameter <br>
 397    */
 398   int FindMatchingDataSegments(const AliHLTComponent* pConsumer,
 399                                vector<AliHLTDataBuffer::AliHLTDataSegment>& tgtList);
 400
 401   /**
 402    * Reset the data buffer.
 403    * Removes all consumers back to the @ref fConsumers list, deletes
 404    * segments and releases the Raw Buffer.
 405    */
 406   int ResetDataBuffer();
 407
 408   //////////////////////////////////////////////////////////////////////////////
 409
 410   // the data description
 411
 412   // the data segments within this buffer
 413   vector<AliHLTDataSegment> fSegments;                             // see above
 414
 415   // the list of all consumers which are going to subscribe to the buffer
 416   AliHLTConsumerDescriptorPList fConsumers;                         // see above
 417   // the list of all consumers which are currently subscribed to the buffer
 418   AliHLTConsumerDescriptorPList fActiveConsumers;                   // see above
 419   // the list of all consumers which are already released for the current event
 420   AliHLTConsumerDescriptorPList fReleasedConsumers;                 // see above
 421
 422   // the buffer instance
 423   AliHLTRawBuffer* fpBuffer;                                       //! transient
 424
 425   // flags indicating the state of the buffer
 426   AliHLTUInt32_t fFlags;                                           // see above
 427
 428   /** list of tasks with forwarded data blocks */
 429   vector<AliHLTTask*> fForwardedSegmentSources;                    //! transient
 430
 431   /** list of forwarded block descriptors */
 432   vector<AliHLTDataSegment> fForwardedSegments;                    //! transient
 433
 434   //////////////////////////////////////////////////////////////////////////////
 435   // global buffer handling, internal use only
 436
 437   /**
 438    * Create a raw buffer of a certain size.
 439    * The function tries to find a buffer of the given size (or a bit bigger by a
 440    * certain margin @ref fgMargin) from the list of free buffers.
 441    * If no buffer is available, a new one is created and added to the buffer handling.
 442    * @param size            min. size of the requested buffer
 443    * @return pointer to raw buffer
 444    */
 445   static AliHLTRawBuffer* CreateRawBuffer(AliHLTUInt32_t size);
 446
 447   /**
 448    * Mark a buffer as free.
 449    * After the Data Buffer has finnished using the raw buffer, it is released
 450    * and added to the list of available buffers.
 451    * @param pBuffer         the raw buffer to release
 452    * @return >=0 if succeeded, neg. error code if failed
 453    */
 454   static int ReleaseRawBuffer(AliHLTRawBuffer* pBuffer);
 455
 456   /**
 457    * Deletes all the raw buffers.
 458    * When the last Data Buffer object is destructed, all raw data buffers are
 459    * relesed.
 460    */
 461   static int DeleteRawBuffers();
 462
 463   /**
 464    * Number of instances of AliHLTDataBuffer.
 465    * The statice variable is incremented and decremented in the constructor/
 466    * destructor. All internal data structures are cleaned up when the last
 467    * instance is exiting.
 468    */
 469   static int fgNofInstances;                                       // see above
 470   /** global list of free raw buffers */
 471   static vector<AliHLTRawBuffer*> fgFreeBuffers;                   // see above
 472   /** global list of currently active raw buffers */
 473   static vector<AliHLTRawBuffer*> fgActiveBuffers;                 // see above
 474   /** determines the raw buffer size margin at buffer requests */
 475   static AliHLTUInt32_t fgMargin;                                  // see above
 476
 477   /** global instance to HLT logging class for static methods */
 478   static AliHLTLogging fgLogging;                                  // see above
 479
 480   /** size of the safety pattern */
 481   static const Int_t fgkSafetyPatternSize;                         // see above
 482
 483   /** the safety pattern */
 484   static const char fgkSafetyPattern[];                            //!transient
 485
 486   //////////////////////////////////////////////////////////////////////////////
 487   // internal helper functions
 488
 489   /**
 490    * Find the consumer descriptor for a certain component and data type in
 491    * a list of consumers.<br>
 492    * <b>Note:</b> There are three lists which contain the consumers in the
 493    * different states.
 494    * @param pConsumer       pointer to consumer component
 495    * @param list            list where to search for the consumer
 496    */
 497   AliHLTConsumerDescriptor* FindConsumer(const AliHLTComponent* pConsumer,
 498                                          AliHLTConsumerDescriptorPList &list) const;
 499
 500   /**
 501    * Change the state of a consumer.
 502    * The state of a consumer is determined by the list it is strored in, the
 503    * method moves a consumer from the source to the target list.
 504    * @param pDesc           pointer to consumer descriptor
 505    * @param srcList         list where the consumer is currently to be found
 506    * @param tgtList         list where to move the consumer
 507    */
 508   int ChangeConsumerState(AliHLTConsumerDescriptor* pDesc,
 509                           AliHLTConsumerDescriptorPList &srcList,
 510                           AliHLTConsumerDescriptorPList &tgtList);
 511
 512   /**
 513    * Cleanup a consumer list.
 514    * Release all allocated data structures. <b>Note:</b> Not the component itself!
 515    */
 516   int CleanupConsumerList();
 517
 518   ClassDef(AliHLTDataBuffer, 0)
 519 };
 520
 521 #endif // ALIHLTDATABUFFER_H