HLT/BASE/AliHLTOUT.h

   1 //-*- Mode: C++ -*-
   2 // @(#) $Id$
   3
   4 #ifndef ALIHLTOUT_H
   5 #define ALIHLTOUT_H
   6 /* This file is property of and copyright by the ALICE HLT Project        *
   7  * ALICE Experiment at CERN, All rights reserved.                         *
   8  * See cxx source for full Copyright notice                               */
   9
  10 /** @file   AliHLTOUT.h
  11     @author Matthias Richter
  12     @date
  13     @brief  The control class for HLTOUT data.
  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                                                                           */
  22 #include <vector>
  23 #include "AliHLTLogging.h"
  24
  25 /**
  26  * @class AliHLTOUT
  27  * The control class for HLTOUT data.
  28  * The output of the HLT, either from the HLTOUT nodes or simulated output,
  29  * is transferred and stored in the HOMER format. The AliHLTOUT class
  30  * implements scanning of the HOMER data for all HLTOUT DDL links and
  31  * abstracts access to the complete HLTOUT data.
  32  *
  33  */
  34 class AliHLTOUT : public AliHLTLogging {
  35  public:
  36   /** standard constructor */
  37   AliHLTOUT();
  38   /** standard destructor */
  39   virtual ~AliHLTOUT();
  40
  41   /**
  42    * Get number of data blocks in the HLTOUT data
  43    */
  44   int GetNofDataBlocks();
  45
  46   /**
  47    * Select the first data block of a certain data type and specification.
  48    * The selection criteria can be of kAliHLTAnyDataType and/or
  49    * kAliHLTVoidDataSpec in order to be ignored and just match any data block.
  50    * @param dt    [in]  data type to match                                <br>
  51    * @param spec  [in]  data specification to match                       <br>
  52    * @return identifier >=0 if success, neg. error code if failed         <br>
  53    *                        -ENOENT if no block found                     <br>
  54    *                        -EPERM if access denied (object locked)
  55    */
  56   int SelectFirstDataBlock(AliHLTComponentDataType dt, AliHLTUInt32_t spec);
  57
  58   /**
  59    * Select the next data block of data type and specification of the previous
  60    * call to @ref SelectFirstDataBlock.
  61    * @return identifier >=0 if success, neg. error code if failed         <br>
  62    *                        -ENOENT if no block found                     <br>
  63    *                        -EPERM if access denied (object locked)
  64    */
  65   int SelectNextDataBlock();
  66
  67   /**
  68    * Get properties of the selected data block.
  69    * @param dt    [out] data type of the selected block
  70    * @param spec  [out] data specification of the selected block
  71    */
  72   int GetDataBlockDescription(AliHLTComponentDataType& dt, AliHLTUInt32_t& spec);
  73
  74   /**
  75    * Get buffer of the selected data block.
  76    * @param pBuffer [out] buffer of the selected data block
  77    * @param size    [out] size of the selected data block
  78    */
  79   int GetDataBuffer(const AliHLTUInt8_t* &pBuffer, AliHLTUInt32_t& size);
  80
  81   /**
  82    * Release buffer after use.
  83    * @param pBuffer [in]  buffer of the selected data block
  84    */
  85   int ReleaseDataBuffer(const AliHLTUInt8_t* pBuffer);
  86
  87   /**
  88    * Locking guard for the AliHLTOUT object.
  89    * If the object is locked, the selection of data blocks can not be changed.
  90    */
  91   class AliHLTOUTLockGuard {
  92   public:
  93     /** constructor */
  94     AliHLTOUTLockGuard(AliHLTOUT* pInstance) : fpInstance(pInstance)
  95     {if (fpInstance) fpInstance->SetStatusFlag(kLocked);}
  96     /** destructor */
  97     ~AliHLTOUTLockGuard()
  98     {if (fpInstance) fpInstance->ClearStatusFlag(kLocked);}
  99
 100   private:
 101     /** standard constructor prohibited */
 102     AliHLTOUTLockGuard();
 103     /** copy constructor prohibited */
 104     AliHLTOUTLockGuard(const AliHLTOUTLockGuard&);
 105     /** assignment operator prohibited */
 106     AliHLTOUTLockGuard& operator=(const AliHLTOUTLockGuard&);
 107
 108     /** the AliHLTOUT instance the guard is locking */
 109     AliHLTOUT* fpInstance; //!transient
 110   };
 111
 112   /**
 113    * Block descriptor.
 114    */
 115   class AliHLTOUTBlockDescriptor {
 116   public:
 117     AliHLTOUTBlockDescriptor(AliHLTComponentDataType dt, AliHLTUInt32_t spec, AliHLTUInt32_t index)
 118       : fDataType(dt), fSpecification(spec), fIndex(index) {};
 119     ~AliHLTOUTBlockDescriptor() {}
 120
 121     operator AliHLTComponentDataType() const {return fDataType;}
 122     operator AliHLTUInt32_t() const {return fSpecification;}
 123     int operator==(AliHLTComponentDataType dt) const {return dt==fDataType;}
 124     int operator==(AliHLTUInt32_t spec) const {return spec==fSpecification;}
 125
 126     AliHLTUInt32_t GetIndex() const {return fIndex;}
 127   private:
 128     /** data type of the block */
 129     AliHLTComponentDataType fDataType; //!transient
 130     /** data specification of the block */
 131     AliHLTUInt32_t          fSpecification; //!transient
 132     /** index in the data stream */
 133     AliHLTUInt32_t          fIndex; //!transient
 134   };
 135
 136   enum AliHLTOUTByteOrder_t {
 137     /** no data block selected */
 138     kInvalidByteOrder=-1,
 139     kUnknownByteOrder=0,
 140     kLittleEndian,
 141     kBigEndian
 142   };
 143
 144   enum AliHLTOUTDataType_t {
 145     kUint64 = 0,
 146     kUint32 = 1,
 147     kUint16 = 2,
 148     kUint8  = 3,
 149     kDouble = 4,
 150     kFloat  = 5
 151   };
 152
 153   /**
 154    * Check byte order of selected block
 155    */
 156   AliHLTOUTByteOrder_t CheckByteOrder();
 157
 158   /**
 159    * Check alignment of selected block
 160    */
 161   int CheckAlignment(AliHLTOUT::AliHLTOUTDataType_t type);
 162
 163  protected:
 164   /**
 165    * Add a block descriptor.
 166    * This is done by the child classes generating the index. The AliHLTOUT
 167    * object must be locked for index generation.
 168    * @param desc    the block descriptor
 169    * @return 0 if success, -EPERM if access denied
 170    */
 171   int AddBlockDescriptor(const AliHLTOUTBlockDescriptor desc);
 172
 173  private:
 174   /** copy constructor prohibited */
 175   AliHLTOUT(const AliHLTOUT&);
 176   /** assignment operator prohibited */
 177   AliHLTOUT& operator=(const AliHLTOUT&);
 178
 179   /**
 180    * Internal status flags
 181    */
 182   enum {
 183     /** the HLTOUT object is locked with the current data block */
 184     kLocked = 0x1,
 185     /** childs can add block descriptors */
 186     kCollecting = 0x2,
 187     /** user of the data block has checked the byte order */
 188     kByteOrderChecked = 0x4,
 189     /** warning on byte order missmatch has been printed */
 190     kByteOrderWarning = 0x8,
 191     /** user of the data block has checked the alignment */
 192     kAlignmentChecked = 0x10,
 193     /** warning on alignment missmatch has been printed */
 194     kAlignmentWarning = 0x20
 195   };
 196
 197   /**
 198    * Generate the index of the HLTOUT data.
 199    * Must be implemented by the child classes.
 200    */
 201   virtual int GenerateIndex()=0;
 202
 203   /**
 204    * Get the data buffer
 205    * @param index   [in]  index of the block
 206    * @param pBuffer [out] buffer of the selected data block
 207    * @param size    [out] size of the selected data block
 208    */
 209   virtual int GetDataBuffer(AliHLTUInt32_t index, const AliHLTUInt8_t* &pBuffer,
 210                             AliHLTUInt32_t& size)=0;
 211
 212   /**
 213    * Check byte order of data block
 214    */
 215   virtual AliHLTOUTByteOrder_t CheckBlockByteOrder(AliHLTUInt32_t index)=0;
 216
 217   /**
 218    * Check alignment of data block
 219    */
 220   virtual int CheckBlockAlignment(AliHLTUInt32_t index, AliHLTOUT::AliHLTOUTDataType_t type)=0;
 221
 222   /**
 223    * Select the data block of data type and specification of the previous
 224    * call to @ref SelectFirstDataBlock. Core function of @ref SelectFirstDataBlock
 225    * and @ref SelectNextDataBlock, starts to find a block at the current list
 226    * position.
 227    * @return identifier >=0 if success, neg. error code if failed         <br>
 228    *                        -ENOENT if no block found                     <br>
 229    *                        -EPERM if access denied (object locked)
 230    */
 231   int FindAndSelectDataBlock();
 232
 233   /**
 234    * Set status flag.
 235    * @param flag     flag to set
 236    * @return current status flags
 237    */
 238   unsigned int SetStatusFlag(unsigned int flag) {return fFlags|=flag;}
 239
 240   /**
 241    * Clear status flag.
 242    * @param flag     flag to clear
 243    * @return current status flags
 244    */
 245   unsigned int ClearStatusFlag(unsigned int flag) {return fFlags&=~flag;}
 246
 247   /**
 248    * Check status flag.
 249    * @param flag     flag to check
 250    * @return 1 if flag is set
 251    */
 252   int CheckStatusFlag(unsigned int flag) const {return (fFlags&flag)==flag;}
 253
 254   /** data type for the current block search, set from @ref SelectFirstDataBlock */
 255   AliHLTComponentDataType fSearchDataType; //!transient
 256
 257   /** data specification for the current block search */
 258   AliHLTUInt32_t fSearchSpecification; //!transient
 259
 260   /** instance flags: locked, collecting, ... */
 261   unsigned int fFlags; //!transient
 262
 263   /** list of block descriptors */
 264   vector<AliHLTOUTBlockDescriptor> fBlockDescList; //!transient
 265
 266   /** current position in the list */
 267   vector<AliHLTOUTBlockDescriptor>::iterator fCurrent; //!transient
 268
 269   /** data buffer under processing */
 270   const AliHLTUInt8_t* fpBuffer; //!transient
 271
 272   ClassDef(AliHLTOUT, 0)
 273 };
 274 #endif