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