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