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                          *
   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; // AliHLTModuleAgent.h
  22 class AliESDEvent;
  23 class AliHLTReconstructor;
  24 class AliRawReader;
  25 class TTree;
  26
  27 #define AliHLTOUTInvalidIndex (~(AliHLTUInt32_t)0)
  28
  29 using std::vector;
  30
  31 typedef vector<AliHLTUInt32_t> AliHLTOUTIndexList;
  32
  33 /**
  34  * @class AliHLTOUT
  35  * The control class for HLTOUT data.
  36  * The output of the HLT, either from the HLTOUT nodes or simulated output,
  37  * is transferred and stored in the HOMER format. The AliHLTOUT class
  38  * implements scanning of the HOMER data for all HLTOUT DDL links and
  39  * abstracts access to the complete HLTOUT data.
  40  *
  41  */
  42 class AliHLTOUT {
  43  public:
  44   /** standard constructor */
  45   AliHLTOUT();
  46   /** standard destructor */
  47   virtual ~AliHLTOUT();
  48
  49   typedef const AliHLTUInt8_t* AliConstExternalBuffer;
  50
  51   /**
  52    * Create an AliHLTOUTRawReader instance.
  53    * Helper function to transparently access classes from the
  54    * libHLTrec library.
  55    */
  56   static AliHLTOUT* New(AliRawReader* pRawReader);
  57
  58   /**
  59    * Create an AliHLTOUTDigitReader instance
  60    * Helper function to transparently access classes from the
  61    * libHLTrec library.
  62    */
  63   static AliHLTOUT* New(TTree* pDigitTree, int event=-1);
  64
  65   /**
  66    * Create an AliHLTOUTDigitReader instance
  67    * Helper function to transparently access classes from the
  68    * libHLTrec library.
  69    */
  70   static AliHLTOUT* New(const char* filename, int event=-1);
  71
  72   /**
  73    * Get the global instance.
  74    * The global instance is set temporarily by the AliHLTOUTGlobalInstanceGuard
  75    * mainly for the sake of data input to an analysis chain. The
  76    * AliHLTOUTPublisherComponent objects can access the global instance.
  77    */
  78   static AliHLTOUT* GetGlobalInstance() {return fgGlobalInstance;}
  79
  80   /**
  81    * Delete an instance of the HLTOUT.
  82    * Helper function to transparently access classes from the
  83    * libHLTrec library. Before deleting, the availability of the
  84    * library is checked.
  85    */
  86   static void Delete(AliHLTOUT* pInstance);
  87
  88   /**
  89    * Locking guard for the AliHLTOUT object.
  90    * If the object is locked, the selection of data blocks can not be changed.
  91    */
  92   class AliHLTOUTLockGuard {
  93   public:
  94     /** constructor */
  95     AliHLTOUTLockGuard(AliHLTOUT* pInstance) : fpInstance(pInstance)
  96     {if (fpInstance) fpInstance->SetStatusFlag(kLocked);}
  97     /** destructor */
  98     ~AliHLTOUTLockGuard()
  99     {if (fpInstance) fpInstance->ClearStatusFlag(kLocked);}
 100
 101   private:
 102     /** standard constructor prohibited */
 103     AliHLTOUTLockGuard();
 104     /** copy constructor prohibited */
 105     AliHLTOUTLockGuard(const AliHLTOUTLockGuard&);
 106     /** assignment operator prohibited */
 107     AliHLTOUTLockGuard& operator=(const AliHLTOUTLockGuard&);
 108
 109     /** the AliHLTOUT instance the guard is locking */
 110     AliHLTOUT* fpInstance; //!transient
 111   };
 112
 113   /**
 114    * Guard for handling of global AliHLTOUT instance.
 115    * The global HLTOUT instance can be set for certain steps of the
 116    * processing. The initial objective is to support input to the
 117    * AliHLTOUTPublisherComponent running in a kChain handler.
 118    *
 119    * The Guard restores the original instance when closed.
 120    */
 121   class AliHLTOUTGlobalInstanceGuard {
 122   public:
 123     /** constructor */
 124     AliHLTOUTGlobalInstanceGuard(AliHLTOUT* pInstance) : fpLastInstance(AliHLTOUT::fgGlobalInstance)
 125     {AliHLTOUT::fgGlobalInstance=pInstance;}
 126     /** destructor */
 127     ~AliHLTOUTGlobalInstanceGuard()
 128     {AliHLTOUT::fgGlobalInstance=fpLastInstance;}
 129
 130   private:
 131     /** standard constructor prohibited */
 132     AliHLTOUTGlobalInstanceGuard();
 133     /** copy constructor prohibited */
 134     AliHLTOUTGlobalInstanceGuard(const AliHLTOUTGlobalInstanceGuard&);
 135     /** assignment operator prohibited */
 136     AliHLTOUTGlobalInstanceGuard& operator=(const AliHLTOUTGlobalInstanceGuard&);
 137
 138     /** the AliHLTOUT instance the guard is locking */
 139     AliHLTOUT* fpLastInstance; //!transient
 140   };
 141
 142   /**
 143    * The HLT OUT Event Header.
 144    * Defined between HLT and DAQ.
 145    */
 146   struct AliHLTOUTEventHeader {
 147     /**Total length of the data in bytes, including HLT event header, excluding CDH. */
 148     AliHLTUInt32_t fLength; //! see above
 149     /** version of the header */
 150     AliHLTUInt32_t fVersion; //! see above
 151     /** High 32 bit word of event id */
 152     AliHLTUInt32_t fEventIDHigh; //! see above
 153     /** Low 32 bit word of event id */
 154     AliHLTUInt32_t fEventIDLow; //! see above
 155   };
 156
 157   enum {
 158     /// versions 1 of the HLT header
 159     kVersion1 = 1,
 160     /// versions 2 of the HLT header
 161     kVersion2 = 2
 162   };
 163
 164   enum {
 165     /// size of HLT decision in data format version 1: 29x4
 166     kSizeDecisionVersion1 = 116,
 167     /// size of HLT decision in data format version 2: 30x4
 168     kSizeDecisionVersion2 = 120
 169   };
 170
 171   // definitions from ALICE internal notes ALICE-INT-2002-010 and
 172   // ALICE-INT-2006-XXX
 173   enum {
 174     /** the 32bit word in the CDH containing the status flags */
 175     kCDHStatusWord=4, //! see above
 176     /** start of the flags in word fgkCDHStatusWord */
 177     kCDHStatusFlagsOffset=12, //! see above
 178     /** bit indicating HLT decision in the HLTOUT*/
 179     kCDHFlagsHLTDecision=6, //! see above
 180     /** bit indicating HLT payload in the HLTOUT*/
 181     kCDHFlagsHLTPayload=7 //! see above
 182   };
 183
 184   class AliHLTOUTHandlerListEntry;
 185   /**
 186    * Block descriptor.
 187    */
 188   class AliHLTOUTBlockDescriptor {
 189   public:
 190     AliHLTOUTBlockDescriptor(AliHLTComponentDataType dt, AliHLTUInt32_t spec, AliHLTUInt32_t index, AliHLTOUT* pCollection)
 191       : fDataType(dt), fSpecification(spec), fIndex(index), fSelected(false), fProcessed(false), fpCollection(pCollection) {};
 192     AliHLTOUTBlockDescriptor(const AliHLTOUTBlockDescriptor& src)
 193       : fDataType(src.fDataType), fSpecification(src.fSpecification), fIndex(src.fIndex), fSelected(false), fProcessed(false), fpCollection(src.fpCollection) {}
 194     AliHLTOUTBlockDescriptor& operator=(const AliHLTOUTBlockDescriptor& src) {
 195       if (this==&src) return *this;
 196       fDataType=src.fDataType; fSpecification=src.fSpecification; fIndex=src.fIndex; fSelected=false; fProcessed=false; fpCollection=src.fpCollection; return *this;
 197     }
 198     ~AliHLTOUTBlockDescriptor() {}
 199
 200     operator AliHLTComponentDataType() const {return fDataType;}
 201     operator AliHLTUInt32_t() const {return fSpecification;}
 202     int operator==(AliHLTComponentDataType dt) const {return dt==fDataType;}
 203     int operator==(AliHLTUInt32_t spec) const {return spec==fSpecification;}
 204     int operator==(AliHLTOUT* collection) const {return collection==fpCollection;}
 205
 206     AliHLTUInt32_t GetIndex() const {return fIndex;}
 207     AliHLTOUT* GetCollection() const {return fpCollection;}
 208
 209     bool IsSelected() const {return fSelected;}
 210     void Select(bool selected=true) {fSelected=selected;}
 211     bool IsProcessed() const {return fProcessed;}
 212     void MarkProcessed() {fProcessed=true;}
 213
 214     /**
 215      * Get the data buffer
 216      * @param [out] pBuffer buffer of the selected data block
 217      * @param [out] size    size of the selected data block
 218      */
 219     int GetDataBuffer(const AliHLTUInt8_t* &pBuffer, AliHLTUInt32_t& size) {
 220       if (fpCollection) return fpCollection->GetDataBuffer(GetIndex(), pBuffer, size);
 221       return -ENODEV;
 222     }
 223
 224     /**
 225      * Get the handler descriptor
 226      */
 227     const AliHLTOUTHandlerListEntry& GetHandlerDesc();
 228
 229     /// print info
 230     void Print(const char* option="") const;
 231
 232   private:
 233     /** data type of the block */
 234     AliHLTComponentDataType fDataType; //!transient
 235     /** data specification of the block */
 236     AliHLTUInt32_t          fSpecification; //!transient
 237     /** index in the data stream */
 238     AliHLTUInt32_t          fIndex; //!transient
 239     /** selection flag */
 240     bool                    fSelected; //!transient
 241     /** processed flag */
 242     bool                    fProcessed; //!transient
 243     /** the collection */
 244     AliHLTOUT*              fpCollection; //!transient
 245   };
 246
 247   class AliHLTOUTHandlerListEntry {
 248   public:
 249     AliHLTOUTHandlerListEntry(AliHLTOUTHandler* pHandler,
 250                               AliHLTModuleAgent::AliHLTOUTHandlerDesc& handlerDesc,
 251                               AliHLTModuleAgent* pAgent,
 252                               AliHLTUInt32_t index);
 253
 254     /** copy constructor for vector handling */
 255     AliHLTOUTHandlerListEntry(const AliHLTOUTHandlerListEntry& src);
 256
 257     /** assignment operator for vector handling */
 258     AliHLTOUTHandlerListEntry& operator=(const AliHLTOUTHandlerListEntry& src);
 259
 260     ~AliHLTOUTHandlerListEntry();
 261
 262     static const AliHLTOUTHandlerListEntry& VoidHandlerListEntry() {return fgkVoidHandlerListEntry;}
 263
 264     operator AliHLTOUTHandler*() const {return fpHandler;}
 265
 266     // please note that fpHandlerDesc is really a pointer and is created
 267     // in the constructor. Thats why it is dereferenced here. The pointer
 268     // type is on purpose, even though it is a bit confusing with the
 269     // argument by reference in the AliHLTOUTHandlerListEntry constructor.
 270     operator const AliHLTModuleAgent::AliHLTOUTHandlerDesc&() const
 271     {return fpHandlerDesc?*fpHandlerDesc:AliHLTModuleAgent::fgkVoidHandlerDesc;}
 272     operator AliHLTModuleAgent*() const {return fpAgent;}
 273
 274     /**
 275      * Two list entries are considered to be equal if the handlers
 276      * are equal.
 277      */
 278     bool operator==(const AliHLTOUTHandlerListEntry& entry) const;
 279
 280     bool operator==(const AliHLTModuleAgent::AliHLTOUTHandlerType handlerType) const;
 281
 282     /**
 283      * Compare the handler descriptor of this list entry with another
 284      * descriptor.
 285      * @return true if both handler and agent match
 286      */
 287     bool operator==(const AliHLTModuleAgent::AliHLTOUTHandlerDesc desc) const;
 288
 289     AliHLTUInt32_t operator[](int i) const;
 290
 291     /**
 292      * Add a block index to this descriptor.
 293      * One descriptor can serve multiple blocks if the agent returns the
 294      * same handler for all of the blocks. Instead of creating a new entry
 295      * the block index ist just added
 296      */
 297     void AddIndex(AliHLTUInt32_t index);
 298
 299     /**
 300      * Add all indices of the descriptor.
 301      */
 302     void AddIndex(const AliHLTOUTHandlerListEntry &desc);
 303
 304     /**
 305      * Check if an index is served by this descriptor.
 306      * @return true if the index is in the table
 307      */
 308     bool HasIndex(AliHLTUInt32_t index) const;
 309
 310     /**
 311      * Invalidate all block indices
 312      */
 313     void InvalidateBlocks() {fBlocks.clear();}
 314
 315     /**
 316      * Check whether the entry has valid blocks.
 317      */
 318     bool IsEmpty() {return fBlocks.size()==0;}
 319
 320     /// print info
 321     void Print(const char* option="") const;
 322
 323   private:
 324     /** standard constructor prohibited */
 325     AliHLTOUTHandlerListEntry();
 326
 327     static const AliHLTOUTHandlerListEntry fgkVoidHandlerListEntry; //! initializer
 328
 329     /** pointer to the handler */
 330     AliHLTOUTHandler* fpHandler; //! transient
 331
 332     /** pointer to handler description */
 333     AliHLTModuleAgent::AliHLTOUTHandlerDesc* fpHandlerDesc; //! transient
 334
 335     /** pointer to module agent */
 336     AliHLTModuleAgent* fpAgent; //! transient
 337
 338     /** list of block indices */
 339     AliHLTOUTIndexList fBlocks; //!transient
 340   };
 341
 342   typedef vector<AliHLTOUTHandlerListEntry> AliHLTOUTHandlerListEntryVector;
 343   typedef vector<AliHLTOUTBlockDescriptor>  AliHLTOUTBlockDescriptorVector;
 344   typedef vector<AliHLTOUT*>                AliHLTOUTPVector;
 345
 346   /**
 347    * Selection guard for the AliHLTOUT object.
 348    * If the object is locked, the selection of data blocks can not be changed.
 349    */
 350   class AliHLTOUTSelectionGuard {
 351   public:
 352     /** constructor */
 353     AliHLTOUTSelectionGuard(AliHLTOUT* pInstance) : fpInstance(pInstance)
 354     {if (fpInstance) fpInstance->SelectDataBlock();}
 355     /** constructor */
 356     AliHLTOUTSelectionGuard(AliHLTOUT* pInstance, const AliHLTOUTHandlerListEntry* pHandlerDesc) : fpInstance(pInstance)
 357     {if (fpInstance) fpInstance->SelectDataBlocks(pHandlerDesc);}
 358     /** destructor */
 359     ~AliHLTOUTSelectionGuard()
 360     {if (fpInstance) fpInstance->DisableBlockSelection();}
 361
 362   private:
 363     /** standard constructor prohibited */
 364     AliHLTOUTSelectionGuard();
 365     /** copy constructor prohibited */
 366     AliHLTOUTSelectionGuard(const AliHLTOUTSelectionGuard&);
 367     /** assignment operator prohibited */
 368     AliHLTOUTSelectionGuard& operator=(const AliHLTOUTSelectionGuard&);
 369
 370     /** the AliHLTOUT instance the guard is locking */
 371     AliHLTOUT* fpInstance; //!transient
 372   };
 373
 374   /**
 375    * Init for processing.
 376    * The HLTOUT is scanned for all available data blocks and the
 377    * AliHLTOUTHandler objects for the data blocks are created according
 378    * to the module agents (see AliHLTModuleAgent).
 379    */
 380   int Init();
 381
 382   /**
 383    * Reset and clear all data block descriptors.
 384    * @note Since sub-collections are only referred via the block
 385    * descriptors, all information on sub-collections is also lost.
 386    * Child classes should implement ResetInput in order to cleanup
 387    * the input devices.
 388    */
 389   int Reset();
 390
 391   /**
 392    * Get the current event id
 393    */
 394   AliHLTUInt64_t EventId() const {return fCurrentEventId;}
 395
 396   /**
 397    * Get number of data blocks in the HLTOUT data
 398    */
 399   int GetNofDataBlocks();
 400
 401   /**
 402    * Select the first data block of a certain data type and specification.
 403    * The selection criteria can be of kAliHLTAnyDataType and/or
 404    * kAliHLTVoidDataSpec in order to be ignored and just match any data block.
 405    *
 406    * The search criteria can be combined with a handler type (e.g. kRawReader)
 407    * @param [in] dt     data type to match                                <br>
 408    * @param [in] spec   data specification to match                       <br>
 409    * @param [in] handlerType  type of the handler
 410    * @param [in] skipProcessed skip all block marked processed
 411    * @return block index: >= 0 if success, -ENOENT if no block found      <br>
 412    *         neg. error code if failed                                    <br>
 413    *                        -EPERM if access denied (object locked)
 414    */
 415   int SelectFirstDataBlock(AliHLTComponentDataType dt=kAliHLTAnyDataType,
 416                            AliHLTUInt32_t spec=kAliHLTVoidDataSpec,
 417                            AliHLTModuleAgent::AliHLTOUTHandlerType handlerType=AliHLTModuleAgent::kUnknownOutput,
 418                            bool skipProcessed=true);
 419
 420   /**
 421    * Select the next data block of data type and specification of the previous
 422    * call to @ref SelectFirstDataBlock.
 423    * @return block index: >= 0 if success, -ENOENT if no block found      <br>
 424    *         neg. error code if failed                                    <br>
 425    *                        -EPERM if access denied (object locked)
 426    */
 427   int SelectNextDataBlock();
 428
 429   /**
 430    * Get properties of the selected data block.
 431    * @param [out] dt    data type of the selected block
 432    * @param [out] spec  data specification of the selected block
 433    */
 434   int GetDataBlockDescription(AliHLTComponentDataType& dt, AliHLTUInt32_t& spec);
 435
 436   /**
 437    * Get handler description of the current data block.
 438    */
 439   const AliHLTOUTHandlerListEntry& GetDataBlockHandlerDesc();
 440
 441   /**
 442    * Get handler type of the selected data block.
 443    * @return handler type for the selected data block
 444    */
 445   AliHLTModuleAgent::AliHLTOUTHandlerType GetDataBlockHandlerType();
 446
 447   /**
 448    * Get the index of the current data block.
 449    * @return index, AliHLTOUTInvalidIndex if no block selected
 450    */
 451   AliHLTUInt32_t GetDataBlockIndex();
 452
 453   /**
 454    * Get buffer of the selected data block.
 455    * Buffer has to be released using ReleaseDataBuffer
 456    * @param [out] desc  block data descriptor
 457    */
 458   int GetDataBuffer(AliHLTComponentBlockData& desc);
 459
 460   /**
 461    * Get buffer of the selected data block.
 462    * Buffer has to be released using ReleaseDataBuffer
 463    * @param [out] pBuffer buffer of the selected data block
 464    * @param [out] size    size of the selected data block
 465    */
 466   int GetDataBuffer(const AliHLTUInt8_t* &pBuffer, AliHLTUInt32_t& size);
 467
 468   /**
 469    * Release buffer after use.
 470    * @param [in] pBuffer  buffer of the selected data block
 471    */
 472   int ReleaseDataBuffer(const AliHLTUInt8_t* pBuffer);
 473
 474   /**
 475    * Get a TObject from the data buffer
 476    * @return TObject pointer if data block is a streamed object
 477    */
 478   TObject* GetDataObject();
 479
 480   /**
 481    * Release data object
 482    */
 483   int ReleaseDataObject(TObject* pObject);
 484
 485   /**
 486    * Add the current data block to the selection.
 487    * Note: enables also the block selection
 488    */
 489   int SelectDataBlock();
 490
 491   /**
 492    * Add the all data blocks of a certain handler to the selection.
 493    * Note: enables also the block selection
 494    */
 495   int SelectDataBlocks(const AliHLTOUTHandlerListEntry* pHandlerDesc);
 496
 497   /**
 498    * Enable the selection of data blocks.
 499    */
 500   int EnableBlockSelection();
 501
 502   /**
 503    * Disable the selection of data blocks.
 504    */
 505   int DisableBlockSelection();
 506
 507   /**
 508    * Reset the data block selection.
 509    * Resets the selection list, none of the blocks is selected.
 510    */
 511   int ResetBlockSelection();
 512
 513   /**
 514    * Mark the current block as processed.
 515    */
 516   int MarkDataBlockProcessed();
 517
 518   /**
 519    * Mark all data blocks of a certain handler processed.
 520    */
 521   int MarkDataBlocksProcessed(const AliHLTOUTHandlerListEntry* pHandlerDesc);
 522
 523   /**
 524    * Add a sub collection to the HLTOUT.
 525    */
 526   int AddSubCollection(AliHLTOUT* pCollection);
 527
 528   /**
 529    * Release a previously added sub collection.
 530    */
 531   int ReleaseSubCollection(AliHLTOUT* pCollection);
 532
 533   /**
 534    * Get module agent for the selected data block.
 535    */
 536   AliHLTModuleAgent* GetAgent();
 537
 538   /**
 539    * Get handler for the selected data block.
 540    */
 541   AliHLTOUTHandler* GetHandler();
 542
 543   /**
 544    * Convert data buffer to ESD.
 545    * The buffer is supposed to describe a streamed AliESDEvent object.
 546    * If no target object is specified, the ESD is written to a file AliHLTdetESDs.root,
 547    * where 'det' is derived from the data type origin. Each time the function is invoked
 548    * a new event is created. Dummy events are added if the previous events did not contain
 549    *
 550    * The function needs AliRoot and might not be implemented by all AliHLTOUT
 551    * implementations.
 552    * a data block of this specification.
 553    * @param [in]  pBuffer  the data buffer
 554    * @param [in]  size     data buffer size
 555    * @param [in]  dt       data type of the block
 556    * @param [out] tgtesd   optional target
 557    */
 558   virtual int WriteESD(const AliHLTUInt8_t* pBuffer, AliHLTUInt32_t size, AliHLTComponentDataType dt, AliESDEvent* tgtesd=NULL) const;
 559
 560   enum AliHLTOUTByteOrder {
 561     /** no data block selected */
 562     kInvalidByteOrder=-1,
 563     kUnknownByteOrder=0,
 564     kLittleEndian,
 565     kBigEndian
 566   };
 567
 568   enum AliHLTOUTDataType {
 569     kUint64 = 0,
 570     kUint32 = 1,
 571     kUint16 = 2,
 572     kUint8  = 3,
 573     kDouble = 4,
 574     kFloat  = 5
 575   };
 576
 577   /**
 578    * Check byte order of selected block
 579    */
 580   AliHLTOUTByteOrder CheckByteOrder();
 581
 582   /**
 583    * Check alignment of selected block
 584    */
 585   int CheckAlignment(AliHLTOUT::AliHLTOUTDataType type);
 586
 587   /**
 588    * Helper function to byte swap a 64 bit value.
 589    */
 590   static AliHLTUInt64_t ByteSwap64(AliHLTUInt64_t src);
 591
 592   /**
 593    * Helper function to byte swap a 32 bit value.
 594    */
 595   static AliHLTUInt32_t ByteSwap32(AliHLTUInt32_t src);
 596
 597   /**
 598    * Insert a handler item.
 599    * The current list entries are checked if the handler is already in
 600    * the list. It is added if not in the list, otherwise the block index
 601    * is added to the existing entry.
 602    * @param list     the handler list
 603    * @param entry    handler list entry
 604    * @return 0 if added, EEXIST (non negative!) if merged with existing entry <br>
 605    *         neg. error code if failed
 606    */
 607   static int InsertHandler(AliHLTOUTHandlerListEntryVector& list, const AliHLTOUTHandlerListEntry &entry);
 608
 609   /**
 610    * Insert all handlers of the specified type to the list.
 611    */
 612   int FillHandlerList(AliHLTOUTHandlerListEntryVector& list, AliHLTModuleAgent::AliHLTOUTHandlerType handlerType);
 613
 614   /**
 615    * Remove empty items which have a duplicate in the list.
 616    */
 617   static int RemoveEmptyDuplicateHandlers(AliHLTOUTHandlerListEntryVector& list);
 618
 619   /**
 620    * Find an entry of a certain description in the list.
 621    * @return index of the entry if found, -ENOENT if not found
 622    */
 623   static int FindHandler(AliHLTOUTHandlerListEntryVector& list, const AliHLTModuleAgent::AliHLTOUTHandlerDesc desc);
 624
 625   /**
 626    * Invalidate all blocks of the handlers in the list
 627    */
 628   static int InvalidateBlocks(AliHLTOUTHandlerListEntryVector& list);
 629
 630  protected:
 631   /**
 632    * Add a block descriptor.
 633    * This is done by the child classes generating the index. The AliHLTOUT
 634    * object must be locked for index generation.
 635    * @param desc    the block descriptor
 636    * @return 0 if success, -EPERM if access denied
 637    */
 638   int AddBlockDescriptor(const AliHLTOUTBlockDescriptor desc);
 639
 640   /**
 641    * Set the event id, only for child classes
 642    */
 643   void SetEventId(AliHLTUInt64_t id);
 644
 645   /**
 646    * Print output or suppress.
 647    */
 648   bool BeVerbose() const {return fbVerbose;}
 649
 650   /**
 651    * Switch output.
 652    */
 653   void SwitchVerbosity(bool verbose) {fbVerbose=verbose;}
 654
 655   /// print info
 656   void Print(const char* option="") const;
 657
 658  private:
 659   /** copy constructor prohibited */
 660   AliHLTOUT(const AliHLTOUT&);
 661   /** assignment operator prohibited */
 662   AliHLTOUT& operator=(const AliHLTOUT&);
 663
 664   /**
 665    * Internal status flags
 666    */
 667   enum {
 668     /** the HLTOUT object is locked with the current data block selection */
 669     kLocked = 0x1,
 670     /** childs can add block descriptors */
 671     kCollecting = 0x2,
 672     /** user of the data block has checked the byte order */
 673     kByteOrderChecked = 0x4,
 674     /** warning on byte order missmatch has been printed */
 675     kByteOrderWarning = 0x8,
 676     /** user of the data block has checked the alignment */
 677     kAlignmentChecked = 0x10,
 678     /** warning on alignment missmatch has been printed */
 679     kAlignmentWarning = 0x20,
 680     /** enable block selection list */
 681     kBlockSelection = 0x40,
 682     /** skip processed data blocks */
 683     kSkipProcessed = 0x80,
 684     /** marked as sub collection */
 685     kIsSubCollection = 0x100
 686   };
 687
 688   /**
 689    * Generate the index of the HLTOUT data.
 690    * Must be implemented by the child classes.
 691    */
 692   virtual int GenerateIndex()=0;
 693
 694   /**
 695    * Find AliHLTOUTHandler objects for the data blocks.
 696    * The available AliHLTModuleAgents are probed whether they provide
 697    * handlers for data processing.
 698    */
 699   int InitHandlers();
 700
 701   /**
 702    * Cleanup and reset the data input.
 703    */
 704   virtual int ResetInput();
 705
 706   /**
 707    * Get the data buffer
 708    * @param [in]  index   index of the block
 709    * @param [out] pBuffer buffer of the selected data block
 710    * @param [out] size    size of the selected data block
 711    */
 712   virtual int GetDataBuffer(AliHLTUInt32_t index, const AliHLTUInt8_t* &pBuffer,
 713                             AliHLTUInt32_t& size)=0;
 714
 715   /**
 716    * Check byte order of data block
 717    */
 718   virtual AliHLTOUTByteOrder CheckBlockByteOrder(AliHLTUInt32_t index)=0;
 719
 720   /**
 721    * Check alignment of data block
 722    */
 723   virtual int CheckBlockAlignment(AliHLTUInt32_t index, AliHLTOUT::AliHLTOUTDataType type)=0;
 724
 725   /**
 726    * Select the data block of data type and specification of the previous
 727    * call to @ref SelectFirstDataBlock. Core function of @ref SelectFirstDataBlock
 728    * and @ref SelectNextDataBlock, starts to find a block at the current list
 729    * position.
 730    *
 731    * The data block is searched from the conditions of fSearchDataType,
 732    * fSearchSpecification, fSearchHandlerType and the selection list.
 733    *
 734    * @return identifier >=0 if success, neg. error code if failed         <br>
 735    *                        -ENOENT if no block found                     <br>
 736    *                        -EPERM if access denied (object locked)
 737    */
 738   int FindAndSelectDataBlock();
 739
 740   /**
 741    * Set status flag.
 742    * @param flag     flag to set
 743    * @return current status flags
 744    */
 745   unsigned int SetStatusFlag(unsigned int flag) {return fFlags|=flag;}
 746
 747   /**
 748    * Clear status flag.
 749    * @param flag     flag to clear
 750    * @return current status flags
 751    */
 752   unsigned int ClearStatusFlag(unsigned int flag) {return fFlags&=~flag;}
 753
 754   /**
 755    * Check status flag.
 756    * @param flag     flag to check
 757    * @return 1 if flag is set
 758    */
 759   int CheckStatusFlag(unsigned int flag) const {return (fFlags&flag)==flag;}
 760
 761   /**
 762    * Find handler description for a certain block index.
 763    */
 764   const AliHLTOUTHandlerListEntry& FindHandlerDesc(AliHLTUInt32_t blockIndex);
 765
 766   /**
 767    * Set the RawReader as parameter.
 768    * The function is for internal use only in conjunction with the
 769    * New() functions.
 770    */
 771   virtual void SetParam(AliRawReader* pRawReader);
 772
 773   /**
 774    * Set the RunLoader as parameter
 775    * The function is for internal use only in conjunction with the
 776    * New() functions.
 777    */
 778   virtual void SetParam(TTree* pDigitTree, int event=-1);
 779
 780   /**
 781    * Set name of the digit file as parameter
 782    * The function is for internal use only in conjunction with the
 783    * New() functions.
 784    */
 785   virtual void SetParam(const char* filename, int event=-1);
 786
 787   /** data type for the current block search, set from @ref SelectFirstDataBlock */
 788   AliHLTComponentDataType fSearchDataType; //!transient
 789
 790   /** data specification for the current block search */
 791   AliHLTUInt32_t fSearchSpecification; //!transient
 792
 793   /** handler type for the current block search */
 794   AliHLTModuleAgent::AliHLTOUTHandlerType fSearchHandlerType; // !transient
 795
 796   /** instance flags: locked, collecting, ... */
 797   unsigned int fFlags; //!transient
 798
 799   /** list of block descriptors */
 800   AliHLTOUTBlockDescriptorVector fBlockDescList; //!transient
 801
 802   /** current position in the list */
 803   unsigned int fCurrent; //!transient
 804
 805   /** data buffer under processing */
 806   AliConstExternalBuffer fpBuffer; //!transient
 807
 808   /** list of AliHLTOUTHandlers */
 809   AliHLTOUTHandlerListEntryVector fDataHandlers; // !transient
 810
 811   /** verbose or silent output */
 812   bool fbVerbose; //!transient
 813
 814   /** gobal instance set for certain steps of the analysis */
 815   static AliHLTOUT* fgGlobalInstance; //! transient
 816
 817   /** logging methods */
 818   AliHLTLogging fLog; //! transient
 819
 820   /** current buffer converted to a TObject */
 821   TObject* fpDataObject; //!
 822   AliConstExternalBuffer fpObjectBuffer; //!
 823   AliHLTUInt32_t fObjectBufferSize; //!
 824
 825   /** current event id */
 826   AliHLTUInt64_t fCurrentEventId; //!
 827
 828   ClassDef(AliHLTOUT, 6)
 829 };
 830 #endif