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