scanning of handlers for HLTOUT blocks added
[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;
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