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