HLT sample applications
[u/mrichter/AliRoot.git] / HLT / BASE / AliHLTComponent.h
CommitLineData
a655eae3 1//-*- Mode: C++ -*-
f23a6e1a 2// @(#) $Id$
3
4#ifndef ALIHLTCOMPONENT_H
5#define ALIHLTCOMPONENT_H
6/* Copyright(c) 1998-1999, ALICE Experiment at CERN, All rights reserved. *
7 * See cxx source for full Copyright notice */
8
bfccbf68 9/** @file AliHLTComponent.h
10 @author Matthias Richter, Timm Steinbeck
11 @date
b22e91eb 12 @brief Base class declaration for HLT components.
13 @note The class is both used in Online (PubSub) and Offline (AliRoot)
14 context
15 */
16/**
17 * @defgroup alihlt_component Component handling of the HLT module
18 * This section describes the the component handling for the HLT module.
19 */
8ede8717 20
21#include <vector>
9ce4bf4a 22#include <string>
5ec8e281 23#include "AliHLTLogging.h"
f23a6e1a 24#include "AliHLTDataTypes.h"
71d7c760 25#include "AliHLTDefinitions.h"
f23a6e1a 26
2d7ff710 27/* Matthias Dec 2006
28 * The names have been changed for Aliroot's coding conventions sake
29 * The old names are defined for backward compatibility with the
30 * stand alone SampleLib package
31 */
32typedef AliHLTComponentLogSeverity AliHLTComponent_LogSeverity;
33typedef AliHLTComponentEventData AliHLTComponent_EventData;
34typedef AliHLTComponentShmData AliHLTComponent_ShmData;
35typedef AliHLTComponentDataType AliHLTComponent_DataType;
36typedef AliHLTComponentBlockData AliHLTComponent_BlockData;
37typedef AliHLTComponentTriggerData AliHLTComponent_TriggerData;
38typedef AliHLTComponentEventDoneData AliHLTComponent_EventDoneData;
39
f23a6e1a 40class AliHLTComponentHandler;
a655eae3 41class TObjArray;
90ebac25 42class TStopwatch;
f23a6e1a 43
bfccbf68 44/**
45 * @class AliHLTComponent
46 * Base class of HLT data processing components.
47 * The class provides a common interface for HLT data processing components.
48 * The interface can be accessed from the online HLT framework or the AliRoot
49 * offline analysis framework.
a655eae3 50 * @section alihltcomponent-properties Component identification and properties
51 * Each component must provide a unique ID, input and output data type indications,
52 * and a spawn function.
53 * @subsection alihltcomponent-req-methods Required property methods
54 * - @ref GetComponentID
55 * - @ref GetInputDataTypes (see @ref alihltcomponent-type for default
56 * implementations.)
57 * - @ref GetOutputDataType (see @ref alihltcomponent-type for default
58 * implementations.)
59 * - @ref GetOutputDataSize (see @ref alihltcomponent-type for default
60 * implementations.)
61 * - @ref Spawn
bfccbf68 62 *
a655eae3 63 * @subsection alihltcomponent-opt-mehods Optional handlers
64 * - @ref DoInit
65 * - @ref DoDeinit
66 *
67 * @subsection alihltcomponent-processing-mehods Data processing
68 *
69 *
70 * @subsection alihltcomponent-type Component type
71 * Components can be of type
90ebac25 72 * - @ref kSource components which only produce data
73 * - @ref kProcessor components which consume and produce data
74 * - @ref kSink components which only consume data
a655eae3 75 *
76 * where data production and consumption refer to the analysis data stream. In
77 * order to indicate the type, a child component can overload the
78 * @ref GetComponentType function.
79 * @subsubsection alihltcomponent-type-std Standard implementations
80 * Components in general do not need to implement this function, standard
81 * implementations of the 3 types are available:
82 * - AliHLTDataSource for components of type @ref kSource <br>
83 * All types of data sources can inherit from AliHLTDataSource and must
84 * implement the @ref AliHLTDataSource::GetEvent method. The class
85 * also implements a standard method for @ref GetInputDataTypes.
86 *
87 * - AliHLTProcessor for components of type @ref kProcessor <br>
88 * All types of data processors can inherit from AliHLTDataSource and must
89 * implement the @ref AliHLTProcessor::DoEvent method.
90 *
91 * - AliHLTDataSink for components of type @ref kSink <br>
92 * All types of data processors can inherit from AliHLTDataSource and must
93 * implement the @ref AliHLTDataSink::DumpEvent method. The class
94 * also implements a standard method for @ref GetOutputDataType and @ref
95 * GetOutputDataSize.
96 *
97 * @subsection alihltcomponent-environment Running environment
bfccbf68 98 *
99 * In order to adapt to different environments (on-line/off-line), the component
100 * gets an environment structure with function pointers. The base class provides
101 * member functions for those environment dependend functions. The member
102 * functions are used by the component implementation and are re-mapped to the
103 * corresponding functions.
a655eae3 104 * @section alihltcomponent-interfaces Component interfaces
105 * Each of the 3 standard component base classes AliHLTProcessor, AliHLTDataSource
106 * and AliHLTDataSink provides it's own processing method (see
107 * @ref alihltcomponent-type-std), which splits into a high and a low-level
108 * method. For the @ref alihltcomponent-low-level-interface, all parameters are
109 * shipped as function arguments, the component is supposed to dump data to the
110 * output buffer and handle all block descriptors.
111 * The @ref alihltcomponent-high-level-interface is the standard processing
112 * method and will be used whenever the low-level method is not overloaded.
113 *
114 * @subsection alihltcomponent-high-level-interface High-level interface
115 * The high-level component interface provides functionality to exchange ROOT
116 * structures between components. In contrast to the
117 * @ref alihltcomponent-low-level-interface, a couple of functions can be used
118 * to access data blocks of the input stream
119 * and send data blocks or ROOT TObject's to the output stream. The functionality
120 * is hidden from the user and is implemented by using ROOT's TMessage class.
121 *
122 * @subsubsection alihltcomponent-high-level-int-methods Interface methods
123 * The interface provides a couple of methods in order to get objects from the
124 * input, data blocks (non TObject) from the input, and to push back objects and
125 * data blocks to the output. For convenience there are several functions of
126 * identical name (and similar behavior) with different parameters defined.
127 * Please refer to the function documentation.
128 * - @ref GetNumberOfInputBlocks <br>
129 * return the number of data blocks in the input stream
130 * - @ref GetFirstInputObject <br>
131 * get the first object of a specific data type
132 * - @ref GetNextInputObject <br>
133 * get the next object of same data type as last GetFirstInputObject/Block call
134 * - @ref GetFirstInputBlock <br>
135 * get the first block of a specific data type
136 * - @ref GetNextInputBlock <br>
137 * get the next block of same data type as last GetFirstInputBlock/Block call
138 * - @ref PushBack <br>
139 * insert an object or data buffer into the output
140 * - @ref CreateEventDoneData <br>
141 * add event information to the output
142 *
143 * In addition, the processing methods are simplified a bit by cutting out most of
144 * the parameters. The component implementation
145 * @see AliHLTProcessor AliHLTDataSource AliHLTDataSink
146 *
8451168b 147 * \em IMPORTANT: objects and block descriptors provided by the high-level interface
148 * <b>MUST NOT BE DELETED</b> by the caller.
149 *
a655eae3 150 * @subsubsection alihltcomponent-high-level-int-guidelines High-level interface guidelines
151 * - Structures must inherit from the ROOT object base class TObject in order be
152 * transported by the transportation framework.
153 * - all pointer members must be transient (marked <tt>//!</tt> behind the member
154 * definition), i.e. will not be stored/transported, or properly marked
155 * (<tt>//-></tt>) in order to call the streamer of the object the member is pointing
156 * to. The latter is not recomended. Structures to be transported between components
157 * should be streamlined.
158 * - no use of stl vectors/strings, use appropriate ROOT classes instead
159 *
160 * @subsection alihltcomponent-low-level-interface Low-level interface
161 * The low-level component interface consists of the specific data processing
162 * methods for @ref AliHLTProcessor, @ref AliHLTDataSource, and @ref AliHLTDataSink.
163 * - @ref AliHLTProcessor::DoEvent
164 * - @ref AliHLTDataSource::GetEvent
165 * - @ref AliHLTDataSink::DumpEvent
166 *
167 *
168 * @section alihltcomponent-handling Component handling
169 * The handling of HLT analysis components is carried out by the AliHLTComponentHandler.
170 * Component are registered automatically at load-time of the component shared library
171 * under the following suppositions:
172 * - the component library has to be loaded from the AliHLTComponentHandler using the
173 * @ref AliHLTComponentHandler::LoadLibrary method.
174 * - the component implementation defines one global object (which is generated
175 * when the library is loaded)
176 *
177 * @subsection alihltcomponent-design-rules General design considerations
178 * The analysis code should be implemented in one or more destict class(es). A
179 * \em component should be implemented which interface the destict analysis code to the
180 * component interface. This component generates the analysis object dynamically. <br>
181 *
182 * Assume you have an implemetation <tt> AliHLTDetMyAnalysis </tt>, another class <tt>
183 * AliHLTDetMyAnalysisComponent </tt> contains:
184 * <pre>
185 * private:
186 * AliHLTDetMyAnalysis* fMyAnalysis; //!
187 * </pre>
188 * The object should then be instantiated in the DoInit handler of
189 * <tt>AliHLTDetMyAnalysisComponent </tt>, and cleaned in the DoDeinit handler.
190 *
191 * Further rules:
192 * - avoid big static arrays in the component, allocate the memory at runtime
193 *
b22e91eb 194 * @ingroup alihlt_component
a655eae3 195 * @section alihltcomponent-members Class members
bfccbf68 196 */
5ec8e281 197class AliHLTComponent : public AliHLTLogging {
f23a6e1a 198 public:
bfccbf68 199 /** standard constructor */
f23a6e1a 200 AliHLTComponent();
70ed7d01 201 /** not a valid copy constructor, defined according to effective C++ style */
202 AliHLTComponent(const AliHLTComponent&);
203 /** not a valid assignment op, but defined according to effective C++ style */
204 AliHLTComponent& operator=(const AliHLTComponent&);
bfccbf68 205 /** standard destructor */
f23a6e1a 206 virtual ~AliHLTComponent();
207
bfccbf68 208 /** component type definitions */
f23a6e1a 209 enum TComponentType { kUnknown=0, kSource=1, kProcessor=2, kSink=3 };
bfccbf68 210
211 /**
212 * Init function to prepare data processing.
213 * Initialization of common data structures for a sequence of events.
214 * The call is redirected to the internal method @ref DoInit which can be
215 * overridden by the child class.<br>
216 * During Init also the environment structure is passed to the component.
217 * @param environ environment pointer with environment dependend function
218 * calls
70ed7d01 219 * @param environParam additionel parameter for function calls, the pointer
bfccbf68 220 * is passed as it is
221 * @param argc size of the argument array
222 * @param argv agument array for component initialization
223 */
70ed7d01 224 virtual int Init( AliHLTComponentEnvironment* environ, void* environParam, int argc, const char** argv );
bfccbf68 225
226 /**
227 * Clean-up function to terminate data processing.
228 * Clean-up of common data structures after data processing.
229 * The call is redirected to the internal method @ref DoDeinit which can be
230 * overridden by the child class.
231 */
f23a6e1a 232 virtual int Deinit();
bfccbf68 233
234 /**
235 * Processing of one event.
3cde846d 236 * The method is the entrance of the event processing. The parameters are
237 * cached for uses with the high-level interface and the DoProcessing
238 * implementation is called.
239 *
240 * @param evtData
241 * @param blocks
242 * @param trigData
243 * @param outputPtr
244 * @param size
245 * @param outputBlockCnt out: size of the output block array, set by the component
246 * @param outputBlocks out: the output block array is allocated internally
247 * @param edd
248 * @return neg. error code if failed
249 */
250 int ProcessEvent( const AliHLTComponentEventData& evtData, const AliHLTComponentBlockData* blocks,
251 AliHLTComponentTriggerData& trigData, AliHLTUInt8_t* outputPtr,
252 AliHLTUInt32_t& size, AliHLTUInt32_t& outputBlockCnt,
253 AliHLTComponentBlockData*& outputBlocks,
254 AliHLTComponentEventDoneData*& edd );
255
256 /**
257 * Internal processing of one event.
bfccbf68 258 * The method is pure virtual and implemented by the child classes
259 * - @ref AliHLTProcessor
260 * - @ref AliHLTDataSource
261 * - @ref AliHLTDataSink
262 *
263 * @param evtData
264 * @param blocks
265 * @param trigData
266 * @param outputPtr
267 * @param size
2d7ff710 268 * @param outputBlocks out: the output block array is allocated internally
bfccbf68 269 * @param edd
270 * @return neg. error code if failed
271 */
3cde846d 272 virtual int DoProcessing( const AliHLTComponentEventData& evtData, const AliHLTComponentBlockData* blocks,
8ede8717 273 AliHLTComponentTriggerData& trigData, AliHLTUInt8_t* outputPtr,
a655eae3 274 AliHLTUInt32_t& size,
275 vector<AliHLTComponentBlockData>& outputBlocks,
8ede8717 276 AliHLTComponentEventDoneData*& edd ) = 0;
f23a6e1a 277
278 // Information member functions for registration.
bfccbf68 279
280 /**
281 * Get the type of the component.
282 * The function is pure virtual and must be implemented by the child class.
283 * @return component type id
284 */
f23a6e1a 285 virtual TComponentType GetComponentType() = 0; // Source, sink, or processor
bfccbf68 286
287 /**
288 * Get the id of the component.
289 * Each component is identified by a unique id.
290 * The function is pure virtual and must be implemented by the child class.
291 * @return component id (string)
292 */
f23a6e1a 293 virtual const char* GetComponentID() = 0;
bfccbf68 294
295 /**
296 * Get the input data types of the component.
297 * The function is pure virtual and must be implemented by the child class.
298 * @return list of data types in the vector reference
299 */
8ede8717 300 virtual void GetInputDataTypes( vector<AliHLTComponentDataType>& ) = 0;
bfccbf68 301
302 /**
303 * Get the output data type of the component.
304 * The function is pure virtual and must be implemented by the child class.
305 * @return output data type
306 */
8ede8717 307 virtual AliHLTComponentDataType GetOutputDataType() = 0;
bfccbf68 308
309 /**
310 * Get a ratio by how much the data volume is shrinked or enhanced.
311 * The function is pure virtual and must be implemented by the child class.
312 * @param constBase <i>return</i>: additive part, independent of the
313 * input data volume
314 * @param inputMultiplier <i>return</i>: multiplication ratio
315 * @return values in the reference variables
316 */
71d7c760 317 virtual void GetOutputDataSize( unsigned long& constBase, double& inputMultiplier ) = 0;
f23a6e1a 318
bfccbf68 319 /**
320 * Spawn function.
321 * Each component must implement a spawn function to create a new instance of
322 * the class. Basically the function must return <i>new <b>my_class_name</b></i>.
323 * @return new class instance
324 */
f23a6e1a 325 virtual AliHLTComponent* Spawn() = 0;
0c0c9d99 326
bfccbf68 327 /**
328 * Find matching data types between this component and a consumer component.
329 * Currently, a component can produce only one type of data. This restriction is most
330 * likely to be abolished in the future.
331 * @param pConsumer a component and consumer of the data produced by this component
332 * @param tgtList reference to a vector list to receive the matching data types.
333 * @return >= 0 success, neg. error code if failed
334 */
8ede8717 335 int FindMatchingDataTypes(AliHLTComponent* pConsumer, vector<AliHLTComponentDataType>* tgtList);
f23a6e1a 336
bfccbf68 337 /**
338 * Set the global component handler.
339 * The static method is needed for the automatic registration of components.
340 */
85869391 341 static int SetGlobalComponentHandler(AliHLTComponentHandler* pCH, int bOverwrite=0);
bfccbf68 342
343 /**
344 * Clear the global component handler.
345 * The static method is needed for the automatic registration of components.
346 */
85869391 347 static int UnsetGlobalComponentHandler();
bfccbf68 348
9ce4bf4a 349 /**
350 * Helper function to convert the data type to a string.
351 */
352 static string DataType2Text( const AliHLTComponentDataType& type );
353
354 /**
5f5b708b 355 * Helper function to print content of data type.
356 */
357 void PrintDataTypeContent(AliHLTComponentDataType& dt, const char* format=NULL) const;
358
359 /**
9ce4bf4a 360 * helper function to initialize AliHLTComponentEventData structure
361 */
362 static void FillEventData(AliHLTComponentEventData& evtData);
363
364 /**
365 * Print info on an AliHLTComponentDataType structure
366 * This is just a helper function to examine an @ref AliHLTComponentDataType
367 * structur.
368 */
369 void PrintComponentDataTypeInfo(const AliHLTComponentDataType& dt);
370
90ebac25 371 /**
372 * Stopwatch type for benchmarking.
373 */
374 enum AliHLTStopwatchType {
375 /** total time for event processing */
376 kSWBase,
377 /** detector algorithm w/o interface callbacks */
378 kSWDA,
379 /** data sources */
380 kSWInput,
381 /** data sinks */
382 kSWOutput,
383 /** number of types */
384 kSWTypeCount
385 };
386
387 /**
388 * Helper class for starting and stopping a stopwatch.
389 * The guard can be used by instantiating an object in a function. The
390 * specified stopwatch is started and the previous stopwatch put on
391 * hold. When the function is terminated, the object is deleted automatically
392 * deleted, stopping the stopwatch and starting the one on hold.<br>
393 * \em IMPORTANT: never create dynamic objects from this guard as this violates
394 * the idea of a guard.
395 */
396 class AliHLTStopwatchGuard {
397 public:
398 /** standard constructor (not for use) */
399 AliHLTStopwatchGuard();
400 /** constructor */
401 AliHLTStopwatchGuard(TStopwatch* pStart);
402 /** copy constructor (not for use) */
403 AliHLTStopwatchGuard(AliHLTStopwatchGuard&);
404 /** destructor */
405 ~AliHLTStopwatchGuard();
406
407 private:
408 /**
409 * Hold the previous guard for the existence of this guard.
410 * Checks whether this guard controls a new stopwatch. In that case, the
411 * previous guard and its stopwatch are put on hold.
412 * @param pSucc instance of the stopwatch of the new guard
413 * @return 1 if pSucc is a different stopwatch which should
414 * be started<br>
415 * 0 if it controls the same stopwatch
416 */
417 int Hold(TStopwatch* pSucc);
418
419 /**
420 * Resume the previous guard.
421 * Checks whether the peceeding guard controls a different stopwatch. In that
422 * case, the its stopwatch is resumed.
423 * @param pSucc instance of the stopwatch of the new guard
424 * @return 1 if pSucc is a different stopwatch which should
425 * be stopped<br>
426 * 0 if it controls the same stopwatch
427 */
428 int Resume(TStopwatch* pSucc);
429
430 /** the stopwatch controlled by this guard */
431 TStopwatch* fpStopwatch; //!transient
432
433 /** previous stopwatch guard, put on hold during existence of the guard */
434 AliHLTStopwatchGuard* fpPrec; //!transient
435
436 /** active stopwatch guard */
437 static AliHLTStopwatchGuard* fgpCurrent; //!transient
438 };
439
440 /**
441 * Set a stopwatch for a given purpose.
442 * @param pSW stopwatch object
443 * @param type type of the stopwatch
444 */
445 int SetStopwatch(TObject* pSW, AliHLTStopwatchType type=kSWBase);
446
447 /**
448 * Init a set of stopwatches.
449 * @param pStopwatches object array of stopwatches
450 */
451 int SetStopwatches(TObjArray* pStopwatches);
a655eae3 452
f23a6e1a 453 protected:
71d7c760 454
bfccbf68 455 /**
8ede8717 456 * Fill AliHLTComponentBlockData structure with default values.
bfccbf68 457 * @param blockData reference to data structure
458 */
70ed7d01 459 void FillBlockData( AliHLTComponentBlockData& blockData ) const;
bfccbf68 460
461 /**
8ede8717 462 * Fill AliHLTComponentShmData structure with default values.
bfccbf68 463 * @param shmData reference to data structure
464 */
70ed7d01 465 void FillShmData( AliHLTComponentShmData& shmData ) const;
bfccbf68 466
467 /**
8ede8717 468 * Fill AliHLTComponentDataType structure with default values.
bfccbf68 469 * @param dataType reference to data structure
470 */
70ed7d01 471 void FillDataType( AliHLTComponentDataType& dataType ) const;
f23a6e1a 472
bfccbf68 473 /**
2d7ff710 474 * Copy data type structure
475 * Copies the value an AliHLTComponentDataType structure to another one
476 * @param[out] tgtdt target structure
477 * @param[in] srcdt source structure
478 */
479 void CopyDataType(AliHLTComponentDataType& tgtdt, const AliHLTComponentDataType& srcdt);
480
481 /**
482 * Set the ID and Origin of an AliHLTComponentDataType structure.
483 * The function sets the fStructureSize member and copies the strings
484 * to the ID and Origin. Only characters from the valid part of the string
485 * are copied, the rest is fille with 0's.
486 * Please note that the fID and fOrigin members are not strings, just arrays of
487 * chars of size @ref kAliHLTComponentDataTypefIDsize and
21745ddc 488 * @ref kAliHLTComponentDataTypefOriginSize respectively and not necessarily with
2d7ff710 489 * a terminating zero.
9ce4bf4a 490 * @param tgtdt target data type structure
2d7ff710 491 * @param id ID string
492 * @param origin Origin string
493 */
494 void SetDataType(AliHLTComponentDataType& tgtdt, const char* id, const char* origin);
495
496 /**
bfccbf68 497 * Default method for the internal initialization.
498 * The method is called by @ref Init
499 */
53feaef5 500 virtual int DoInit( int argc, const char** argv );
f23a6e1a 501
bfccbf68 502 /**
503 * Default method for the internal clean-up.
504 * The method is called by @ref Deinit
505 */
53feaef5 506 virtual int DoDeinit();
f23a6e1a 507
bfccbf68 508 /**
509 * General memory allocation method.
510 * All memory which is going to be used 'outside' of the interface must
511 * be provided by the framework (online or offline).
512 * The method is redirected to a function provided by the current
513 * framework. Function pointers are transferred via the @ref
514 * AliHLTComponentEnvironment structure.
515 */
85869391 516 void* AllocMemory( unsigned long size );
f23a6e1a 517
bfccbf68 518 /**
519 * Helper function to create a monolithic BlockData description block out
520 * of a list BlockData descriptors.
521 * For convenience, inside the interface vector lists are used, to make the
522 * interface pure C style, monilithic blocks must be exchanged.
523 * The method is redirected to a function provided by the current
524 * framework. Function pointers are transferred via the @ref
525 * AliHLTComponentEnvironment structure.
526 */
8ede8717 527 int MakeOutputDataBlockList( const vector<AliHLTComponentBlockData>& blocks, AliHLTUInt32_t* blockCount,
528 AliHLTComponentBlockData** outputBlocks );
f23a6e1a 529
bfccbf68 530 /**
531 * Fill the EventDoneData structure.
532 * The method is redirected to a function provided by the current
533 * framework. Function pointers are transferred via the @ref
534 * AliHLTComponentEnvironment structure.
535 */
8ede8717 536 int GetEventDoneData( unsigned long size, AliHLTComponentEventDoneData** edd );
f23a6e1a 537
bfccbf68 538 /**
539 * Helper function to convert the data type to a string.
540 */
70ed7d01 541 void DataType2Text(const AliHLTComponentDataType& type, char output[kAliHLTComponentDataTypefIDsize+kAliHLTComponentDataTypefOriginSize+2]) const;
fa2e9b7c 542
3cde846d 543 /**
544 * Get event number.
545 * @return value of the internal event counter
546 */
70ed7d01 547 int GetEventCount() const;
3cde846d 548
a655eae3 549 /**
550 * Get the number of input blocks.
551 * @return number of input blocks
552 */
553 int GetNumberOfInputBlocks();
554
555 /**
556 * Get the first object of a specific data type from the input data.
557 * The hight-level methods provide functionality to transfer ROOT data
558 * structures which inherit from TObject.
559 * The method looks for the first ROOT object of type dt in the input stream.
560 * If also the class name is provided, the object is checked for the right
561 * class type. The input data block needs a certain structure, namely the
562 * buffer size as first word. If the cross check fails, the retrieval is
8451168b 563 * silently abondoned, unless the \em bForce parameter is set.<br>
564 * \em Note: THE OBJECT MUST NOT BE DELETED by the caller.
a655eae3 565 * @param dt data type of the object
566 * @param classname class name of the object
567 * @param bForce force the retrieval of an object, error messages
568 * are suppressed if \em bForce is not set
569 * @return pointer to @ref TObject, NULL if no objects of specified type
570 * available
571 */
572 const TObject* GetFirstInputObject(const AliHLTComponentDataType& dt=kAliHLTAnyDataType,
573 const char* classname=NULL,
574 int bForce=0);
575
576 /**
577 * Get the first object of a specific data type from the input data.
578 * The hight-level methods provide functionality to transfer ROOT data
579 * structures which inherit from TObject.
580 * The method looks for the first ROOT object of type specified by the ID and
581 * Origin strings in the input stream.
582 * If also the class name is provided, the object is checked for the right
583 * class type. The input data block needs a certain structure, namely the
584 * buffer size as first word. If the cross check fails, the retrieval is
8451168b 585 * silently abondoned, unless the \em bForce parameter is set.<br>
586 * \em Note: THE OBJECT MUST NOT BE DELETED by the caller.
a655eae3 587 * @param dtID data type ID of the object
588 * @param dtOrigin data type origin of the object
589 * @param classname class name of the object
590 * @param bForce force the retrieval of an object, error messages
591 * are suppressed if \em bForce is not set
592 * @return pointer to @ref TObject, NULL if no objects of specified type
593 * available
594 */
595 const TObject* GetFirstInputObject(const char* dtID,
596 const char* dtOrigin,
597 const char* classname=NULL,
598 int bForce=0);
599
600 /**
601 * Get the next object of a specific data type from the input data.
602 * The hight-level methods provide functionality to transfer ROOT data
603 * structures which inherit from TObject.
604 * The method looks for the next ROOT object of type and class specified
8451168b 605 * to the previous @ref GetFirstInputObject call.<br>
606 * \em Note: THE OBJECT MUST NOT BE DELETED by the caller.
a655eae3 607 * @param bForce force the retrieval of an object, error messages
608 * are suppressed if \em bForce is not set
609 * @return pointer to @ref TObject, NULL if no more objects available
610 */
611 const TObject* GetNextInputObject(int bForce=0);
612
613 /**
614 * Get data type of an input block.
615 * Get data type of the object previously fetched via
616 * GetFirstInputObject/NextInputObject or the last one if no object
617 * specified.
618 * @param pObject pointer to TObject
619 * @return data specification, kAliHLTVoidDataSpec if failed
620 */
621 AliHLTComponentDataType GetDataType(const TObject* pObject=NULL);
622
623 /**
624 * Get data specification of an input block.
625 * Get data specification of the object previously fetched via
626 * GetFirstInputObject/NextInputObject or the last one if no object
627 * specified.
628 * @param pObject pointer to TObject
629 * @return data specification, kAliHLTVoidDataSpec if failed
630 */
631 AliHLTUInt32_t GetSpecification(const TObject* pObject=NULL);
632
633 /**
634 * Get the first block of a specific data type from the input data.
635 * The method looks for the first block of type dt in the input stream. It is intended
8451168b 636 * to be used within the high-level interface.<br>
637 * \em Note: THE BLOCK DESCRIPTOR MUST NOT BE DELETED by the caller.
a655eae3 638 * @param dt data type of the block
639 * @return pointer to @ref AliHLTComponentBlockData
640 */
641 const AliHLTComponentBlockData* GetFirstInputBlock(const AliHLTComponentDataType& dt=kAliHLTAnyDataType);
642
643 /**
644 * Get the first block of a specific data type from the input data.
645 * The method looks for the first block of type specified by the ID and
646 * Origin strings in the input stream. It is intended
8451168b 647 * to be used within the high-level interface.<br>
648 * \em Note: THE BLOCK DESCRIPTOR MUST NOT BE DELETED by the caller.
a655eae3 649 * @param dtID data type ID of the block
650 * @param dtOrigin data type origin of the block
651 * @return pointer to @ref AliHLTComponentBlockData
652 */
653 const AliHLTComponentBlockData* GetFirstInputBlock(const char* dtID,
654 const char* dtOrigin);
655
656 /**
8451168b 657 * Get input block by index.<br>
658 * \em Note: THE BLOCK DESCRIPTOR MUST NOT BE DELETED by the caller.
a655eae3 659 * @return pointer to AliHLTComponentBlockData, NULL if index out of range
660 */
661 const AliHLTComponentBlockData* GetInputBlock(int index);
662
663 /**
664 * Get the next block of a specific data type from the input data.
665 * The method looks for the next block of type and class specified
666 * to the previous @ref GetFirstInputBlock call.
8451168b 667 * To be used within the high-level interface.<br>
668 * \em Note: THE BLOCK DESCRIPTOR MUST NOT BE DELETED by the caller.
a655eae3 669 */
670 const AliHLTComponentBlockData* GetNextInputBlock();
671
672 /**
673 * Get data specification of an input block.
674 * Get data specification of the input bblock previously fetched via
675 * GetFirstInputObject/NextInputObject or the last one if no block
676 * specified.
677 * @param pBlock pointer to input block
678 * @return data specification, kAliHLTVoidDataSpec if failed
679 */
680 AliHLTUInt32_t GetSpecification(const AliHLTComponentBlockData* pBlock=NULL);
681
682 /**
683 * Insert an object into the output.
684 * @param pObject pointer to root object
685 * @param dt data type of the object
686 * @param spec data specification
687 * @return neg. error code if failed
688 */
689 int PushBack(TObject* pObject, const AliHLTComponentDataType& dt,
690 AliHLTUInt32_t spec=kAliHLTVoidDataSpec);
691
692 /**
693 * Insert an object into the output.
694 * @param pObject pointer to root object
695 * @param dtID data type ID of the object
696 * @param dtOrigin data type origin of the object
697 * @param spec data specification
698 * @return neg. error code if failed
699 */
700 int PushBack(TObject* pObject, const char* dtID, const char* dtOrigin,
701 AliHLTUInt32_t spec=kAliHLTVoidDataSpec);
702
703 /**
704 * Insert an object into the output.
705 * @param pBuffer pointer to buffer
706 * @param iSize size of the buffer
707 * @param dt data type of the object
708 * @param spec data specification
709 * @return neg. error code if failed
710 */
711 int PushBack(void* pBuffer, int iSize, const AliHLTComponentDataType& dt,
712 AliHLTUInt32_t spec=kAliHLTVoidDataSpec);
713
714 /**
715 * Insert an object into the output.
716 * @param pBuffer pointer to buffer
717 * @param iSize size of the buffer
718 * @param dtID data type ID of the object
719 * @param dtOrigin data type origin of the object
720 * @param spec data specification
721 * @return neg. error code if failed
722 */
723 int PushBack(void* pBuffer, int iSize, const char* dtID, const char* dtOrigin,
724 AliHLTUInt32_t spec=kAliHLTVoidDataSpec);
725
726 /**
8451168b 727 * Estimate size of a TObject
728 * @param pObject
729 * @return buffer size in byte
730 */
731 int EstimateObjectSize(TObject* pObject) const;
732
733 /**
a655eae3 734 * Insert event-done data information into the output.
735 * @param edd event-done data information
736 */
737 int CreateEventDoneData(AliHLTComponentEventDoneData edd);
738
f23a6e1a 739 private:
3cde846d 740 /**
741 * Increment the internal event counter.
742 * To be used by the friend classes AliHLTProcessor, AliHLTDataSource
743 * and AliHLTDataSink.
744 * @return new value of the internal event counter
a655eae3 745 * @internal
3cde846d 746 */
747 int IncrementEventCounter();
748
a655eae3 749 /**
750 * Find the first input block of specified data type beginning at index.
751 * @param dt data type
752 * @param startIdx index to start the search
753 * @return index of the block, -ENOENT if no block found
754 *
755 * @internal
756 */
757 int FindInputBlock(const AliHLTComponentDataType& dt, int startIdx=-1);
758
759 /**
760 * Get index in the array of input bocks.
761 * Calculate index and check integrety of a block data structure pointer.
762 * @param pBlock pointer to block data
763 * @return index of the block, -ENOENT if no block found
764 *
765 * @internal
766 */
767 int FindInputBlock(const AliHLTComponentBlockData* pBlock);
768
769 /**
770 * Create an object from a specified input block.
771 * @param idx index of the input block
772 * @param bForce force the retrieval of an object, error messages
773 * are suppressed if \em bForce is not set
774 * @return pointer to TObject, caller must delete the object after use
775 *
776 * @internal
777 */
778 TObject* CreateInputObject(int idx, int bForce=0);
779
780 /**
781 * Get input object
8451168b 782 * Get object from the input block list. The methods first checks whether the
783 * object was already created. If not, it is created by @ref CreateInputObject
784 * and inserted into the list of objects.
a655eae3 785 * @param idx index in the input block list
786 * @param classname name of the class, object is checked for correct class
787 * name if set
788 * @param bForce force the retrieval of an object, error messages
789 * are suppressed if \em bForce is not set
790 * @return pointer to TObject
791 *
792 * @internal
793 */
794 TObject* GetInputObject(int idx, const char* classname=NULL, int bForce=0);
795
796 /**
8451168b 797 * Clean the list of input objects.
798 * Cleanup is done at the end of each event processing.
799 */
800 int CleanupInputObjects();
801
802 /**
a655eae3 803 * Insert a buffer into the output block stream.
804 * This is the only method to insert blocks into the output stream, called
805 * from all types of the Pushback method. The actual data might have been
806 * written to the output buffer already. In that case NULL can be provided
807 * as buffer, only the block descriptor will be build.
808 * @param pBuffer pointer to buffer
809 * @param iSize size of the buffer in byte
810 * @param dt data type
811 * @param spec data specification
812 */
813 int InsertOutputBlock(void* pBuffer, int iSize,
814 const AliHLTComponentDataType& dt,
815 AliHLTUInt32_t spec);
816
817
bfccbf68 818 /** The global component handler instance */
a655eae3 819 static AliHLTComponentHandler* fgpComponentHandler; //! transient
70ed7d01 820
bfccbf68 821 /** The environment where the component is running in */
a655eae3 822 AliHLTComponentEnvironment fEnvironment; // see above
f23a6e1a 823
a655eae3 824 /** Set by ProcessEvent before the processing starts */
825 AliHLTEventID_t fCurrentEvent; // see above
f23a6e1a 826
3cde846d 827 /** internal event no */
a655eae3 828 int fEventCount; // see above
829
830 /** the number of failed events */
831 int fFailedEvents; // see above
832
833 /** event data struct of the current event under processing */
834 AliHLTComponentEventData fCurrentEventData; // see above
835
836 /** array of input data blocks of the current event */
837 const AliHLTComponentBlockData* fpInputBlocks; //! transient
838
839 /** index of the current input block */
840 int fCurrentInputBlock; // see above
841
842 /** data type of the last block search */
843 AliHLTComponentDataType fSearchDataType; // see above
844
845 /** name of the class for the object to search for */
846 string fClassName; // see above
847
848 /** array of generated input objects */
849 TObjArray* fpInputObjects; //! transient
850
851 /** the output buffer */
852 AliHLTUInt8_t* fpOutputBuffer; //! transient
853
854 /** size of the output buffer */
855 AliHLTUInt32_t fOutputBufferSize; // see above
856
857 /** size of data written to output buffer */
858 AliHLTUInt32_t fOutputBufferFilled; // see above
859
860 /** list of ouput block data descriptors */
861 vector<AliHLTComponentBlockData> fOutputBlocks; // see above
3cde846d 862
90ebac25 863 /** stopwatch array */
864 TObjArray* fpStopwatches; //! transient
865
866 ClassDef(AliHLTComponent, 2)
f23a6e1a 867};
868#endif