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