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
  16 #include <vector>
  17 #include "AliHLTLogging.h"
  18 #include "AliHLTModuleAgent.h"
  19
  20 class AliHLTOUTHandler;
  21 class AliHLTOUTHandlerDesc;
  22
  23 #define AliHLTOUTInvalidIndex (~(AliHLTUInt32_t)0)
  24
  25 typedef vector<AliHLTUInt32_t> AliHLTOUTIndexList;
  26
  27 /**
  28  * @class AliHLTOUT
  29  * The control class for HLTOUT data.
  30  * The output of the HLT, either from the HLTOUT nodes or simulated output,
  31  * is transferred and stored in the HOMER format. The AliHLTOUT class
  32  * implements scanning of the HOMER data for all HLTOUT DDL links and
  33  * abstracts access to the complete HLTOUT data.
  34  *
  35  */
  36 class AliHLTOUT : public AliHLTLogging {
  37  public:
  38   /** standard constructor */
  39   AliHLTOUT();
  40   /** standard destructor */
  41   virtual ~AliHLTOUT();
  42
  43   /**
  44    * Init for processing.
  45    * The HLTOUT is scanned for all available data blocks and the
  46    * AliHLTOUTHandler objects for the data blocks are created according
  47    * to the module agents (see AliHLTModuleAgent).
  48    */
  49   int Init();
  50
  51   /**
  52    * Get number of data blocks in the HLTOUT data
  53    */
  54   int GetNofDataBlocks();
  55
  56   /**
  57    * Select the first data block of a certain data type and specification.
  58    * The selection criteria can be of kAliHLTAnyDataType and/or
  59    * kAliHLTVoidDataSpec in order to be ignored and just match any data block.
  60    *
  61    * The search criteria can be combined with a handler type (e.g. kRawReader)
  62    * @param dt    [in]  data type to match                                <br>
  63    * @param spec  [in]  data specification to match                       <br>
  64    * @param handlerType [in]  type of the handler
  65    * @return identifier >0 if success, 0 if no block found                <br>
  66    *         neg. error code if failed                                    <br>
  67    *                        -EPERM if access denied (object locked)
  68    */
  69   int SelectFirstDataBlock(AliHLTComponentDataType dt, AliHLTUInt32_t spec,
  70                            AliHLTModuleAgent::AliHLTOUTHandlerType handlerType=AliHLTModuleAgent::kUnknownOutput);
  71
  72   /**
  73    * Select the next data block of data type and specification of the previous
  74    * call to @ref SelectFirstDataBlock.
  75    * @return identifier >0 if success, 0 if no block found                <br>
  76    *         neg. error code if failed                                    <br>
  77    *                        -EPERM if access denied (object locked)
  78    */
  79   int SelectNextDataBlock();
  80
  81   /**
  82    * Get properties of the selected data block.
  83    * @param dt    [out] data type of the selected block
  84    * @param spec  [out] data specification of the selected block
  85    */
  86   int GetDataBlockDescription(AliHLTComponentDataType& dt, AliHLTUInt32_t& spec);
  87
  88   /**
  89    * Get the index of the current data block.
  90    * @return index, AliHLTOUTInvalidIndex if no block selected
  91    */
  92   AliHLTUInt32_t GetDataBlockIndex();
  93
  94   /**
  95    * Get buffer of the selected data block.
  96    * @param pBuffer [out] buffer of the selected data block
  97    * @param size    [out] size of the selected data block
  98    */
  99   int GetDataBuffer(const AliHLTUInt8_t* &pBuffer, AliHLTUInt32_t& size);
 100
 101   /**
 102    * Release buffer after use.
 103    * @param pBuffer [in]  buffer of the selected data block
 104    */
 105   int ReleaseDataBuffer(const AliHLTUInt8_t* pBuffer);
 106
 107   /**
 108    * Locking guard for the AliHLTOUT object.
 109    * If the object is locked, the selection of data blocks can not be changed.
 110    */
 111   class AliHLTOUTLockGuard {
 112   public:
 113     /** constructor */
 114     AliHLTOUTLockGuard(AliHLTOUT* pInstance) : fpInstance(pInstance)
 115     {if (fpInstance) fpInstance->SetStatusFlag(kLocked);}
 116     /** destructor */
 117     ~AliHLTOUTLockGuard()
 118     {if (fpInstance) fpInstance->ClearStatusFlag(kLocked);}
 119
 120   private:
 121     /** standard constructor prohibited */
 122     AliHLTOUTLockGuard();
 123     /** copy constructor prohibited */
 124     AliHLTOUTLockGuard(const AliHLTOUTLockGuard&);
 125     /** assignment operator prohibited */
 126     AliHLTOUTLockGuard& operator=(const AliHLTOUTLockGuard&);
 127
 128     /** the AliHLTOUT instance the guard is locking */
 129     AliHLTOUT* fpInstance; //!transient
 130   };
 131
 132   /**
 133    * The HLT OUT Event Header.
 134    * Defined between HLT and DAQ.
 135    */
 136   struct AliHLTOUTEventHeader {
 137     /**Total length of the data in bytes, including HLT event header, excluding CDH. */
 138     AliHLTUInt32_t fLength; //! see above
 139     /** version of the header */
 140     AliHLTUInt32_t fVersion; //! see above
 141     /** event id */
 142     AliHLTUInt64_t fEventID; //! see above
 143   };
 144
 145   // definitions from ALICE internal notes ALICE-INT-2002-010 and
 146   // ALICE-INT-2006-XXX
 147   /** the 32bit word in the CDH containing the status flags */
 148   static const unsigned char fgkCDHStatusWord; //! see above
 149   /** start of the flags in word fgkCDHStatusWord */
 150   static const unsigned char fgkCDHStatusFlagsOffset; //! see above
 151   /** bit indicating HLT decision in the HLTOUT*/
 152   static const unsigned char fgkCDHFlagsHLTDecision; //! see above
 153   /** bit indicating HLT payload in the HLTOUT*/
 154   static const unsigned char fgkCDHFlagsHLTPayload; //! see above
 155
 156   /**
 157    * Block descriptor.
 158    */
 159   class AliHLTOUTBlockDescriptor {
 160   public:
 161     AliHLTOUTBlockDescriptor(AliHLTComponentDataType dt, AliHLTUInt32_t spec, AliHLTUInt32_t index)
 162       : fDataType(dt), fSpecification(spec), fIndex(index) {};
 163     ~AliHLTOUTBlockDescriptor() {}
 164
 165     operator AliHLTComponentDataType() const {return fDataType;}
 166     operator AliHLTUInt32_t() const {return fSpecification;}
 167     int operator==(AliHLTComponentDataType dt) const {return dt==fDataType;}
 168     int operator==(AliHLTUInt32_t spec) const {return spec==fSpecification;}
 169
 170     AliHLTUInt32_t GetIndex() const {return fIndex;}
 171   private:
 172     /** data type of the block */
 173     AliHLTComponentDataType fDataType; //!transient
 174     /** data specification of the block */
 175     AliHLTUInt32_t          fSpecification; //!transient
 176     /** index in the data stream */
 177     AliHLTUInt32_t          fIndex; //!transient
 178   };
 179
 180   enum AliHLTOUTByteOrder_t {
 181     /** no data block selected */
 182     kInvalidByteOrder=-1,
 183     kUnknownByteOrder=0,
 184     kLittleEndian,
 185     kBigEndian
 186   };
 187
 188   enum AliHLTOUTDataType_t {
 189     kUint64 = 0,
 190     kUint32 = 1,
 191     kUint16 = 2,
 192     kUint8  = 3,
 193     kDouble = 4,
 194     kFloat  = 5
 195   };
 196
 197   /**
 198    * Check byte order of selected block
 199    */
 200   AliHLTOUTByteOrder_t CheckByteOrder();
 201
 202   /**
 203    * Check alignment of selected block
 204    */
 205   int CheckAlignment(AliHLTOUT::AliHLTOUTDataType_t type);
 206
 207  protected:
 208   /**
 209    * Add a block descriptor.
 210    * This is done by the child classes generating the index. The AliHLTOUT
 211    * object must be locked for index generation.
 212    * @param desc    the block descriptor
 213    * @return 0 if success, -EPERM if access denied
 214    */
 215   int AddBlockDescriptor(const AliHLTOUTBlockDescriptor desc);
 216
 217  private:
 218   /** copy constructor prohibited */
 219   AliHLTOUT(const AliHLTOUT&);
 220   /** assignment operator prohibited */
 221   AliHLTOUT& operator=(const AliHLTOUT&);
 222
 223   /**
 224    * Internal status flags
 225    */
 226   enum {
 227     /** the HLTOUT object is locked with the current data block */
 228     kLocked = 0x1,
 229     /** childs can add block descriptors */
 230     kCollecting = 0x2,
 231     /** user of the data block has checked the byte order */
 232     kByteOrderChecked = 0x4,
 233     /** warning on byte order missmatch has been printed */
 234     kByteOrderWarning = 0x8,
 235     /** user of the data block has checked the alignment */
 236     kAlignmentChecked = 0x10,
 237     /** warning on alignment missmatch has been printed */
 238     kAlignmentWarning = 0x20
 239   };
 240
 241   class AliHLTOUTHandlerListEntry {
 242   public:
 243     AliHLTOUTHandlerListEntry(AliHLTOUTHandler* pHandler,
 244                               AliHLTModuleAgent::AliHLTOUTHandlerDesc& handlerDesc,
 245                               AliHLTModuleAgent* pAgent,
 246                               AliHLTUInt32_t index);
 247
 248     /** copy constructor for vector handling */
 249     AliHLTOUTHandlerListEntry(const AliHLTOUTHandlerListEntry& src);
 250
 251     /** assignment operator for vector handling */
 252     AliHLTOUTHandlerListEntry& operator=(const AliHLTOUTHandlerListEntry& src);
 253
 254     ~AliHLTOUTHandlerListEntry();
 255
 256     operator AliHLTOUTHandler*() const {return fpHandler;}
 257     operator AliHLTModuleAgent::AliHLTOUTHandlerDesc&() {return fHandlerDesc;}
 258     operator AliHLTModuleAgent*() const {return fpAgent;}
 259
 260     bool operator==(const AliHLTOUTHandlerListEntry& entry) const;
 261
 262     AliHLTUInt32_t operator[](int i) const;
 263
 264     void AddIndex(AliHLTUInt32_t index);
 265
 266   private:
 267     /** standard constructor prohibited */
 268     AliHLTOUTHandlerListEntry();
 269
 270     /** pointer to the handler */
 271     AliHLTOUTHandler* fpHandler; //! transient
 272
 273     /** pointer to handler description */
 274     AliHLTModuleAgent::AliHLTOUTHandlerDesc fHandlerDesc; //! transient
 275
 276     /** pointer to module agent */
 277     AliHLTModuleAgent* fpAgent; //! transient
 278
 279     /** list of block indexes */
 280     AliHLTOUTIndexList fBlocks; //!transient
 281   };
 282
 283   /**
 284    * Generate the index of the HLTOUT data.
 285    * Must be implemented by the child classes.
 286    */
 287   virtual int GenerateIndex()=0;
 288
 289   /**
 290    * Find AliHLTOUTHandler objects for the data blocks.
 291    * The available AliHLTModuleAgents are probed whether they provide
 292    * handlers for data processing.
 293    */
 294   int InitHandlers();
 295
 296   /**
 297    * Get the data buffer
 298    * @param index   [in]  index of the block
 299    * @param pBuffer [out] buffer of the selected data block
 300    * @param size    [out] size of the selected data block
 301    */
 302   virtual int GetDataBuffer(AliHLTUInt32_t index, const AliHLTUInt8_t* &pBuffer,
 303                             AliHLTUInt32_t& size)=0;
 304
 305   /**
 306    * Check byte order of data block
 307    */
 308   virtual AliHLTOUTByteOrder_t CheckBlockByteOrder(AliHLTUInt32_t index)=0;
 309
 310   /**
 311    * Check alignment of data block
 312    */
 313   virtual int CheckBlockAlignment(AliHLTUInt32_t index, AliHLTOUT::AliHLTOUTDataType_t type)=0;
 314
 315   /**
 316    * Select the data block of data type and specification of the previous
 317    * call to @ref SelectFirstDataBlock. Core function of @ref SelectFirstDataBlock
 318    * and @ref SelectNextDataBlock, starts to find a block at the current list
 319    * position.
 320    * @return identifier >=0 if success, neg. error code if failed         <br>
 321    *                        -ENOENT if no block found                     <br>
 322    *                        -EPERM if access denied (object locked)
 323    */
 324   int FindAndSelectDataBlock();
 325
 326   /**
 327    * Set status flag.
 328    * @param flag     flag to set
 329    * @return current status flags
 330    */
 331   unsigned int SetStatusFlag(unsigned int flag) {return fFlags|=flag;}
 332
 333   /**
 334    * Clear status flag.
 335    * @param flag     flag to clear
 336    * @return current status flags
 337    */
 338   unsigned int ClearStatusFlag(unsigned int flag) {return fFlags&=~flag;}
 339
 340   /**
 341    * Check status flag.
 342    * @param flag     flag to check
 343    * @return 1 if flag is set
 344    */
 345   int CheckStatusFlag(unsigned int flag) const {return (fFlags&flag)==flag;}
 346
 347   /**
 348    * Insert a handler item.
 349    * The current list entries are checked if the handler is already in
 350    * the list. It is added if not in the list, otherwise the block index
 351    * is added to the existing entry.
 352    * @param entry    handler list entry
 353    * @return 0 if added, EEXIST (non negative!) if merged with existing entry <br>
 354    *         neg. error code if failed
 355    */
 356   int InsertHandler(const AliHLTOUTHandlerListEntry &entry);
 357
 358   /** data type for the current block search, set from @ref SelectFirstDataBlock */
 359   AliHLTComponentDataType fSearchDataType; //!transient
 360
 361   /** data specification for the current block search */
 362   AliHLTUInt32_t fSearchSpecification; //!transient
 363
 364   /** instance flags: locked, collecting, ... */
 365   unsigned int fFlags; //!transient
 366
 367   /** list of block descriptors */
 368   vector<AliHLTOUTBlockDescriptor> fBlockDescList; //!transient
 369
 370   /** current position in the list */
 371   vector<AliHLTOUTBlockDescriptor>::iterator fCurrent; //!transient
 372
 373   /** data buffer under processing */
 374   const AliHLTUInt8_t* fpBuffer; //!transient
 375
 376   /** list of AliHLTOUTHandlers */
 377   vector<AliHLTOUTHandlerListEntry> fDataHandlers; // !transient
 378
 379   ClassDef(AliHLTOUT, 1)
 380 };
 381 #endif