4 #ifndef ALIHLTCOMPONENT_H
5 #define ALIHLTCOMPONENT_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 */
10 /** @file AliHLTComponent.h
11 @author Matthias Richter, Timm Steinbeck
13 @brief Base class declaration for HLT components.
14 @note The class is both used in Online (PubSub) and Offline (AliRoot)
17 // see below for class documentation
19 // refer to README to build package
21 // visit http://web.ift.uib.no/~kjeks/doc/alice-hlt
24 * @defgroup alihlt_component Component handling of the HLT module
25 * This section describes the the component handling for the HLT module.
30 #include "AliHLTLogging.h"
31 #include "AliHLTDataTypes.h"
32 //#include "AliHLTDefinitions.h"
35 * The names have been changed for Aliroot's coding conventions sake
36 * The old names are defined for backward compatibility with the
37 * stand alone SampleLib package
39 typedef AliHLTComponentLogSeverity AliHLTComponent_LogSeverity;
40 typedef AliHLTComponentEventData AliHLTComponent_EventData;
41 typedef AliHLTComponentShmData AliHLTComponent_ShmData;
42 typedef AliHLTComponentDataType AliHLTComponent_DataType;
43 typedef AliHLTComponentBlockData AliHLTComponent_BlockData;
44 typedef AliHLTComponentTriggerData AliHLTComponent_TriggerData;
45 typedef AliHLTComponentEventDoneData AliHLTComponent_EventDoneData;
47 class AliHLTComponentHandler;
50 class AliHLTMemoryFile;
53 * @class AliHLTComponent
54 * Base class of HLT data processing components.
55 * The class provides a common interface for HLT data processing components.
56 * The interface can be accessed from the online HLT framework or the AliRoot
57 * offline analysis framework.
58 * @section alihltcomponent-properties Component identification and properties
59 * Each component must provide a unique ID, input and output data type indications,
60 * and a spawn function.
61 * @subsection alihltcomponent-req-methods Required property methods
62 * - @ref GetComponentID
63 * - @ref GetInputDataTypes (see @ref alihltcomponent-type for default
65 * - @ref GetOutputDataType (see @ref alihltcomponent-type for default
67 * - @ref GetOutputDataSize (see @ref alihltcomponent-type for default
71 * @subsection alihltcomponent-opt-mehods Optional handlers
74 * - @ref GetOutputDataTypes
75 * If the component has multiple output data types @ref GetOutputDataType
76 * should return @ref kAliHLTMultipleDataType. The framework will invoke
77 * @ref GetOutputDataTypes, a list can be filled.
79 * @subsection alihltcomponent-processing-mehods Data processing
82 * @subsection alihltcomponent-type Component type
83 * Components can be of type
84 * - @ref kSource components which only produce data
85 * - @ref kProcessor components which consume and produce data
86 * - @ref kSink components which only consume data
88 * where data production and consumption refer to the analysis data stream. In
89 * order to indicate the type, a child component can overload the
90 * @ref GetComponentType function.
91 * @subsubsection alihltcomponent-type-std Standard implementations
92 * Components in general do not need to implement this function, standard
93 * implementations of the 3 types are available:
94 * - AliHLTDataSource for components of type @ref kSource <br>
95 * All types of data sources can inherit from AliHLTDataSource and must
96 * implement the @ref AliHLTDataSource::GetEvent method. The class
97 * also implements a standard method for @ref GetInputDataTypes.
99 * - AliHLTProcessor for components of type @ref kProcessor <br>
100 * All types of data processors can inherit from AliHLTDataSource and must
101 * implement the @ref AliHLTProcessor::DoEvent method.
103 * - AliHLTDataSink for components of type @ref kSink <br>
104 * All types of data processors can inherit from AliHLTDataSource and must
105 * implement the @ref AliHLTDataSink::DumpEvent method. The class
106 * also implements a standard method for @ref GetOutputDataType and @ref
109 * @subsection alihltcomponent-environment Running environment
111 * In order to adapt to different environments (on-line/off-line), the component
112 * gets an environment structure with function pointers. The base class provides
113 * member functions for those environment dependend functions. The member
114 * functions are used by the component implementation and are re-mapped to the
115 * corresponding functions.
117 * @section alihltcomponent-interfaces Component interfaces
118 * Each of the 3 standard component base classes AliHLTProcessor, AliHLTDataSource
119 * and AliHLTDataSink provides it's own processing method (see
120 * @ref alihltcomponent-type-std), which splits into a high and a low-level
121 * method. For the @ref alihltcomponent-low-level-interface, all parameters are
122 * shipped as function arguments, the component is supposed to dump data to the
123 * output buffer and handle all block descriptors.
124 * The @ref alihltcomponent-high-level-interface is the standard processing
125 * method and will be used whenever the low-level method is not overloaded.
127 * In both cases it is necessary to calculate/estimate the size of the output
128 * buffer before the processing. Output buffers can never be allocated inside
129 * the component because of the push-architecture of the HLT.
130 * For that reason the @ref GetOutputDataSize function should return a rough
131 * estimatian of the data to be produced by the component. The component is
132 * responsible for checking the memory size and must return -ENOSPC if the
133 * available buffer is to small, and update the estimator respectively. The
134 * framework will allocate a buffer of appropriate size and call the processing
137 * @subsection alihltcomponent-error-codes Data processing
138 * For return codes, the following scheme applies:
139 * - The data processing methods have to indicate error conditions by a negative
140 * error/return code. Preferably the system error codes are used like
141 * e.g. -EINVAL. This requires to include the header
145 * - If no suitable input block could be found (e.g. no clusters for the TPC cluster
146 * finder) set size to 0, block list is empty, return 0
147 * - If no ususable or significant signal could be found in the input blocks
148 * return an empty output block, set size accordingly, and return 0. An empty output
149 * block here could be either a real empty one of size 0 (in which case size also
150 * would have to be set to zero) or a block filled with just the minimum necessary
151 * accounting/meta-structures. E.g. in the TPC
153 * @subsection alihltcomponent-high-level-interface High-level interface
154 * The high-level component interface provides functionality to exchange ROOT
155 * structures between components. In contrast to the
156 * @ref alihltcomponent-low-level-interface, a couple of functions can be used
157 * to access data blocks of the input stream
158 * and send data blocks or ROOT TObject's to the output stream. The functionality
159 * is hidden from the user and is implemented by using ROOT's TMessage class.
161 * @subsubsection alihltcomponent-high-level-int-methods Interface methods
162 * The interface provides a couple of methods in order to get objects from the
163 * input, data blocks (non TObject) from the input, and to push back objects and
164 * data blocks to the output. For convenience there are several functions of
165 * identical name (and similar behavior) with different parameters defined.
166 * Please refer to the function documentation.
167 * - @ref GetNumberOfInputBlocks <br>
168 * return the number of data blocks in the input stream
169 * - @ref GetFirstInputObject <br>
170 * get the first object of a specific data type
171 * - @ref GetNextInputObject <br>
172 * get the next object of same data type as last GetFirstInputObject/Block call
173 * - @ref GetFirstInputBlock <br>
174 * get the first block of a specific data type
175 * - @ref GetNextInputBlock <br>
176 * get the next block of same data type as last GetFirstInputBlock/Block call
177 * - @ref PushBack <br>
178 * insert an object or data buffer into the output
179 * - @ref CreateEventDoneData <br>
180 * add event information to the output
182 * In addition, the processing methods are simplified a bit by cutting out most of
185 * - @ref AliHLTProcessor::DoEvent
186 * - @ref AliHLTDataSource::GetEvent
187 * - @ref AliHLTDataSink::DumpEvent
189 * \em IMPORTANT: objects and block descriptors provided by the high-level interface
190 * <b>MUST NOT BE DELETED</b> by the caller.
192 * @subsubsection alihltcomponent-high-level-int-guidelines High-level interface guidelines
193 * - Structures must inherit from the ROOT object base class TObject in order be
194 * transported by the transportation framework.
195 * - all pointer members must be transient (marked <tt>//!</tt> behind the member
196 * definition), i.e. will not be stored/transported, or properly marked
197 * (<tt>//-></tt>) in order to call the streamer of the object the member is pointing
198 * to. The latter is not recomended. Structures to be transported between components
199 * should be streamlined.
200 * - no use of stl vectors/strings, use appropriate ROOT classes instead
202 * @subsection alihltcomponent-low-level-interface Low-level interface
203 * The low-level component interface consists of the specific data processing
204 * methods for @ref AliHLTProcessor, @ref AliHLTDataSource, and @ref AliHLTDataSink.
205 * - @ref AliHLTProcessor::DoEvent
206 * - @ref AliHLTDataSource::GetEvent
207 * - @ref AliHLTDataSink::DumpEvent
210 * @section alihltcomponent-handling Component handling
211 * The handling of HLT analysis components is carried out by the AliHLTComponentHandler.
212 * Component are registered automatically at load-time of the component shared library
213 * under the following suppositions:
214 * - the component library has to be loaded from the AliHLTComponentHandler using the
215 * @ref AliHLTComponentHandler::LoadLibrary method.
216 * - the component implementation defines one global object (which is generated
217 * when the library is loaded)
219 * @subsection alihltcomponent-design-rules General design considerations
220 * The analysis code should be implemented in one or more destict class(es). A
221 * \em component should be implemented which interface the destict analysis code to the
222 * component interface. This component generates the analysis object dynamically. <br>
224 * Assume you have an implemetation <tt> AliHLTDetMyAnalysis </tt>, another class <tt>
225 * AliHLTDetMyAnalysisComponent </tt> contains:
228 * AliHLTDetMyAnalysis* fMyAnalysis; //!
230 * The object should then be instantiated in the DoInit handler of
231 * <tt>AliHLTDetMyAnalysisComponent </tt>, and cleaned in the DoDeinit handler.
234 * - avoid big static arrays in the component, allocate the memory at runtime
236 * @ingroup alihlt_component
237 * @section alihltcomponent-members Class members
239 class AliHLTComponent : public AliHLTLogging {
241 /** standard constructor */
243 /** standard destructor */
244 virtual ~AliHLTComponent();
246 /** component type definitions */
247 enum TComponentType { kUnknown=0, kSource=1, kProcessor=2, kSink=3 };
250 * Init function to prepare data processing.
251 * Initialization of common data structures for a sequence of events.
252 * The call is redirected to the internal method @ref DoInit which can be
253 * overridden by the child class.<br>
254 * During Init also the environment structure is passed to the component.
255 * @param environ environment pointer with environment dependend function
257 * @param environParam additionel parameter for function calls, the pointer
259 * @param argc size of the argument array
260 * @param argv agument array for component initialization
262 virtual int Init( AliHLTComponentEnvironment* environ, void* environParam, int argc, const char** argv );
265 * Clean-up function to terminate data processing.
266 * Clean-up of common data structures after data processing.
267 * The call is redirected to the internal method @ref DoDeinit which can be
268 * overridden by the child class.
270 virtual int Deinit();
273 * Processing of one event.
274 * The method is the entrance of the event processing. The parameters are
275 * cached for uses with the high-level interface and the DoProcessing
276 * implementation is called.
283 * @param outputBlockCnt out: size of the output block array, set by the component
284 * @param outputBlocks out: the output block array is allocated internally
286 * @return neg. error code if failed
288 int ProcessEvent( const AliHLTComponentEventData& evtData, const AliHLTComponentBlockData* blocks,
289 AliHLTComponentTriggerData& trigData, AliHLTUInt8_t* outputPtr,
290 AliHLTUInt32_t& size, AliHLTUInt32_t& outputBlockCnt,
291 AliHLTComponentBlockData*& outputBlocks,
292 AliHLTComponentEventDoneData*& edd );
295 * Internal processing of one event.
296 * The method is pure virtual and implemented by the child classes
297 * - @ref AliHLTProcessor
298 * - @ref AliHLTDataSource
299 * - @ref AliHLTDataSink
306 * @param outputBlocks out: the output block array is allocated internally
308 * @return neg. error code if failed
310 virtual int DoProcessing( const AliHLTComponentEventData& evtData, const AliHLTComponentBlockData* blocks,
311 AliHLTComponentTriggerData& trigData, AliHLTUInt8_t* outputPtr,
312 AliHLTUInt32_t& size,
313 vector<AliHLTComponentBlockData>& outputBlocks,
314 AliHLTComponentEventDoneData*& edd ) = 0;
316 // Information member functions for registration.
319 * Get the type of the component.
320 * The function is pure virtual and must be implemented by the child class.
321 * @return component type id
323 virtual TComponentType GetComponentType() = 0; // Source, sink, or processor
326 * Get the id of the component.
327 * Each component is identified by a unique id.
328 * The function is pure virtual and must be implemented by the child class.
329 * @return component id (string)
331 virtual const char* GetComponentID() = 0;
334 * Get the input data types of the component.
335 * The function is pure virtual and must be implemented by the child class.
336 * @return list of data types in the vector reference
338 virtual void GetInputDataTypes( vector<AliHLTComponentDataType>& ) = 0;
341 * Get the output data type of the component.
342 * The function is pure virtual and must be implemented by the child class.
343 * @return output data type
345 virtual AliHLTComponentDataType GetOutputDataType() = 0;
348 * Get the output data types of the component.
349 * The function can be implemented to indicate multiple output data types
350 * in the target array.
351 * @ref GetOutputDataType must return @ref kAliHLTMultipleDataType in order
352 * to invoke this method.
353 * @param tgtList list to receive the data types
354 * @return no of output data types, data types in the target list
356 virtual int GetOutputDataTypes(vector<AliHLTComponentDataType>& tgtList);
359 * Get a ratio by how much the data volume is shrinked or enhanced.
360 * The function is pure virtual and must be implemented by the child class.
361 * @param constBase <i>return</i>: additive part, independent of the
363 * @param inputMultiplier <i>return</i>: multiplication ratio
364 * @return values in the reference variables
366 virtual void GetOutputDataSize( unsigned long& constBase, double& inputMultiplier ) = 0;
370 * Each component must implement a spawn function to create a new instance of
371 * the class. Basically the function must return <i>new <b>my_class_name</b></i>.
372 * @return new class instance
374 virtual AliHLTComponent* Spawn() = 0;
377 * Find matching data types between this component and a consumer component.
378 * Currently, a component can produce only one type of data. This restriction is most
379 * likely to be abolished in the future.
380 * @param pConsumer a component and consumer of the data produced by this component
381 * @param tgtList reference to a vector list to receive the matching data types.
382 * @return >= 0 success, neg. error code if failed
384 int FindMatchingDataTypes(AliHLTComponent* pConsumer, vector<AliHLTComponentDataType>* tgtList);
387 * Set the global component handler.
388 * The static method is needed for the automatic registration of components.
390 static int SetGlobalComponentHandler(AliHLTComponentHandler* pCH, int bOverwrite=0);
393 * Clear the global component handler.
394 * The static method is needed for the automatic registration of components.
396 static int UnsetGlobalComponentHandler();
399 * Helper function to convert the data type to a string.
401 static string DataType2Text( const AliHLTComponentDataType& type );
404 * Helper function to print content of data type.
406 void PrintDataTypeContent(AliHLTComponentDataType& dt, const char* format=NULL) const;
409 * helper function to initialize AliHLTComponentEventData structure
411 static void FillEventData(AliHLTComponentEventData& evtData);
414 * Print info on an AliHLTComponentDataType structure
415 * This is just a helper function to examine an @ref AliHLTComponentDataType
418 void PrintComponentDataTypeInfo(const AliHLTComponentDataType& dt);
421 * Stopwatch type for benchmarking.
423 enum AliHLTStopwatchType {
424 /** total time for event processing */
426 /** detector algorithm w/o interface callbacks */
432 /** number of types */
437 * Helper class for starting and stopping a stopwatch.
438 * The guard can be used by instantiating an object in a function. The
439 * specified stopwatch is started and the previous stopwatch put on
440 * hold. When the function is terminated, the object is deleted automatically
441 * deleted, stopping the stopwatch and starting the one on hold.<br>
442 * \em IMPORTANT: never create dynamic objects from this guard as this violates
443 * the idea of a guard.
445 class AliHLTStopwatchGuard {
447 /** standard constructor (not for use) */
448 AliHLTStopwatchGuard();
450 AliHLTStopwatchGuard(TStopwatch* pStart);
451 /** copy constructor (not for use) */
452 AliHLTStopwatchGuard(const AliHLTStopwatchGuard&);
453 /** assignment operator (not for use) */
454 AliHLTStopwatchGuard& operator=(const AliHLTStopwatchGuard&);
456 ~AliHLTStopwatchGuard();
460 * Hold the previous guard for the existence of this guard.
461 * Checks whether this guard controls a new stopwatch. In that case, the
462 * previous guard and its stopwatch are put on hold.
463 * @param pSucc instance of the stopwatch of the new guard
464 * @return 1 if pSucc is a different stopwatch which should
466 * 0 if it controls the same stopwatch
468 int Hold(TStopwatch* pSucc);
471 * Resume the previous guard.
472 * Checks whether the peceeding guard controls a different stopwatch. In that
473 * case, the its stopwatch is resumed.
474 * @param pSucc instance of the stopwatch of the new guard
475 * @return 1 if pSucc is a different stopwatch which should
477 * 0 if it controls the same stopwatch
479 int Resume(TStopwatch* pSucc);
481 /** the stopwatch controlled by this guard */
482 TStopwatch* fpStopwatch; //!transient
484 /** previous stopwatch guard, put on hold during existence of the guard */
485 AliHLTStopwatchGuard* fpPrec; //!transient
487 /** active stopwatch guard */
488 static AliHLTStopwatchGuard* fgpCurrent; //!transient
492 * Set a stopwatch for a given purpose.
493 * @param pSW stopwatch object
494 * @param type type of the stopwatch
496 int SetStopwatch(TObject* pSW, AliHLTStopwatchType type=kSWBase);
499 * Init a set of stopwatches.
500 * @param pStopwatches object array of stopwatches
502 int SetStopwatches(TObjArray* pStopwatches);
507 * Fill AliHLTComponentBlockData structure with default values.
508 * @param blockData reference to data structure
510 void FillBlockData( AliHLTComponentBlockData& blockData ) const;
513 * Fill AliHLTComponentShmData structure with default values.
514 * @param shmData reference to data structure
516 void FillShmData( AliHLTComponentShmData& shmData ) const;
519 * Fill AliHLTComponentDataType structure with default values.
520 * @param dataType reference to data structure
522 void FillDataType( AliHLTComponentDataType& dataType ) const;
525 * Copy data type structure
526 * Copies the value an AliHLTComponentDataType structure to another one
527 * @param[out] tgtdt target structure
528 * @param[in] srcdt source structure
530 void CopyDataType(AliHLTComponentDataType& tgtdt, const AliHLTComponentDataType& srcdt);
533 * Set the ID and Origin of an AliHLTComponentDataType structure.
534 * The function sets the fStructureSize member and copies the strings
535 * to the ID and Origin. Only characters from the valid part of the string
536 * are copied, the rest is fille with 0's.
537 * Please note that the fID and fOrigin members are not strings, just arrays of
538 * chars of size @ref kAliHLTComponentDataTypefIDsize and
539 * @ref kAliHLTComponentDataTypefOriginSize respectively and not necessarily with
540 * a terminating zero.
541 * @param tgtdt target data type structure
542 * @param id ID string
543 * @param origin Origin string
545 void SetDataType(AliHLTComponentDataType& tgtdt, const char* id, const char* origin);
548 * Default method for the internal initialization.
549 * The method is called by @ref Init
551 virtual int DoInit( int argc, const char** argv );
554 * Default method for the internal clean-up.
555 * The method is called by @ref Deinit
557 virtual int DoDeinit();
560 * General memory allocation method.
561 * All memory which is going to be used 'outside' of the interface must
562 * be provided by the framework (online or offline).
563 * The method is redirected to a function provided by the current
564 * framework. Function pointers are transferred via the @ref
565 * AliHLTComponentEnvironment structure.
567 void* AllocMemory( unsigned long size );
570 * Helper function to create a monolithic BlockData description block out
571 * of a list BlockData descriptors.
572 * For convenience, inside the interface vector lists are used, to make the
573 * interface pure C style, monilithic blocks must be exchanged.
574 * The method is redirected to a function provided by the current
575 * framework. Function pointers are transferred via the @ref
576 * AliHLTComponentEnvironment structure.
578 int MakeOutputDataBlockList( const vector<AliHLTComponentBlockData>& blocks, AliHLTUInt32_t* blockCount,
579 AliHLTComponentBlockData** outputBlocks );
582 * Fill the EventDoneData structure.
583 * The method is redirected to a function provided by the current
584 * framework. Function pointers are transferred via the @ref
585 * AliHLTComponentEnvironment structure.
587 int GetEventDoneData( unsigned long size, AliHLTComponentEventDoneData** edd );
590 * Helper function to convert the data type to a string.
592 void DataType2Text(const AliHLTComponentDataType& type, char output[kAliHLTComponentDataTypefIDsize+kAliHLTComponentDataTypefOriginSize+2]) const;
596 * @return value of the internal event counter
598 int GetEventCount() const;
601 * Get the number of input blocks.
602 * @return number of input blocks
604 int GetNumberOfInputBlocks() const;
607 * Get the first object of a specific data type from the input data.
608 * The hight-level methods provide functionality to transfer ROOT data
609 * structures which inherit from TObject.
610 * The method looks for the first ROOT object of type dt in the input stream.
611 * If also the class name is provided, the object is checked for the right
612 * class type. The input data block needs a certain structure, namely the
613 * buffer size as first word. If the cross check fails, the retrieval is
614 * silently abondoned, unless the \em bForce parameter is set.<br>
615 * \em Note: THE OBJECT MUST NOT BE DELETED by the caller.
616 * @param dt data type of the object
617 * @param classname class name of the object
618 * @param bForce force the retrieval of an object, error messages
619 * are suppressed if \em bForce is not set
620 * @return pointer to @ref TObject, NULL if no objects of specified type
623 const TObject* GetFirstInputObject(const AliHLTComponentDataType& dt=kAliHLTAnyDataType,
624 const char* classname=NULL,
628 * Get the first object of a specific data type from the input data.
629 * The hight-level methods provide functionality to transfer ROOT data
630 * structures which inherit from TObject.
631 * The method looks for the first ROOT object of type specified by the ID and
632 * Origin strings in the input stream.
633 * If also the class name is provided, the object is checked for the right
634 * class type. The input data block needs a certain structure, namely the
635 * buffer size as first word. If the cross check fails, the retrieval is
636 * silently abondoned, unless the \em bForce parameter is set.<br>
637 * \em Note: THE OBJECT MUST NOT BE DELETED by the caller.
638 * @param dtID data type ID of the object
639 * @param dtOrigin data type origin of the object
640 * @param classname class name of the object
641 * @param bForce force the retrieval of an object, error messages
642 * are suppressed if \em bForce is not set
643 * @return pointer to @ref TObject, NULL if no objects of specified type
646 const TObject* GetFirstInputObject(const char* dtID,
647 const char* dtOrigin,
648 const char* classname=NULL,
652 * Get the next object of a specific data type from the input data.
653 * The hight-level methods provide functionality to transfer ROOT data
654 * structures which inherit from TObject.
655 * The method looks for the next ROOT object of type and class specified
656 * to the previous @ref GetFirstInputObject call.<br>
657 * \em Note: THE OBJECT MUST NOT BE DELETED by the caller.
658 * @param bForce force the retrieval of an object, error messages
659 * are suppressed if \em bForce is not set
660 * @return pointer to @ref TObject, NULL if no more objects available
662 const TObject* GetNextInputObject(int bForce=0);
665 * Get data type of an input block.
666 * Get data type of the object previously fetched via
667 * GetFirstInputObject/NextInputObject or the last one if no object
669 * @param pObject pointer to TObject
670 * @return data specification, kAliHLTVoidDataSpec if failed
672 AliHLTComponentDataType GetDataType(const TObject* pObject=NULL);
675 * Get data specification of an input block.
676 * Get data specification of the object previously fetched via
677 * GetFirstInputObject/NextInputObject or the last one if no object
679 * @param pObject pointer to TObject
680 * @return data specification, kAliHLTVoidDataSpec if failed
682 AliHLTUInt32_t GetSpecification(const TObject* pObject=NULL);
685 * Get the first block of a specific data type from the input data.
686 * The method looks for the first block of type dt in the input stream. It is intended
687 * to be used within the high-level interface.<br>
688 * \em Note: THE BLOCK DESCRIPTOR MUST NOT BE DELETED by the caller.
689 * @param dt data type of the block
690 * @return pointer to @ref AliHLTComponentBlockData
692 const AliHLTComponentBlockData* GetFirstInputBlock(const AliHLTComponentDataType& dt=kAliHLTAnyDataType);
695 * Get the first block of a specific data type from the input data.
696 * The method looks for the first block of type specified by the ID and
697 * Origin strings in the input stream. It is intended
698 * to be used within the high-level interface.<br>
699 * \em Note: THE BLOCK DESCRIPTOR MUST NOT BE DELETED by the caller.
700 * @param dtID data type ID of the block
701 * @param dtOrigin data type origin of the block
702 * @return pointer to @ref AliHLTComponentBlockData
704 const AliHLTComponentBlockData* GetFirstInputBlock(const char* dtID,
705 const char* dtOrigin);
708 * Get input block by index.<br>
709 * \em Note: THE BLOCK DESCRIPTOR MUST NOT BE DELETED by the caller.
710 * @return pointer to AliHLTComponentBlockData, NULL if index out of range
712 const AliHLTComponentBlockData* GetInputBlock(int index);
715 * Get the next block of a specific data type from the input data.
716 * The method looks for the next block of type and class specified
717 * to the previous @ref GetFirstInputBlock call.
718 * To be used within the high-level interface.<br>
719 * \em Note: THE BLOCK DESCRIPTOR MUST NOT BE DELETED by the caller.
721 const AliHLTComponentBlockData* GetNextInputBlock();
724 * Get data specification of an input block.
725 * Get data specification of the input bblock previously fetched via
726 * GetFirstInputObject/NextInputObject or the last one if no block
728 * @param pBlock pointer to input block
729 * @return data specification, kAliHLTVoidDataSpec if failed
731 AliHLTUInt32_t GetSpecification(const AliHLTComponentBlockData* pBlock=NULL);
734 * Insert an object into the output.
735 * If header is specified, it will be inserted before the root object,
736 * default is no header.
737 * @param pObject pointer to root object
738 * @param dt data type of the object
739 * @param spec data specification
740 * @param pHeader pointer to header
741 * @param headerSize size of Header
742 * @return neg. error code if failed
744 int PushBack(TObject* pObject, const AliHLTComponentDataType& dt,
745 AliHLTUInt32_t spec=kAliHLTVoidDataSpec,
746 void* pHeader=NULL, int headerSize=0);
749 * Insert an object into the output.
750 * If header is specified, it will be inserted before the root object,
751 * default is no header.
752 * @param pObject pointer to root object
753 * @param dtID data type ID of the object
754 * @param dtOrigin data type origin of the object
755 * @param spec data specification
756 * @param pHeader pointer to header
757 * @param headerSize size of Header
758 * @return neg. error code if failed
760 int PushBack(TObject* pObject, const char* dtID, const char* dtOrigin,
761 AliHLTUInt32_t spec=kAliHLTVoidDataSpec,
762 void* pHeader=NULL, int headerSize=0);
765 * Insert an object into the output.
766 * @param pBuffer pointer to buffer
767 * @param iSize size of the buffer
768 * @param dt data type of the object
769 * @param spec data specification
770 * @param pHeader pointer to header
771 * @param headerSize size of Header
772 * @return neg. error code if failed
774 int PushBack(void* pBuffer, int iSize, const AliHLTComponentDataType& dt,
775 AliHLTUInt32_t spec=kAliHLTVoidDataSpec,
776 void* pHeader=NULL, int headerSize=0);
779 * Insert an object into the output.
780 * @param pBuffer pointer to buffer
781 * @param iSize size of the buffer
782 * @param dtID data type ID of the object
783 * @param dtOrigin data type origin of the object
784 * @param spec data specification
785 * @param pHeader pointer to header
786 * @param headerSize size of Header
787 * @return neg. error code if failed
789 int PushBack(void* pBuffer, int iSize, const char* dtID, const char* dtOrigin,
790 AliHLTUInt32_t spec=kAliHLTVoidDataSpec,
791 void* pHeader=NULL, int headerSize=0);
794 * Estimate size of a TObject
796 * @return buffer size in byte
798 int EstimateObjectSize(TObject* pObject) const;
801 * Create a memory file in the output stream.
802 * This method creates a TFile object which stores all data in
803 * memory instead of disk. The TFile object is published as binary data.
804 * The instance can be used like a normal TFile object. The TFile::Close
805 * or @ref CloseMemoryFile method has to be called in order to flush the
808 * \b Note: The returned object is deleted by the framework.
809 * @param capacity total size reserved for the memory file
810 * @param dtID data type ID of the file
811 * @param dtOrigin data type origin of the file
812 * @param spec data specification
813 * @return file handle, NULL if failed
815 AliHLTMemoryFile* CreateMemoryFile(int capacity, const char* dtID, const char* dtOrigin,
816 AliHLTUInt32_t spec=kAliHLTVoidDataSpec);
819 * Create a memory file in the output stream.
820 * This method creates a TFile object which stores all data in
821 * memory instead of disk. The TFile object is published as binary data.
822 * The instance can be used like a normal TFile object. The TFile::Close
823 * or @ref CloseMemoryFile method has to be called in order to flush the
826 * \b Note: The returned object is deleted by the framework.
827 * @param capacity total size reserved for the memory file
828 * @param dt data type of the file
829 * @param spec data specification
830 * @return file handle, NULL if failed
832 AliHLTMemoryFile* CreateMemoryFile(int capacity,
833 const AliHLTComponentDataType& dt=kAliHLTAnyDataType,
834 AliHLTUInt32_t spec=kAliHLTVoidDataSpec);
837 * Create a memory file in the output stream.
838 * This method creates a TFile object which stores all data in
839 * memory instead of disk. The TFile object is published as binary data.
840 * The instance can be used like a normal TFile object. The TFile::Close
841 * or @ref CloseMemoryFile method has to be called in order to flush the
844 * \b Note: The returned object is deleted by the framework.
845 * @param dtID data type ID of the file
846 * @param dtOrigin data type origin of the file
847 * @param spec data specification
848 * @param capacity fraction of the available output buffer size
849 * @return file handle, NULL if failed
851 AliHLTMemoryFile* CreateMemoryFile(const char* dtID, const char* dtOrigin,
852 AliHLTUInt32_t spec=kAliHLTVoidDataSpec,
856 * Create a memory file in the output stream.
857 * This method creates a TFile object which stores all data in
858 * memory instead of disk. The TFile object is published as binary data.
859 * The instance can be used like a normal TFile object. The TFile::Close
860 * or @ref CloseMemoryFile method has to be called in order to flush the
863 * \b Note: The returned object is deleted by the framework.
864 * @param dt data type of the file
865 * @param spec data specification
866 * @param capacity fraction of the available output buffer size
867 * @return file handle, NULL if failed
869 AliHLTMemoryFile* CreateMemoryFile(const AliHLTComponentDataType& dt=kAliHLTAnyDataType,
870 AliHLTUInt32_t spec=kAliHLTVoidDataSpec,
874 * Write an object to memory file in the output stream.
875 * @param pFile file handle
876 * @param pObject pointer to root object
877 * @param key key in ROOT file
878 * @param option options, see TObject::Write
879 * @return neg. error code if failed
880 * - -ENOSPC no space left
882 int Write(AliHLTMemoryFile* pFile, const TObject* pObject, const char* key=NULL, int option=TObject::kOverwrite);
885 * Close object memory file.
886 * @param pFile file handle
887 * @return neg. error code if failed
888 * - -ENOSPC buffer size too small
890 int CloseMemoryFile(AliHLTMemoryFile* pFile);
893 * Insert event-done data information into the output.
894 * @param edd event-done data information
896 int CreateEventDoneData(AliHLTComponentEventDoneData edd);
899 * Get current run number
901 AliHLTUInt32_t GetRunNo() const;
904 * Get the current run type.
906 AliHLTUInt32_t GetRunType() const;
909 * Copy a struct from block data.
910 * The function checks for block size and struct size. The least common
911 * size will be copied to the target struct, remaining fields are initialized
913 * The target struct must have a 32bit struct size indicator as first member.
914 * @param pStruct target struct
915 * @param iStructSize size of the struct
916 * @param iBlockNo index of input block
917 * @param structname name of the struct (log messages)
918 * @param eventname name of the event (log messages)
919 * @return size copied, neg. error if failed
921 int CopyStruct(void* pStruct, unsigned int iStructSize, unsigned int iBlockNo,
922 const char* structname="", const char* eventname="");
925 /** copy constructor prohibited */
926 AliHLTComponent(const AliHLTComponent&);
927 /** assignment operator prohibited */
928 AliHLTComponent& operator=(const AliHLTComponent&);
931 * Increment the internal event counter.
932 * To be used by the friend classes AliHLTProcessor, AliHLTDataSource
933 * and AliHLTDataSink.
934 * @return new value of the internal event counter
937 int IncrementEventCounter();
940 * Find the first input block of specified data type beginning at index.
941 * Input blocks containing a TObject have the size of the object as an
942 * unsigned 32 bit number in the first 4 bytes. This has to match the block
944 * @param dt data type
945 * @param startIdx index to start the search
946 * @param bObject check if this is an object
947 * @return index of the block, -ENOENT if no block found
951 int FindInputBlock(const AliHLTComponentDataType& dt, int startIdx=-1, int bObject=0) const;
954 * Get index in the array of input bocks.
955 * Calculate index and check integrety of a block data structure pointer.
956 * @param pBlock pointer to block data
957 * @return index of the block, -ENOENT if no block found
961 int FindInputBlock(const AliHLTComponentBlockData* pBlock) const;
964 * Create an object from a specified input block.
965 * @param idx index of the input block
966 * @param bForce force the retrieval of an object, error messages
967 * are suppressed if \em bForce is not set
968 * @return pointer to TObject, caller must delete the object after use
972 TObject* CreateInputObject(int idx, int bForce=0);
976 * Get object from the input block list. The methods first checks whether the
977 * object was already created. If not, it is created by @ref CreateInputObject
978 * and inserted into the list of objects.
979 * @param idx index in the input block list
980 * @param classname name of the class, object is checked for correct class
982 * @param bForce force the retrieval of an object, error messages
983 * are suppressed if \em bForce is not set
984 * @return pointer to TObject
988 TObject* GetInputObject(int idx, const char* classname=NULL, int bForce=0);
991 * Clean the list of input objects.
992 * Cleanup is done at the end of each event processing.
994 int CleanupInputObjects();
997 * Insert a buffer into the output block stream.
998 * This is the only method to insert blocks into the output stream, called
999 * from all types of the Pushback method. The actual data might have been
1000 * written to the output buffer already. In that case NULL can be provided
1001 * as buffer, only the block descriptor will be build. If a header is specified,
1002 * it will be inserted before the buffer, default is no header.
1003 * @param pBuffer pointer to buffer
1004 * @param iBufferSize size of the buffer in byte
1005 * @param dt data type
1006 * @param spec data specification
1007 * @param pHeader pointer to header
1008 * @param iHeaderSize size of Header
1009 * @return neg. error code if failed
1011 int InsertOutputBlock(void* pBuffer, int iBufferSize,
1012 const AliHLTComponentDataType& dt,
1013 AliHLTUInt32_t spec,
1014 void* pHeader=NULL, int iHeaderSize=0);
1016 /** The global component handler instance */
1017 static AliHLTComponentHandler* fgpComponentHandler; //! transient
1019 /** The environment where the component is running in */
1020 AliHLTComponentEnvironment fEnvironment; // see above
1022 /** Set by ProcessEvent before the processing starts */
1023 AliHLTEventID_t fCurrentEvent; // see above
1025 /** internal event no */
1026 int fEventCount; // see above
1028 /** the number of failed events */
1029 int fFailedEvents; // see above
1031 /** event data struct of the current event under processing */
1032 AliHLTComponentEventData fCurrentEventData; // see above
1034 /** array of input data blocks of the current event */
1035 const AliHLTComponentBlockData* fpInputBlocks; //! transient
1037 /** index of the current input block */
1038 int fCurrentInputBlock; // see above
1040 /** data type of the last block search */
1041 AliHLTComponentDataType fSearchDataType; // see above
1043 /** name of the class for the object to search for */
1044 string fClassName; // see above
1046 /** array of generated input objects */
1047 TObjArray* fpInputObjects; //! transient
1049 /** the output buffer */
1050 AliHLTUInt8_t* fpOutputBuffer; //! transient
1052 /** size of the output buffer */
1053 AliHLTUInt32_t fOutputBufferSize; // see above
1055 /** size of data written to output buffer */
1056 AliHLTUInt32_t fOutputBufferFilled; // see above
1058 /** list of ouput block data descriptors */
1059 vector<AliHLTComponentBlockData> fOutputBlocks; // see above
1061 /** stopwatch array */
1062 TObjArray* fpStopwatches; //! transient
1064 /** array of memory files AliHLTMemoryFile */
1065 vector<AliHLTMemoryFile*> fMemFiles; //! transient
1067 /** descriptor of the current run */
1068 AliHLTRunDesc* fpRunDesc; //! transient
1070 /** the current DDL list */
1071 AliHLTEventDDL* fpDDLList; //! transient
1073 ClassDef(AliHLTComponent, 3)