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