Update for complying with train (first round)
[u/mrichter/AliRoot.git] / 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; // AliHLTModuleAgent.h
22 class AliESDEvent;
23 class AliHLTReconstructor;
24
25 #define AliHLTOUTInvalidIndex (~(AliHLTUInt32_t)0)
26
27 typedef vector<AliHLTUInt32_t> AliHLTOUTIndexList;
28
29 /**
30  * @class AliHLTOUT
31  * The control class for HLTOUT data.
32  * The output of the HLT, either from the HLTOUT nodes or simulated output,
33  * is transferred and stored in the HOMER format. The AliHLTOUT class 
34  * implements scanning of the HOMER data for all HLTOUT DDL links and
35  * abstracts access to the complete HLTOUT data.
36  * 
37  */
38 class AliHLTOUT : public AliHLTLogging {
39  public:
40   /** standard constructor */
41   AliHLTOUT();
42   /** standard destructor */
43   virtual ~AliHLTOUT();
44
45   /**
46    * Locking guard for the AliHLTOUT object.
47    * If the object is locked, the selection of data blocks can not be changed.
48    */
49   class AliHLTOUTLockGuard {
50   public:
51     /** constructor */
52     AliHLTOUTLockGuard(AliHLTOUT* pInstance) : fpInstance(pInstance)
53     {if (fpInstance) fpInstance->SetStatusFlag(kLocked);}
54     /** destructor */
55     ~AliHLTOUTLockGuard()
56     {if (fpInstance) fpInstance->ClearStatusFlag(kLocked);}
57
58   private:
59     /** standard constructor prohibited */
60     AliHLTOUTLockGuard();
61     /** copy constructor prohibited */
62     AliHLTOUTLockGuard(const AliHLTOUTLockGuard&);
63     /** assignment operator prohibited */
64     AliHLTOUTLockGuard& operator=(const AliHLTOUTLockGuard&);
65
66     /** the AliHLTOUT instance the guard is locking */
67     AliHLTOUT* fpInstance; //!transient
68   };
69
70   /**
71    * The HLT OUT Event Header.
72    * Defined between HLT and DAQ.
73    */
74   struct AliHLTOUTEventHeader {
75     /**Total length of the data in bytes, including HLT event header, excluding CDH. */
76     AliHLTUInt32_t fLength; //! see above
77     /** version of the header */
78     AliHLTUInt32_t fVersion; //! see above
79     /** High 32 bit word of event id */
80     AliHLTUInt32_t fEventIDHigh; //! see above
81     /** Low 32 bit word of event id */
82     AliHLTUInt32_t fEventIDLow; //! see above
83   };
84
85   enum {
86     /// versions 1 of the HLT header
87     kVersion1 = 1,
88     /// versions 2 of the HLT header
89     kVersion2 = 2
90   };
91
92   enum {
93     /// size of HLT decision in data format version 1: 29x4
94     kSizeDecisionVersion1 = 116,
95     /// size of HLT decision in data format version 2: 30x4
96     kSizeDecisionVersion2 = 120
97   };
98
99   // definitions from ALICE internal notes ALICE-INT-2002-010 and
100   // ALICE-INT-2006-XXX
101   enum {
102     /** the 32bit word in the CDH containing the status flags */
103     kCDHStatusWord=4, //! see above
104     /** start of the flags in word fgkCDHStatusWord */
105     kCDHStatusFlagsOffset=12, //! see above
106     /** bit indicating HLT decision in the HLTOUT*/
107     kCDHFlagsHLTDecision=6, //! see above
108     /** bit indicating HLT payload in the HLTOUT*/
109     kCDHFlagsHLTPayload=7 //! see above
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   class AliHLTOUTHandlerListEntry {
137   public:
138     AliHLTOUTHandlerListEntry(AliHLTOUTHandler* pHandler, 
139                               AliHLTModuleAgent::AliHLTOUTHandlerDesc& handlerDesc,
140                               AliHLTModuleAgent* pAgent,
141                               AliHLTUInt32_t index);
142
143     /** copy constructor for vector handling */
144     AliHLTOUTHandlerListEntry(const AliHLTOUTHandlerListEntry& src);
145
146     /** assignment operator for vector handling */
147     AliHLTOUTHandlerListEntry& operator=(const AliHLTOUTHandlerListEntry& src);
148
149     ~AliHLTOUTHandlerListEntry();
150
151     static const AliHLTOUTHandlerListEntry fgkVoidHandlerListEntry; //! initializer
152
153     operator AliHLTOUTHandler*() const {return fpHandler;}
154
155     // please note that fpHandlerDesc is really a pointer and is created
156     // in the constructor. Thats why it is dereferenced here. The pointer
157     // type is on purpose, even though it is a bit confusing with the 
158     // argument by reference in the AliHLTOUTHandlerListEntry constructor.
159     operator const AliHLTModuleAgent::AliHLTOUTHandlerDesc&() const 
160     {return fpHandlerDesc?*fpHandlerDesc:AliHLTModuleAgent::fgkVoidHandlerDesc;}
161     operator AliHLTModuleAgent*() const {return fpAgent;}
162
163     /**
164      * Two list entries are considered to be equal if the handlers
165      * are equal.
166      */
167     bool operator==(const AliHLTOUTHandlerListEntry& entry) const;
168
169     bool operator==(const AliHLTModuleAgent::AliHLTOUTHandlerType handlerType) const;
170
171     AliHLTUInt32_t operator[](int i) const;
172
173     /**
174      * Add a block index to this descriptor.
175      * One descriptor can serve multiple blocks if the agent returns the
176      * same handler for all of the blocks. Instead of creating a new entry
177      * the block index ist just added
178      */
179     void AddIndex(AliHLTUInt32_t index);
180
181     /**
182      * Add all indexes of the descriptor.
183      */
184     void AddIndex(AliHLTOUTHandlerListEntry &desc);
185
186     /**
187      * Check if an index is served by this descriptor.
188      * @return true if the index is in the table
189      */
190     bool HasIndex(AliHLTUInt32_t index);
191
192   private:
193     /** standard constructor prohibited */
194     AliHLTOUTHandlerListEntry();
195
196     /** pointer to the handler */
197     AliHLTOUTHandler* fpHandler; //! transient
198
199     /** pointer to handler description */
200     AliHLTModuleAgent::AliHLTOUTHandlerDesc* fpHandlerDesc; //! transient
201
202     /** pointer to module agent */
203     AliHLTModuleAgent* fpAgent; //! transient
204
205     /** list of block indexes */
206     AliHLTOUTIndexList fBlocks; //!transient
207   };
208
209   typedef vector<AliHLTOUTHandlerListEntry> AliHLTOUTHandlerListEntryVector;
210   typedef vector<AliHLTOUTBlockDescriptor>  AliHLTOUTBlockDescriptorVector;
211
212   /**
213    * Init for processing.
214    * The HLTOUT is scanned for all available data blocks and the
215    * AliHLTOUTHandler objects for the data blocks are created according
216    * to the module agents (see AliHLTModuleAgent).
217    */
218   int Init();
219
220   /**
221    * Get number of data blocks in the HLTOUT data
222    */
223   int GetNofDataBlocks();
224
225   /**
226    * Select the first data block of a certain data type and specification.
227    * The selection criteria can be of kAliHLTAnyDataType and/or
228    * kAliHLTVoidDataSpec in order to be ignored and just match any data block.
229    *
230    * The search criteria can be combined with a handler type (e.g. kRawReader)
231    * @param dt    [in]  data type to match                                <br>
232    * @param spec  [in]  data specification to match                       <br>
233    * @param handlerType [in]  type of the handler
234    * @return identifier >0 if success, 0 if no block found                <br>
235    *         neg. error code if failed                                    <br>
236    *                        -EPERM if access denied (object locked)
237    */
238   int SelectFirstDataBlock(AliHLTComponentDataType dt=kAliHLTAnyDataType,
239                            AliHLTUInt32_t spec=kAliHLTVoidDataSpec,
240                            AliHLTModuleAgent::AliHLTOUTHandlerType handlerType=AliHLTModuleAgent::kUnknownOutput);
241
242   /**
243    * Select the next data block of data type and specification of the previous
244    * call to @ref SelectFirstDataBlock.
245    * @return identifier >0 if success, 0 if no block found                <br>
246    *         neg. error code if failed                                    <br>
247    *                        -EPERM if access denied (object locked)
248    */
249   int SelectNextDataBlock();
250
251   /**
252    * Get properties of the selected data block.
253    * @param dt    [out] data type of the selected block
254    * @param spec  [out] data specification of the selected block
255    */
256   int GetDataBlockDescription(AliHLTComponentDataType& dt, AliHLTUInt32_t& spec);
257
258   /**
259    * Get handler description of the current data block.
260    */
261   const AliHLTOUTHandlerListEntry& GetDataBlockHandlerDesc();
262
263   /**
264    * Get handler type of the selected data block.
265    * @return handler type for the selected data block
266    */
267   AliHLTModuleAgent::AliHLTOUTHandlerType GetDataBlockHandlerType();
268
269   /**
270    * Get the index of the current data block.
271    * @return index, AliHLTOUTInvalidIndex if no block selected
272    */
273   AliHLTUInt32_t GetDataBlockIndex();
274
275   /**
276    * Get buffer of the selected data block.
277    * @param pBuffer [out] buffer of the selected data block
278    * @param size    [out] size of the selected data block
279    */
280   int GetDataBuffer(const AliHLTUInt8_t* &pBuffer, AliHLTUInt32_t& size);
281
282   /**
283    * Release buffer after use.
284    * @param pBuffer [in]  buffer of the selected data block
285    */
286   int ReleaseDataBuffer(const AliHLTUInt8_t* pBuffer);
287
288   /**
289    * Get module agent for the selected data block.
290    */
291   AliHLTModuleAgent* GetAgent();
292
293   /**
294    * Get handler for the selected data block.
295    */
296   AliHLTOUTHandler* GetHandler();
297
298   /**
299    * Convert data buffer to ESD.
300    * The buffer is supposed to describe a streamed AliESDEvent object.
301    * If no target object is specified, the ESD is written to a file AliHLTdetESDs.root,
302    * where 'det' is derived from the data type origin. Each time the function is invoked
303    * a new event is created. Dummy events are added if the previous events did not contain
304    *
305    * The function needs AliRoot and might not be implemented by all AliHLTOUT
306    * implementations.
307    * a data block of this specification.
308    * @param pBuffer  [in] the data buffer
309    * @param size     [in] data buffer size
310    * @param dt       [in] data type of the block
311    * @param tgtesd   [out] optional target
312    */
313   virtual int WriteESD(const AliHLTUInt8_t* pBuffer, AliHLTUInt32_t size, AliHLTComponentDataType dt, AliESDEvent* tgtesd=NULL) const;
314
315   enum AliHLTOUTByteOrder {
316     /** no data block selected */
317     kInvalidByteOrder=-1,
318     kUnknownByteOrder=0,
319     kLittleEndian,
320     kBigEndian
321   };
322
323   enum AliHLTOUTDataType {
324     kUint64 = 0,
325     kUint32 = 1,
326     kUint16 = 2,
327     kUint8  = 3,
328     kDouble = 4,
329     kFloat  = 5
330   };
331
332   /**
333    * Check byte order of selected block
334    */
335   AliHLTOUTByteOrder CheckByteOrder();
336
337   /**
338    * Check alignment of selected block
339    */
340   int CheckAlignment(AliHLTOUT::AliHLTOUTDataType type);
341
342   /**
343    * Helper function to byte swap a 64 bit value.
344    */
345   static AliHLTUInt64_t ByteSwap64(AliHLTUInt64_t src);
346
347   /**
348    * Helper function to byte swap a 32 bit value.
349    */
350   static AliHLTUInt32_t ByteSwap32(AliHLTUInt32_t src);
351
352   /**
353    * Insert a handler item.
354    * The current list entries are checked if the handler is already in
355    * the list. It is added if not in the list, otherwise the block index
356    * is added to the existing entry.
357    * @param list     the handler list
358    * @param entry    handler list entry
359    * @return 0 if added, EEXIST (non negative!) if merged with existing entry <br>
360    *         neg. error code if failed
361    */
362   static int InsertHandler(AliHLTOUTHandlerListEntryVector& list, const AliHLTOUTHandlerListEntry &entry);
363   
364  protected:
365   /**
366    * Add a block descriptor.
367    * This is done by the child classes generating the index. The AliHLTOUT
368    * object must be locked for index generation.
369    * @param desc    the block descriptor
370    * @return 0 if success, -EPERM if access denied
371    */
372   int AddBlockDescriptor(const AliHLTOUTBlockDescriptor desc);
373
374   /**
375    * Print output or suppress.
376    */
377   bool BeVerbose() {return fbVerbose;}
378
379   /**
380    * Switch output.
381    */
382   void SwitchVerbosity(bool verbose) {fbVerbose=verbose;}
383
384  private:
385   /** copy constructor prohibited */
386   AliHLTOUT(const AliHLTOUT&);
387   /** assignment operator prohibited */
388   AliHLTOUT& operator=(const AliHLTOUT&);
389
390   /**
391    * Internal status flags
392    */
393   enum {
394     /** the HLTOUT object is locked with the current data block */
395     kLocked = 0x1,
396     /** childs can add block descriptors */
397     kCollecting = 0x2,
398     /** user of the data block has checked the byte order */
399     kByteOrderChecked = 0x4,
400     /** warning on byte order missmatch has been printed */
401     kByteOrderWarning = 0x8,
402     /** user of the data block has checked the alignment */
403     kAlignmentChecked = 0x10,
404     /** warning on alignment missmatch has been printed */
405     kAlignmentWarning = 0x20
406   };
407
408   /**
409    * Generate the index of the HLTOUT data.
410    * Must be implemented by the child classes.
411    */
412   virtual int GenerateIndex()=0;
413
414   /**
415    * Find AliHLTOUTHandler objects for the data blocks.
416    * The available AliHLTModuleAgents are probed whether they provide
417    * handlers for data processing.
418    */
419   int InitHandlers();
420
421   /**
422    * Get the data buffer
423    * @param index   [in]  index of the block
424    * @param pBuffer [out] buffer of the selected data block
425    * @param size    [out] size of the selected data block
426    */
427   virtual int GetDataBuffer(AliHLTUInt32_t index, const AliHLTUInt8_t* &pBuffer, 
428                             AliHLTUInt32_t& size)=0;
429
430   /**
431    * Check byte order of data block
432    */
433   virtual AliHLTOUTByteOrder CheckBlockByteOrder(AliHLTUInt32_t index)=0;
434
435   /**
436    * Check alignment of data block
437    */
438   virtual int CheckBlockAlignment(AliHLTUInt32_t index, AliHLTOUT::AliHLTOUTDataType type)=0;
439
440   /**
441    * Select the data block of data type and specification of the previous
442    * call to @ref SelectFirstDataBlock. Core function of @ref SelectFirstDataBlock
443    * and @ref SelectNextDataBlock, starts to find a block at the current list
444    * position. 
445    * @return identifier >=0 if success, neg. error code if failed         <br>
446    *                        -ENOENT if no block found                     <br>
447    *                        -EPERM if access denied (object locked)
448    */
449   int FindAndSelectDataBlock();
450
451   /**
452    * Set status flag.
453    * @param flag     flag to set
454    * @return current status flags
455    */
456   unsigned int SetStatusFlag(unsigned int flag) {return fFlags|=flag;}
457
458   /**
459    * Clear status flag.
460    * @param flag     flag to clear
461    * @return current status flags
462    */
463   unsigned int ClearStatusFlag(unsigned int flag) {return fFlags&=~flag;}
464
465   /**
466    * Check status flag.
467    * @param flag     flag to check
468    * @return 1 if flag is set
469    */
470   int CheckStatusFlag(unsigned int flag) const {return (fFlags&flag)==flag;}
471
472   /**
473    * Find handler description for a certain block index.
474    */
475   const AliHLTOUTHandlerListEntry& FindHandlerDesc(AliHLTUInt32_t blockIndex);
476
477   /** data type for the current block search, set from @ref SelectFirstDataBlock */
478   AliHLTComponentDataType fSearchDataType; //!transient
479
480   /** data specification for the current block search */
481   AliHLTUInt32_t fSearchSpecification; //!transient
482
483   /** handler type for the current block search */
484   AliHLTModuleAgent::AliHLTOUTHandlerType fSearchHandlerType; // !transient
485
486   /** instance flags: locked, collecting, ... */
487   unsigned int fFlags; //!transient
488
489   /** list of block descriptors */
490   AliHLTOUTBlockDescriptorVector fBlockDescList; //!transient
491
492   /** current position in the list */
493   AliHLTOUTBlockDescriptorVector::iterator fCurrent; //!transient
494
495   /** data buffer under processing */
496   const AliHLTUInt8_t* fpBuffer; //!transient
497
498   /** list of AliHLTOUTHandlers */
499   AliHLTOUTHandlerListEntryVector fDataHandlers; // !transient
500
501   /** verbose or silent output */
502   bool fbVerbose; //!transient
503
504   ClassDef(AliHLTOUT, 2)
505 };
506 #endif