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