scanning of handlers for HLTOUT blocks added
[u/mrichter/AliRoot.git] / HLT / BASE / AliHLTOUT.h
CommitLineData
62bb3cd4 1//-*- Mode: C++ -*-
2// @(#) $Id$
3
4#ifndef ALIHLTOUT_H
5#define ALIHLTOUT_H
5db0e774 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 *
62bb3cd4 9
10/** @file AliHLTOUT.h
11 @author Matthias Richter
12 @date
13 @brief The control class for HLTOUT data.
5db0e774 14*/
62bb3cd4 15
4de7334f 16#include <vector>
62bb3cd4 17#include "AliHLTLogging.h"
5db0e774 18#include "AliHLTModuleAgent.h"
19
20class AliHLTOUTHandler;
21class AliHLTOUTHandlerDesc;
22
23#define AliHLTOUTInvalidIndex (~(AliHLTUInt32_t)0)
24
25typedef vector<AliHLTUInt32_t> AliHLTOUTIndexList;
62bb3cd4 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 */
36class AliHLTOUT : public AliHLTLogging {
37 public:
38 /** standard constructor */
39 AliHLTOUT();
40 /** standard destructor */
41 virtual ~AliHLTOUT();
42
4de7334f 43 /**
5db0e774 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 /**
4de7334f 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.
5db0e774 60 *
61 * The search criteria can be combined with a handler type (e.g. kRawReader)
4de7334f 62 * @param dt [in] data type to match <br>
63 * @param spec [in] data specification to match <br>
5db0e774 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>
4de7334f 67 * -EPERM if access denied (object locked)
68 */
5db0e774 69 int SelectFirstDataBlock(AliHLTComponentDataType dt, AliHLTUInt32_t spec,
70 AliHLTModuleAgent::AliHLTOUTHandlerType handlerType=AliHLTModuleAgent::kUnknownOutput);
4de7334f 71
72 /**
73 * Select the next data block of data type and specification of the previous
74 * call to @ref SelectFirstDataBlock.
5db0e774 75 * @return identifier >0 if success, 0 if no block found <br>
76 * neg. error code if failed <br>
4de7334f 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 /**
5db0e774 89 * Get the index of the current data block.
90 * @return index, AliHLTOUTInvalidIndex if no block selected
91 */
92 AliHLTUInt32_t GetDataBlockIndex();
93
94 /**
4de7334f 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)
049b43b2 115 {if (fpInstance) fpInstance->SetStatusFlag(kLocked);}
4de7334f 116 /** destructor */
117 ~AliHLTOUTLockGuard()
049b43b2 118 {if (fpInstance) fpInstance->ClearStatusFlag(kLocked);}
4de7334f 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 /**
4b113031 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 /**
4de7334f 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
049b43b2 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
62bb3cd4 207 protected:
4de7334f 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);
62bb3cd4 216
217 private:
218 /** copy constructor prohibited */
219 AliHLTOUT(const AliHLTOUT&);
220 /** assignment operator prohibited */
221 AliHLTOUT& operator=(const AliHLTOUT&);
222
4de7334f 223 /**
049b43b2 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
5db0e774 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
049b43b2 283 /**
4de7334f 284 * Generate the index of the HLTOUT data.
285 * Must be implemented by the child classes.
286 */
287 virtual int GenerateIndex()=0;
288
289 /**
5db0e774 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 /**
4de7334f 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
049b43b2 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
5db0e774 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
4de7334f 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
049b43b2 364 /** instance flags: locked, collecting, ... */
365 unsigned int fFlags; //!transient
4de7334f 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
5db0e774 376 /** list of AliHLTOUTHandlers */
377 vector<AliHLTOUTHandlerListEntry> fDataHandlers; // !transient
378
379 ClassDef(AliHLTOUT, 1)
62bb3cd4 380};
381#endif