further work on 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 // see below for class documentation
16 // or
17 // refer to README to build package
18 // or
19 // visit http://web.ift.uib.no/~kjeks/doc/alice-hlt
20
21                                                                           */
22 #include <vector>
23 #include "AliHLTLogging.h"
24
25 /**
26  * @class AliHLTOUT
27  * The control class for HLTOUT data.
28  * The output of the HLT, either from the HLTOUT nodes or simulated output,
29  * is transferred and stored in the HOMER format. The AliHLTOUT class 
30  * implements scanning of the HOMER data for all HLTOUT DDL links and
31  * abstracts access to the complete HLTOUT data.
32  * 
33  */
34 class AliHLTOUT : public AliHLTLogging {
35  public:
36   /** standard constructor */
37   AliHLTOUT();
38   /** standard destructor */
39   virtual ~AliHLTOUT();
40
41   /**
42    * Get number of data blocks in the HLTOUT data
43    */
44   int GetNofDataBlocks();
45
46   /**
47    * Select the first data block of a certain data type and specification.
48    * The selection criteria can be of kAliHLTAnyDataType and/or
49    * kAliHLTVoidDataSpec in order to be ignored and just match any data block.
50    * @param dt    [in]  data type to match                                <br>
51    * @param spec  [in]  data specification to match                       <br>
52    * @return identifier >=0 if success, neg. error code if failed         <br>
53    *                        -ENOENT if no block found                     <br>
54    *                        -EPERM if access denied (object locked)
55    */
56   int SelectFirstDataBlock(AliHLTComponentDataType dt, AliHLTUInt32_t spec);
57
58   /**
59    * Select the next data block of data type and specification of the previous
60    * call to @ref SelectFirstDataBlock.
61    * @return identifier >=0 if success, neg. error code if failed         <br>
62    *                        -ENOENT if no block found                     <br>
63    *                        -EPERM if access denied (object locked)
64    */
65   int SelectNextDataBlock();
66
67   /**
68    * Get properties of the selected data block.
69    * @param dt    [out] data type of the selected block
70    * @param spec  [out] data specification of the selected block
71    */
72   int GetDataBlockDescription(AliHLTComponentDataType& dt, AliHLTUInt32_t& spec);
73
74   /**
75    * Get buffer of the selected data block.
76    * @param pBuffer [out] buffer of the selected data block
77    * @param size    [out] size of the selected data block
78    */
79   int GetDataBuffer(const AliHLTUInt8_t* &pBuffer, AliHLTUInt32_t& size);
80
81   /**
82    * Release buffer after use.
83    * @param pBuffer [in]  buffer of the selected data block
84    */
85   int ReleaseDataBuffer(const AliHLTUInt8_t* pBuffer);
86
87   /**
88    * Locking guard for the AliHLTOUT object.
89    * If the object is locked, the selection of data blocks can not be changed.
90    */
91   class AliHLTOUTLockGuard {
92   public:
93     /** constructor */
94     AliHLTOUTLockGuard(AliHLTOUT* pInstance) : fpInstance(pInstance)
95     {if (fpInstance) fpInstance->SetStatusFlag(kLocked);}
96     /** destructor */
97     ~AliHLTOUTLockGuard()
98     {if (fpInstance) fpInstance->ClearStatusFlag(kLocked);}
99
100   private:
101     /** standard constructor prohibited */
102     AliHLTOUTLockGuard();
103     /** copy constructor prohibited */
104     AliHLTOUTLockGuard(const AliHLTOUTLockGuard&);
105     /** assignment operator prohibited */
106     AliHLTOUTLockGuard& operator=(const AliHLTOUTLockGuard&);
107
108     /** the AliHLTOUT instance the guard is locking */
109     AliHLTOUT* fpInstance; //!transient
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   enum AliHLTOUTByteOrder_t {
137     /** no data block selected */
138     kInvalidByteOrder=-1,
139     kUnknownByteOrder=0,
140     kLittleEndian,
141     kBigEndian
142   };
143
144   enum AliHLTOUTDataType_t {
145     kUint64 = 0,
146     kUint32 = 1,
147     kUint16 = 2,
148     kUint8  = 3,
149     kDouble = 4,
150     kFloat  = 5
151   };
152
153   /**
154    * Check byte order of selected block
155    */
156   AliHLTOUTByteOrder_t CheckByteOrder();
157
158   /**
159    * Check alignment of selected block
160    */
161   int CheckAlignment(AliHLTOUT::AliHLTOUTDataType_t type);
162
163  protected:
164   /**
165    * Add a block descriptor.
166    * This is done by the child classes generating the index. The AliHLTOUT
167    * object must be locked for index generation.
168    * @param desc    the block descriptor
169    * @return 0 if success, -EPERM if access denied
170    */
171   int AddBlockDescriptor(const AliHLTOUTBlockDescriptor desc);
172
173  private:
174   /** copy constructor prohibited */
175   AliHLTOUT(const AliHLTOUT&);
176   /** assignment operator prohibited */
177   AliHLTOUT& operator=(const AliHLTOUT&);
178
179   /**
180    * Internal status flags
181    */
182   enum {
183     /** the HLTOUT object is locked with the current data block */
184     kLocked = 0x1,
185     /** childs can add block descriptors */
186     kCollecting = 0x2,
187     /** user of the data block has checked the byte order */
188     kByteOrderChecked = 0x4,
189     /** warning on byte order missmatch has been printed */
190     kByteOrderWarning = 0x8,
191     /** user of the data block has checked the alignment */
192     kAlignmentChecked = 0x10,
193     /** warning on alignment missmatch has been printed */
194     kAlignmentWarning = 0x20
195   };
196
197   /**
198    * Generate the index of the HLTOUT data.
199    * Must be implemented by the child classes.
200    */
201   virtual int GenerateIndex()=0;
202
203   /**
204    * Get the data buffer
205    * @param index   [in]  index of the block
206    * @param pBuffer [out] buffer of the selected data block
207    * @param size    [out] size of the selected data block
208    */
209   virtual int GetDataBuffer(AliHLTUInt32_t index, const AliHLTUInt8_t* &pBuffer, 
210                             AliHLTUInt32_t& size)=0;
211
212   /**
213    * Check byte order of data block
214    */
215   virtual AliHLTOUTByteOrder_t CheckBlockByteOrder(AliHLTUInt32_t index)=0;
216
217   /**
218    * Check alignment of data block
219    */
220   virtual int CheckBlockAlignment(AliHLTUInt32_t index, AliHLTOUT::AliHLTOUTDataType_t type)=0;
221
222   /**
223    * Select the data block of data type and specification of the previous
224    * call to @ref SelectFirstDataBlock. Core function of @ref SelectFirstDataBlock
225    * and @ref SelectNextDataBlock, starts to find a block at the current list
226    * position. 
227    * @return identifier >=0 if success, neg. error code if failed         <br>
228    *                        -ENOENT if no block found                     <br>
229    *                        -EPERM if access denied (object locked)
230    */
231   int FindAndSelectDataBlock();
232
233   /**
234    * Set status flag.
235    * @param flag     flag to set
236    * @return current status flags
237    */
238   unsigned int SetStatusFlag(unsigned int flag) {return fFlags|=flag;}
239
240   /**
241    * Clear status flag.
242    * @param flag     flag to clear
243    * @return current status flags
244    */
245   unsigned int ClearStatusFlag(unsigned int flag) {return fFlags&=~flag;}
246
247   /**
248    * Check status flag.
249    * @param flag     flag to check
250    * @return 1 if flag is set
251    */
252   int CheckStatusFlag(unsigned int flag) const {return (fFlags&flag)==flag;}
253
254   /** data type for the current block search, set from @ref SelectFirstDataBlock */
255   AliHLTComponentDataType fSearchDataType; //!transient
256
257   /** data specification for the current block search */
258   AliHLTUInt32_t fSearchSpecification; //!transient
259
260   /** instance flags: locked, collecting, ... */
261   unsigned int fFlags; //!transient
262
263   /** list of block descriptors */
264   vector<AliHLTOUTBlockDescriptor> fBlockDescList; //!transient
265
266   /** current position in the list */
267   vector<AliHLTOUTBlockDescriptor>::iterator fCurrent; //!transient
268
269   /** data buffer under processing */
270   const AliHLTUInt8_t* fpBuffer; //!transient
271
272   ClassDef(AliHLTOUT, 0)
273 };
274 #endif