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;
27 #define AliHLTOUTInvalidIndex (~(AliHLTUInt32_t)0)
29 typedef vector<AliHLTUInt32_t> AliHLTOUTIndexList;
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.
42 /** standard constructor */
44 /** standard destructor */
48 * Create an AliHLTOUTRawReader instance.
49 * Helper function to transparently access classes from the
52 static AliHLTOUT* New(AliRawReader* pRawReader);
55 * Create an AliHLTOUTDigitReader instance
56 * Helper function to transparently access classes from the
59 static AliHLTOUT* New(TTree* pDigitTree, int event=-1);
62 * Get the global instance.
63 * The global instance is set temporarily by the AliHLTOUTGlobalInstanceGuard
64 * mainly for the sake of data input to an analysis chain. The
65 * AliHLTOUTPublisherComponent objects can access the global instance.
67 static AliHLTOUT* GetGlobalInstance() {return fgGlobalInstance;}
70 * Delete an instance of the HLTOUT.
71 * Helper function to transparently access classes from the
72 * libHLTrec library. Before deleting, the availability of the
75 static void Delete(AliHLTOUT* pInstance);
78 * Locking guard for the AliHLTOUT object.
79 * If the object is locked, the selection of data blocks can not be changed.
81 class AliHLTOUTLockGuard {
84 AliHLTOUTLockGuard(AliHLTOUT* pInstance) : fpInstance(pInstance)
85 {if (fpInstance) fpInstance->SetStatusFlag(kLocked);}
88 {if (fpInstance) fpInstance->ClearStatusFlag(kLocked);}
91 /** standard constructor prohibited */
93 /** copy constructor prohibited */
94 AliHLTOUTLockGuard(const AliHLTOUTLockGuard&);
95 /** assignment operator prohibited */
96 AliHLTOUTLockGuard& operator=(const AliHLTOUTLockGuard&);
98 /** the AliHLTOUT instance the guard is locking */
99 AliHLTOUT* fpInstance; //!transient
103 * Guard for handling of global AliHLTOUT instance.
104 * The global HLTOUT instance can be set for certain steps of the
105 * processing. The initial objective is to support input to the
106 * AliHLTOUTPublisherComponent running in a kChain handler.
108 * The Guard restores the original instance when closed.
110 class AliHLTOUTGlobalInstanceGuard {
113 AliHLTOUTGlobalInstanceGuard(AliHLTOUT* pInstance) : fpLastInstance(AliHLTOUT::fgGlobalInstance)
114 {AliHLTOUT::fgGlobalInstance=pInstance;}
116 ~AliHLTOUTGlobalInstanceGuard()
117 {AliHLTOUT::fgGlobalInstance=fpLastInstance;}
120 /** standard constructor prohibited */
121 AliHLTOUTGlobalInstanceGuard();
122 /** copy constructor prohibited */
123 AliHLTOUTGlobalInstanceGuard(const AliHLTOUTGlobalInstanceGuard&);
124 /** assignment operator prohibited */
125 AliHLTOUTGlobalInstanceGuard& operator=(const AliHLTOUTGlobalInstanceGuard&);
127 /** the AliHLTOUT instance the guard is locking */
128 AliHLTOUT* fpLastInstance; //!transient
132 * The HLT OUT Event Header.
133 * Defined between HLT and DAQ.
135 struct AliHLTOUTEventHeader {
136 /**Total length of the data in bytes, including HLT event header, excluding CDH. */
137 AliHLTUInt32_t fLength; //! see above
138 /** version of the header */
139 AliHLTUInt32_t fVersion; //! see above
140 /** High 32 bit word of event id */
141 AliHLTUInt32_t fEventIDHigh; //! see above
142 /** Low 32 bit word of event id */
143 AliHLTUInt32_t fEventIDLow; //! see above
147 /// versions 1 of the HLT header
149 /// versions 2 of the HLT header
154 /// size of HLT decision in data format version 1: 29x4
155 kSizeDecisionVersion1 = 116,
156 /// size of HLT decision in data format version 2: 30x4
157 kSizeDecisionVersion2 = 120
160 // definitions from ALICE internal notes ALICE-INT-2002-010 and
161 // ALICE-INT-2006-XXX
163 /** the 32bit word in the CDH containing the status flags */
164 kCDHStatusWord=4, //! see above
165 /** start of the flags in word fgkCDHStatusWord */
166 kCDHStatusFlagsOffset=12, //! see above
167 /** bit indicating HLT decision in the HLTOUT*/
168 kCDHFlagsHLTDecision=6, //! see above
169 /** bit indicating HLT payload in the HLTOUT*/
170 kCDHFlagsHLTPayload=7 //! see above
173 class AliHLTOUTHandlerListEntry;
177 class AliHLTOUTBlockDescriptor {
179 AliHLTOUTBlockDescriptor(AliHLTComponentDataType dt, AliHLTUInt32_t spec, AliHLTUInt32_t index, AliHLTOUT* pCollection)
180 : fDataType(dt), fSpecification(spec), fIndex(index), fSelected(false), fProcessed(false), fpCollection(pCollection) {};
181 AliHLTOUTBlockDescriptor(const AliHLTOUTBlockDescriptor& src)
182 : fDataType(src.fDataType), fSpecification(src.fSpecification), fIndex(src.fIndex), fSelected(false), fProcessed(false), fpCollection(src.fpCollection) {}
183 AliHLTOUTBlockDescriptor& operator=(const AliHLTOUTBlockDescriptor& src)
184 { fDataType=src.fDataType; fSpecification=src.fSpecification; fIndex=src.fIndex; fSelected=false; fProcessed=false; fpCollection=src.fpCollection; return *this; }
185 ~AliHLTOUTBlockDescriptor() {}
187 operator AliHLTComponentDataType() const {return fDataType;}
188 operator AliHLTUInt32_t() const {return fSpecification;}
189 int operator==(AliHLTComponentDataType dt) const {return dt==fDataType;}
190 int operator==(AliHLTUInt32_t spec) const {return spec==fSpecification;}
191 int operator==(AliHLTOUT* collection) const {return collection==fpCollection;}
193 AliHLTUInt32_t GetIndex() const {return fIndex;}
194 AliHLTOUT* GetCollection() const {return fpCollection;}
196 bool IsSelected() const {return fSelected;}
197 void Select(bool selected=true) {fSelected=selected;}
198 bool IsProcessed() const {return fProcessed;}
199 void MarkProcessed() {fProcessed=true;}
202 * Get the data buffer
203 * @param pBuffer [out] buffer of the selected data block
204 * @param size [out] size of the selected data block
206 int GetDataBuffer(const AliHLTUInt8_t* &pBuffer, AliHLTUInt32_t& size) {
207 if (fpCollection) return fpCollection->GetDataBuffer(GetIndex(), pBuffer, size);
212 * Get the handler descriptor
214 const AliHLTOUTHandlerListEntry& GetHandlerDesc();
217 /** data type of the block */
218 AliHLTComponentDataType fDataType; //!transient
219 /** data specification of the block */
220 AliHLTUInt32_t fSpecification; //!transient
221 /** index in the data stream */
222 AliHLTUInt32_t fIndex; //!transient
223 /** selection flag */
224 bool fSelected; //!transient
225 /** processed flag */
226 bool fProcessed; //!transient
227 /** the collection */
228 AliHLTOUT* fpCollection; //!transient
231 class AliHLTOUTHandlerListEntry {
233 AliHLTOUTHandlerListEntry(AliHLTOUTHandler* pHandler,
234 AliHLTModuleAgent::AliHLTOUTHandlerDesc& handlerDesc,
235 AliHLTModuleAgent* pAgent,
236 AliHLTUInt32_t index);
238 /** copy constructor for vector handling */
239 AliHLTOUTHandlerListEntry(const AliHLTOUTHandlerListEntry& src);
241 /** assignment operator for vector handling */
242 AliHLTOUTHandlerListEntry& operator=(const AliHLTOUTHandlerListEntry& src);
244 ~AliHLTOUTHandlerListEntry();
246 static const AliHLTOUTHandlerListEntry fgkVoidHandlerListEntry; //! initializer
248 operator AliHLTOUTHandler*() const {return fpHandler;}
250 // please note that fpHandlerDesc is really a pointer and is created
251 // in the constructor. Thats why it is dereferenced here. The pointer
252 // type is on purpose, even though it is a bit confusing with the
253 // argument by reference in the AliHLTOUTHandlerListEntry constructor.
254 operator const AliHLTModuleAgent::AliHLTOUTHandlerDesc&() const
255 {return fpHandlerDesc?*fpHandlerDesc:AliHLTModuleAgent::fgkVoidHandlerDesc;}
256 operator AliHLTModuleAgent*() const {return fpAgent;}
259 * Two list entries are considered to be equal if the handlers
262 bool operator==(const AliHLTOUTHandlerListEntry& entry) const;
264 bool operator==(const AliHLTModuleAgent::AliHLTOUTHandlerType handlerType) const;
267 * Compare the handler descriptor of this list entry with another
269 * @return true if both handler and agent match
271 bool operator==(const AliHLTModuleAgent::AliHLTOUTHandlerDesc desc) const;
273 AliHLTUInt32_t operator[](int i) const;
276 * Add a block index to this descriptor.
277 * One descriptor can serve multiple blocks if the agent returns the
278 * same handler for all of the blocks. Instead of creating a new entry
279 * the block index ist just added
281 void AddIndex(AliHLTUInt32_t index);
284 * Add all indices of the descriptor.
286 void AddIndex(AliHLTOUTHandlerListEntry &desc);
289 * Check if an index is served by this descriptor.
290 * @return true if the index is in the table
292 bool HasIndex(AliHLTUInt32_t index) const;
295 * Invalidate all block indices
297 void InvalidateBlocks() {fBlocks.clear();}
300 * Check whether the entry has valid blocks.
302 bool IsEmpty() {return fBlocks.size()==0;}
305 /** standard constructor prohibited */
306 AliHLTOUTHandlerListEntry();
308 /** pointer to the handler */
309 AliHLTOUTHandler* fpHandler; //! transient
311 /** pointer to handler description */
312 AliHLTModuleAgent::AliHLTOUTHandlerDesc* fpHandlerDesc; //! transient
314 /** pointer to module agent */
315 AliHLTModuleAgent* fpAgent; //! transient
317 /** list of block indices */
318 AliHLTOUTIndexList fBlocks; //!transient
321 typedef vector<AliHLTOUTHandlerListEntry> AliHLTOUTHandlerListEntryVector;
322 typedef vector<AliHLTOUTBlockDescriptor> AliHLTOUTBlockDescriptorVector;
323 typedef vector<AliHLTOUT*> AliHLTOUTPVector;
326 * Selection guard for the AliHLTOUT object.
327 * If the object is locked, the selection of data blocks can not be changed.
329 class AliHLTOUTSelectionGuard {
332 AliHLTOUTSelectionGuard(AliHLTOUT* pInstance) : fpInstance(pInstance)
333 {if (fpInstance) fpInstance->SelectDataBlock();}
335 AliHLTOUTSelectionGuard(AliHLTOUT* pInstance, const AliHLTOUTHandlerListEntry* pHandlerDesc) : fpInstance(pInstance)
336 {if (fpInstance) fpInstance->SelectDataBlocks(pHandlerDesc);}
338 ~AliHLTOUTSelectionGuard()
339 {if (fpInstance) fpInstance->DisableBlockSelection();}
342 /** standard constructor prohibited */
343 AliHLTOUTSelectionGuard();
344 /** copy constructor prohibited */
345 AliHLTOUTSelectionGuard(const AliHLTOUTSelectionGuard&);
346 /** assignment operator prohibited */
347 AliHLTOUTSelectionGuard& operator=(const AliHLTOUTSelectionGuard&);
349 /** the AliHLTOUT instance the guard is locking */
350 AliHLTOUT* fpInstance; //!transient
354 * Init for processing.
355 * The HLTOUT is scanned for all available data blocks and the
356 * AliHLTOUTHandler objects for the data blocks are created according
357 * to the module agents (see AliHLTModuleAgent).
362 * Reset and clear all data block descriptors.
363 * @note Since sub-collections are only referred via the block
364 * descriptors, all information on sub-collections is also lost.
365 * Child classes should implement ResetInput in order to cleanup
371 * Get number of data blocks in the HLTOUT data
373 int GetNofDataBlocks();
376 * Select the first data block of a certain data type and specification.
377 * The selection criteria can be of kAliHLTAnyDataType and/or
378 * kAliHLTVoidDataSpec in order to be ignored and just match any data block.
380 * The search criteria can be combined with a handler type (e.g. kRawReader)
381 * @param dt [in] data type to match <br>
382 * @param spec [in] data specification to match <br>
383 * @param handlerType [in] type of the handler
384 * @param skipProcessed [in] skip all block marked processed
385 * @return block index: >= 0 if success, -ENOENT if no block found <br>
386 * neg. error code if failed <br>
387 * -EPERM if access denied (object locked)
389 int SelectFirstDataBlock(AliHLTComponentDataType dt=kAliHLTAnyDataType,
390 AliHLTUInt32_t spec=kAliHLTVoidDataSpec,
391 AliHLTModuleAgent::AliHLTOUTHandlerType handlerType=AliHLTModuleAgent::kUnknownOutput,
392 bool skipProcessed=true);
395 * Select the next data block of data type and specification of the previous
396 * call to @ref SelectFirstDataBlock.
397 * @return block index: >= 0 if success, -ENOENT if no block found <br>
398 * neg. error code if failed <br>
399 * -EPERM if access denied (object locked)
401 int SelectNextDataBlock();
404 * Get properties of the selected data block.
405 * @param dt [out] data type of the selected block
406 * @param spec [out] data specification of the selected block
408 int GetDataBlockDescription(AliHLTComponentDataType& dt, AliHLTUInt32_t& spec);
411 * Get handler description of the current data block.
413 const AliHLTOUTHandlerListEntry& GetDataBlockHandlerDesc();
416 * Get handler type of the selected data block.
417 * @return handler type for the selected data block
419 AliHLTModuleAgent::AliHLTOUTHandlerType GetDataBlockHandlerType();
422 * Get the index of the current data block.
423 * @return index, AliHLTOUTInvalidIndex if no block selected
425 AliHLTUInt32_t GetDataBlockIndex();
428 * Get buffer of the selected data block.
429 * @param pBuffer [out] buffer of the selected data block
430 * @param size [out] size of the selected data block
432 int GetDataBuffer(const AliHLTUInt8_t* &pBuffer, AliHLTUInt32_t& size);
435 * Release buffer after use.
436 * @param pBuffer [in] buffer of the selected data block
438 int ReleaseDataBuffer(const AliHLTUInt8_t* pBuffer);
441 * Add the current data block to the selection.
442 * Note: enables also the block selection
444 int SelectDataBlock();
447 * Add the all data blocks of a certain handler to the selection.
448 * Note: enables also the block selection
450 int SelectDataBlocks(const AliHLTOUTHandlerListEntry* pHandlerDesc);
453 * Enable the selection of data blocks.
455 int EnableBlockSelection();
458 * Disable the selection of data blocks.
460 int DisableBlockSelection();
463 * Reset the data block selection.
464 * Resets the selection list, none of the blocks is selected.
466 int ResetBlockSelection();
469 * Mark the current block as processed.
471 int MarkDataBlockProcessed();
474 * Mark all data blocks of a certain handler processed.
476 int MarkDataBlocksProcessed(const AliHLTOUTHandlerListEntry* pHandlerDesc);
479 * Add a sub collection to the HLTOUT.
481 int AddSubCollection(AliHLTOUT* pCollection);
484 * Release a previously added sub collection.
486 int ReleaseSubCollection(AliHLTOUT* pCollection);
489 * Get module agent for the selected data block.
491 AliHLTModuleAgent* GetAgent();
494 * Get handler for the selected data block.
496 AliHLTOUTHandler* GetHandler();
499 * Convert data buffer to ESD.
500 * The buffer is supposed to describe a streamed AliESDEvent object.
501 * If no target object is specified, the ESD is written to a file AliHLTdetESDs.root,
502 * where 'det' is derived from the data type origin. Each time the function is invoked
503 * a new event is created. Dummy events are added if the previous events did not contain
505 * The function needs AliRoot and might not be implemented by all AliHLTOUT
507 * a data block of this specification.
508 * @param pBuffer [in] the data buffer
509 * @param size [in] data buffer size
510 * @param dt [in] data type of the block
511 * @param tgtesd [out] optional target
513 virtual int WriteESD(const AliHLTUInt8_t* pBuffer, AliHLTUInt32_t size, AliHLTComponentDataType dt, AliESDEvent* tgtesd=NULL) const;
515 enum AliHLTOUTByteOrder {
516 /** no data block selected */
517 kInvalidByteOrder=-1,
523 enum AliHLTOUTDataType {
533 * Check byte order of selected block
535 AliHLTOUTByteOrder CheckByteOrder();
538 * Check alignment of selected block
540 int CheckAlignment(AliHLTOUT::AliHLTOUTDataType type);
543 * Helper function to byte swap a 64 bit value.
545 static AliHLTUInt64_t ByteSwap64(AliHLTUInt64_t src);
548 * Helper function to byte swap a 32 bit value.
550 static AliHLTUInt32_t ByteSwap32(AliHLTUInt32_t src);
553 * Insert a handler item.
554 * The current list entries are checked if the handler is already in
555 * the list. It is added if not in the list, otherwise the block index
556 * is added to the existing entry.
557 * @param list the handler list
558 * @param entry handler list entry
559 * @return 0 if added, EEXIST (non negative!) if merged with existing entry <br>
560 * neg. error code if failed
562 static int InsertHandler(AliHLTOUTHandlerListEntryVector& list, const AliHLTOUTHandlerListEntry &entry);
565 * Insert all handlers of the specified type to the list.
567 int FillHandlerList(AliHLTOUTHandlerListEntryVector& list, AliHLTModuleAgent::AliHLTOUTHandlerType handlerType);
570 * Remove empty items which have a duplicate in the list.
572 static int RemoveEmptyDuplicateHandlers(AliHLTOUTHandlerListEntryVector& list);
575 * Find an entry of a certain description in the list.
576 * @return index of the entry if found, -ENOENT if not found
578 static int FindHandler(AliHLTOUTHandlerListEntryVector& list, const AliHLTModuleAgent::AliHLTOUTHandlerDesc desc);
581 * Invalidate all blocks of the handlers in the list
583 static int InvalidateBlocks(AliHLTOUTHandlerListEntryVector& list);
587 * Add a block descriptor.
588 * This is done by the child classes generating the index. The AliHLTOUT
589 * object must be locked for index generation.
590 * @param desc the block descriptor
591 * @return 0 if success, -EPERM if access denied
593 int AddBlockDescriptor(const AliHLTOUTBlockDescriptor desc);
596 * Print output or suppress.
598 bool BeVerbose() {return fbVerbose;}
603 void SwitchVerbosity(bool verbose) {fbVerbose=verbose;}
606 /** copy constructor prohibited */
607 AliHLTOUT(const AliHLTOUT&);
608 /** assignment operator prohibited */
609 AliHLTOUT& operator=(const AliHLTOUT&);
612 * Internal status flags
615 /** the HLTOUT object is locked with the current data block selection */
617 /** childs can add block descriptors */
619 /** user of the data block has checked the byte order */
620 kByteOrderChecked = 0x4,
621 /** warning on byte order missmatch has been printed */
622 kByteOrderWarning = 0x8,
623 /** user of the data block has checked the alignment */
624 kAlignmentChecked = 0x10,
625 /** warning on alignment missmatch has been printed */
626 kAlignmentWarning = 0x20,
627 /** enable block selection list */
628 kBlockSelection = 0x40,
629 /** skip processed data blocks */
630 kSkipProcessed = 0x80,
631 /** marked as sub collection */
632 kIsSubCollection = 0x100
636 * Generate the index of the HLTOUT data.
637 * Must be implemented by the child classes.
639 virtual int GenerateIndex()=0;
642 * Find AliHLTOUTHandler objects for the data blocks.
643 * The available AliHLTModuleAgents are probed whether they provide
644 * handlers for data processing.
649 * Cleanup and reset the data input.
651 virtual int ResetInput();
654 * Get the data buffer
655 * @param index [in] index of the block
656 * @param pBuffer [out] buffer of the selected data block
657 * @param size [out] size of the selected data block
659 virtual int GetDataBuffer(AliHLTUInt32_t index, const AliHLTUInt8_t* &pBuffer,
660 AliHLTUInt32_t& size)=0;
663 * Check byte order of data block
665 virtual AliHLTOUTByteOrder CheckBlockByteOrder(AliHLTUInt32_t index)=0;
668 * Check alignment of data block
670 virtual int CheckBlockAlignment(AliHLTUInt32_t index, AliHLTOUT::AliHLTOUTDataType type)=0;
673 * Select the data block of data type and specification of the previous
674 * call to @ref SelectFirstDataBlock. Core function of @ref SelectFirstDataBlock
675 * and @ref SelectNextDataBlock, starts to find a block at the current list
678 * The data block is searched from the conditions of fSearchDataType,
679 * fSearchSpecification, fSearchHandlerType and the selection list.
681 * @return identifier >=0 if success, neg. error code if failed <br>
682 * -ENOENT if no block found <br>
683 * -EPERM if access denied (object locked)
685 int FindAndSelectDataBlock();
689 * @param flag flag to set
690 * @return current status flags
692 unsigned int SetStatusFlag(unsigned int flag) {return fFlags|=flag;}
696 * @param flag flag to clear
697 * @return current status flags
699 unsigned int ClearStatusFlag(unsigned int flag) {return fFlags&=~flag;}
703 * @param flag flag to check
704 * @return 1 if flag is set
706 int CheckStatusFlag(unsigned int flag) const {return (fFlags&flag)==flag;}
709 * Find handler description for a certain block index.
711 const AliHLTOUTHandlerListEntry& FindHandlerDesc(AliHLTUInt32_t blockIndex);
714 * Internal New function for the external HLTOUT instances.
715 * Currently supported classes are AliHLTOUTRawReader and
716 * AliHLTOUTDigitReader, both implemented in libHLTrec.so.
718 static AliHLTOUT* New(const char* classname);
721 * Set the RawReader as parameter.
722 * The function is for internal use only in conjunction with the
725 virtual void SetParam(AliRawReader* pRawReader);
728 * Set the RunLoader as parameter
729 * The function is for internal use only in conjunction with the
732 virtual void SetParam(TTree* pDigitTree, int event=-1);
734 /** data type for the current block search, set from @ref SelectFirstDataBlock */
735 AliHLTComponentDataType fSearchDataType; //!transient
737 /** data specification for the current block search */
738 AliHLTUInt32_t fSearchSpecification; //!transient
740 /** handler type for the current block search */
741 AliHLTModuleAgent::AliHLTOUTHandlerType fSearchHandlerType; // !transient
743 /** instance flags: locked, collecting, ... */
744 unsigned int fFlags; //!transient
746 /** list of block descriptors */
747 AliHLTOUTBlockDescriptorVector fBlockDescList; //!transient
749 /** current position in the list */
750 unsigned int fCurrent; //!transient
752 /** data buffer under processing */
753 const AliHLTUInt8_t* fpBuffer; //!transient
755 /** list of AliHLTOUTHandlers */
756 AliHLTOUTHandlerListEntryVector fDataHandlers; // !transient
758 /** verbose or silent output */
759 bool fbVerbose; //!transient
761 /** gobal instance set for certain steps of the analysis */
762 static AliHLTOUT* fgGlobalInstance; //! transient
764 /** logging methods */
765 AliHLTLogging fLog; //! transient
767 ClassDef(AliHLTOUT, 4)