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 *
11 @author Matthias Richter
13 @brief The control class for HLTOUT data.
17 #include "AliHLTLogging.h"
18 #include "AliHLTModuleAgent.h"
20 class AliHLTOUTHandler;
21 class AliHLTOUTHandlerDesc; // AliHLTModuleAgent.h
23 class AliHLTReconstructor;
25 #define AliHLTOUTInvalidIndex (~(AliHLTUInt32_t)0)
27 typedef vector<AliHLTUInt32_t> AliHLTOUTIndexList;
31 * The control class for HLTOUT data.
32 * The output of the HLT, either from the HLTOUT nodes or simulated output,
33 * is transferred and stored in the HOMER format. The AliHLTOUT class
34 * implements scanning of the HOMER data for all HLTOUT DDL links and
35 * abstracts access to the complete HLTOUT data.
38 class AliHLTOUT : public AliHLTLogging {
40 /** standard constructor */
42 /** standard destructor */
46 * Locking guard for the AliHLTOUT object.
47 * If the object is locked, the selection of data blocks can not be changed.
49 class AliHLTOUTLockGuard {
52 AliHLTOUTLockGuard(AliHLTOUT* pInstance) : fpInstance(pInstance)
53 {if (fpInstance) fpInstance->SetStatusFlag(kLocked);}
56 {if (fpInstance) fpInstance->ClearStatusFlag(kLocked);}
59 /** standard constructor prohibited */
61 /** copy constructor prohibited */
62 AliHLTOUTLockGuard(const AliHLTOUTLockGuard&);
63 /** assignment operator prohibited */
64 AliHLTOUTLockGuard& operator=(const AliHLTOUTLockGuard&);
66 /** the AliHLTOUT instance the guard is locking */
67 AliHLTOUT* fpInstance; //!transient
71 * The HLT OUT Event Header.
72 * Defined between HLT and DAQ.
74 struct AliHLTOUTEventHeader {
75 /**Total length of the data in bytes, including HLT event header, excluding CDH. */
76 AliHLTUInt32_t fLength; //! see above
77 /** version of the header */
78 AliHLTUInt32_t fVersion; //! see above
80 AliHLTUInt64_t fEventID; //! see above
84 /// versions 1 of the HLT header
86 /// versions 2 of the HLT header
91 /// size of HLT decision in data format version 1: 29x4
92 kSizeDecisionVersion1 = 116,
93 /// size of HLT decision in data format version 2: 30x4
94 kSizeDecisionVersion2 = 120
97 // definitions from ALICE internal notes ALICE-INT-2002-010 and
100 /** the 32bit word in the CDH containing the status flags */
101 kCDHStatusWord=4, //! see above
102 /** start of the flags in word fgkCDHStatusWord */
103 kCDHStatusFlagsOffset=12, //! see above
104 /** bit indicating HLT decision in the HLTOUT*/
105 kCDHFlagsHLTDecision=6, //! see above
106 /** bit indicating HLT payload in the HLTOUT*/
107 kCDHFlagsHLTPayload=7 //! see above
113 class AliHLTOUTBlockDescriptor {
115 AliHLTOUTBlockDescriptor(AliHLTComponentDataType dt, AliHLTUInt32_t spec, AliHLTUInt32_t index)
116 : fDataType(dt), fSpecification(spec), fIndex(index) {};
117 ~AliHLTOUTBlockDescriptor() {}
119 operator AliHLTComponentDataType() const {return fDataType;}
120 operator AliHLTUInt32_t() const {return fSpecification;}
121 int operator==(AliHLTComponentDataType dt) const {return dt==fDataType;}
122 int operator==(AliHLTUInt32_t spec) const {return spec==fSpecification;}
124 AliHLTUInt32_t GetIndex() const {return fIndex;}
126 /** data type of the block */
127 AliHLTComponentDataType fDataType; //!transient
128 /** data specification of the block */
129 AliHLTUInt32_t fSpecification; //!transient
130 /** index in the data stream */
131 AliHLTUInt32_t fIndex; //!transient
134 class AliHLTOUTHandlerListEntry {
136 AliHLTOUTHandlerListEntry(AliHLTOUTHandler* pHandler,
137 AliHLTModuleAgent::AliHLTOUTHandlerDesc& handlerDesc,
138 AliHLTModuleAgent* pAgent,
139 AliHLTUInt32_t index);
141 /** copy constructor for vector handling */
142 AliHLTOUTHandlerListEntry(const AliHLTOUTHandlerListEntry& src);
144 /** assignment operator for vector handling */
145 AliHLTOUTHandlerListEntry& operator=(const AliHLTOUTHandlerListEntry& src);
147 ~AliHLTOUTHandlerListEntry();
149 static const AliHLTOUTHandlerListEntry fgkVoidHandlerListEntry; //! initializer
151 operator AliHLTOUTHandler*() const {return fpHandler;}
153 // please note that fpHandlerDesc is really a pointer and is created
154 // in the constructor. Thats why it is dereferenced here. The pointer
155 // type is on purpose, even though it is a bit confusing with the
156 // argument by reference in the AliHLTOUTHandlerListEntry constructor.
157 operator const AliHLTModuleAgent::AliHLTOUTHandlerDesc&() const
158 {return fpHandlerDesc?*fpHandlerDesc:AliHLTModuleAgent::fgkVoidHandlerDesc;}
159 operator AliHLTModuleAgent*() const {return fpAgent;}
162 * Two list entries are considered to be equal if the handlers
165 bool operator==(const AliHLTOUTHandlerListEntry& entry) const;
167 bool operator==(const AliHLTModuleAgent::AliHLTOUTHandlerType handlerType) const;
169 AliHLTUInt32_t operator[](int i) const;
172 * Add a block index to this descriptor.
173 * One descriptor can serve multiple blocks if the agent returns the
174 * same handler for all of the blocks. Instead of creating a new entry
175 * the block index ist just added
177 void AddIndex(AliHLTUInt32_t index);
180 * Add all indexes of the descriptor.
182 void AddIndex(AliHLTOUTHandlerListEntry &desc);
185 * Check if an index is served by this descriptor.
186 * @return true if the index is in the table
188 bool HasIndex(AliHLTUInt32_t index);
191 /** standard constructor prohibited */
192 AliHLTOUTHandlerListEntry();
194 /** pointer to the handler */
195 AliHLTOUTHandler* fpHandler; //! transient
197 /** pointer to handler description */
198 AliHLTModuleAgent::AliHLTOUTHandlerDesc* fpHandlerDesc; //! transient
200 /** pointer to module agent */
201 AliHLTModuleAgent* fpAgent; //! transient
203 /** list of block indexes */
204 AliHLTOUTIndexList fBlocks; //!transient
207 typedef vector<AliHLTOUTHandlerListEntry> AliHLTOUTHandlerListEntryVector;
208 typedef vector<AliHLTOUTBlockDescriptor> AliHLTOUTBlockDescriptorVector;
211 * Init for processing.
212 * The HLTOUT is scanned for all available data blocks and the
213 * AliHLTOUTHandler objects for the data blocks are created according
214 * to the module agents (see AliHLTModuleAgent).
219 * Get number of data blocks in the HLTOUT data
221 int GetNofDataBlocks();
224 * Select the first data block of a certain data type and specification.
225 * The selection criteria can be of kAliHLTAnyDataType and/or
226 * kAliHLTVoidDataSpec in order to be ignored and just match any data block.
228 * The search criteria can be combined with a handler type (e.g. kRawReader)
229 * @param dt [in] data type to match <br>
230 * @param spec [in] data specification to match <br>
231 * @param handlerType [in] type of the handler
232 * @return identifier >0 if success, 0 if no block found <br>
233 * neg. error code if failed <br>
234 * -EPERM if access denied (object locked)
236 int SelectFirstDataBlock(AliHLTComponentDataType dt=kAliHLTAnyDataType,
237 AliHLTUInt32_t spec=kAliHLTVoidDataSpec,
238 AliHLTModuleAgent::AliHLTOUTHandlerType handlerType=AliHLTModuleAgent::kUnknownOutput);
241 * Select the next data block of data type and specification of the previous
242 * call to @ref SelectFirstDataBlock.
243 * @return identifier >0 if success, 0 if no block found <br>
244 * neg. error code if failed <br>
245 * -EPERM if access denied (object locked)
247 int SelectNextDataBlock();
250 * Get properties of the selected data block.
251 * @param dt [out] data type of the selected block
252 * @param spec [out] data specification of the selected block
254 int GetDataBlockDescription(AliHLTComponentDataType& dt, AliHLTUInt32_t& spec);
257 * Get handler description of the current data block.
259 const AliHLTOUTHandlerListEntry& GetDataBlockHandlerDesc();
262 * Get handler type of the selected data block.
263 * @return handler type for the selected data block
265 AliHLTModuleAgent::AliHLTOUTHandlerType GetDataBlockHandlerType();
268 * Get the index of the current data block.
269 * @return index, AliHLTOUTInvalidIndex if no block selected
271 AliHLTUInt32_t GetDataBlockIndex();
274 * Get buffer of the selected data block.
275 * @param pBuffer [out] buffer of the selected data block
276 * @param size [out] size of the selected data block
278 int GetDataBuffer(const AliHLTUInt8_t* &pBuffer, AliHLTUInt32_t& size);
281 * Release buffer after use.
282 * @param pBuffer [in] buffer of the selected data block
284 int ReleaseDataBuffer(const AliHLTUInt8_t* pBuffer);
287 * Get module agent for the selected data block.
289 AliHLTModuleAgent* GetAgent();
292 * Get handler for the selected data block.
294 AliHLTOUTHandler* GetHandler();
297 * Convert data buffer to ESD.
298 * The buffer is supposed to describe a streamed AliESDEvent object.
299 * If no target object is specified, the ESD is written to a file AliHLTdetESDs.root,
300 * where 'det' is derived from the data type origin. Each time the function is invoked
301 * a new event is created. Dummy events are added if the previous events did not contain
303 * The function needs AliRoot and might not be implemented by all AliHLTOUT
305 * a data block of this specification.
306 * @param pBuffer [in] the data buffer
307 * @param size [in] data buffer size
308 * @param dt [in] data type of the block
309 * @param tgtesd [out] optional target
311 virtual int WriteESD(const AliHLTUInt8_t* pBuffer, AliHLTUInt32_t size, AliHLTComponentDataType dt, AliESDEvent* tgtesd=NULL) const;
313 enum AliHLTOUTByteOrder {
314 /** no data block selected */
315 kInvalidByteOrder=-1,
321 enum AliHLTOUTDataType {
331 * Check byte order of selected block
333 AliHLTOUTByteOrder CheckByteOrder();
336 * Check alignment of selected block
338 int CheckAlignment(AliHLTOUT::AliHLTOUTDataType type);
341 * Helper function to byte swap a 64 bit value.
343 static AliHLTUInt64_t ByteSwap64(AliHLTUInt64_t src);
346 * Helper function to byte swap a 32 bit value.
348 static AliHLTUInt32_t ByteSwap32(AliHLTUInt32_t src);
351 * Insert a handler item.
352 * The current list entries are checked if the handler is already in
353 * the list. It is added if not in the list, otherwise the block index
354 * is added to the existing entry.
355 * @param list the handler list
356 * @param entry handler list entry
357 * @return 0 if added, EEXIST (non negative!) if merged with existing entry <br>
358 * neg. error code if failed
360 static int InsertHandler(AliHLTOUTHandlerListEntryVector& list, const AliHLTOUTHandlerListEntry &entry);
364 * Add a block descriptor.
365 * This is done by the child classes generating the index. The AliHLTOUT
366 * object must be locked for index generation.
367 * @param desc the block descriptor
368 * @return 0 if success, -EPERM if access denied
370 int AddBlockDescriptor(const AliHLTOUTBlockDescriptor desc);
373 * Print output or suppress.
375 bool BeVerbose() {return fbVerbose;}
380 void SwitchVerbosity(bool verbose) {fbVerbose=verbose;}
383 /** copy constructor prohibited */
384 AliHLTOUT(const AliHLTOUT&);
385 /** assignment operator prohibited */
386 AliHLTOUT& operator=(const AliHLTOUT&);
389 * Internal status flags
392 /** the HLTOUT object is locked with the current data block */
394 /** childs can add block descriptors */
396 /** user of the data block has checked the byte order */
397 kByteOrderChecked = 0x4,
398 /** warning on byte order missmatch has been printed */
399 kByteOrderWarning = 0x8,
400 /** user of the data block has checked the alignment */
401 kAlignmentChecked = 0x10,
402 /** warning on alignment missmatch has been printed */
403 kAlignmentWarning = 0x20
407 * Generate the index of the HLTOUT data.
408 * Must be implemented by the child classes.
410 virtual int GenerateIndex()=0;
413 * Find AliHLTOUTHandler objects for the data blocks.
414 * The available AliHLTModuleAgents are probed whether they provide
415 * handlers for data processing.
420 * Get the data buffer
421 * @param index [in] index of the block
422 * @param pBuffer [out] buffer of the selected data block
423 * @param size [out] size of the selected data block
425 virtual int GetDataBuffer(AliHLTUInt32_t index, const AliHLTUInt8_t* &pBuffer,
426 AliHLTUInt32_t& size)=0;
429 * Check byte order of data block
431 virtual AliHLTOUTByteOrder CheckBlockByteOrder(AliHLTUInt32_t index)=0;
434 * Check alignment of data block
436 virtual int CheckBlockAlignment(AliHLTUInt32_t index, AliHLTOUT::AliHLTOUTDataType type)=0;
439 * Select the data block of data type and specification of the previous
440 * call to @ref SelectFirstDataBlock. Core function of @ref SelectFirstDataBlock
441 * and @ref SelectNextDataBlock, starts to find a block at the current list
443 * @return identifier >=0 if success, neg. error code if failed <br>
444 * -ENOENT if no block found <br>
445 * -EPERM if access denied (object locked)
447 int FindAndSelectDataBlock();
451 * @param flag flag to set
452 * @return current status flags
454 unsigned int SetStatusFlag(unsigned int flag) {return fFlags|=flag;}
458 * @param flag flag to clear
459 * @return current status flags
461 unsigned int ClearStatusFlag(unsigned int flag) {return fFlags&=~flag;}
465 * @param flag flag to check
466 * @return 1 if flag is set
468 int CheckStatusFlag(unsigned int flag) const {return (fFlags&flag)==flag;}
471 * Find handler description for a certain block index.
473 const AliHLTOUTHandlerListEntry& FindHandlerDesc(AliHLTUInt32_t blockIndex);
475 /** data type for the current block search, set from @ref SelectFirstDataBlock */
476 AliHLTComponentDataType fSearchDataType; //!transient
478 /** data specification for the current block search */
479 AliHLTUInt32_t fSearchSpecification; //!transient
481 /** handler type for the current block search */
482 AliHLTModuleAgent::AliHLTOUTHandlerType fSearchHandlerType; // !transient
484 /** instance flags: locked, collecting, ... */
485 unsigned int fFlags; //!transient
487 /** list of block descriptors */
488 AliHLTOUTBlockDescriptorVector fBlockDescList; //!transient
490 /** current position in the list */
491 AliHLTOUTBlockDescriptorVector::iterator fCurrent; //!transient
493 /** data buffer under processing */
494 const AliHLTUInt8_t* fpBuffer; //!transient
496 /** list of AliHLTOUTHandlers */
497 AliHLTOUTHandlerListEntryVector fDataHandlers; // !transient
499 /** verbose or silent output */
500 bool fbVerbose; //!transient
502 ClassDef(AliHLTOUT, 2)