minor correction in documentation
[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
79c114b5 6/* This file is property of and copyright by the ALICE HLT Project *
7 * ALICE Experiment at CERN, All rights reserved. *
f23a6e1a 8 * See cxx source for full Copyright notice */
9
bfccbf68 10/** @file AliHLTComponent.h
11 @author Matthias Richter, Timm Steinbeck
12 @date
b22e91eb 13 @brief Base class declaration for HLT components.
14 @note The class is both used in Online (PubSub) and Offline (AliRoot)
15 context
30338a30 16
17// see below for class documentation
18// or
19// refer to README to build package
20// or
21// visit http://web.ift.uib.no/~kjeks/doc/alice-hlt
b22e91eb 22 */
23/**
24 * @defgroup alihlt_component Component handling of the HLT module
25 * This section describes the the component handling for the HLT module.
26 */
8ede8717 27
28#include <vector>
9ce4bf4a 29#include <string>
5ec8e281 30#include "AliHLTLogging.h"
f23a6e1a 31#include "AliHLTDataTypes.h"
66043029 32//#include "AliHLTDefinitions.h"
f23a6e1a 33
2d7ff710 34/* Matthias Dec 2006
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
38 */
39typedef AliHLTComponentLogSeverity AliHLTComponent_LogSeverity;
40typedef AliHLTComponentEventData AliHLTComponent_EventData;
41typedef AliHLTComponentShmData AliHLTComponent_ShmData;
42typedef AliHLTComponentDataType AliHLTComponent_DataType;
43typedef AliHLTComponentBlockData AliHLTComponent_BlockData;
44typedef AliHLTComponentTriggerData AliHLTComponent_TriggerData;
45typedef AliHLTComponentEventDoneData AliHLTComponent_EventDoneData;
46
f23a6e1a 47class AliHLTComponentHandler;
a655eae3 48class TObjArray;
90ebac25 49class TStopwatch;
79c114b5 50class AliHLTMemoryFile;
f23a6e1a 51
bfccbf68 52/**
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.
a655eae3 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
64 * implementations.)
65 * - @ref GetOutputDataType (see @ref alihltcomponent-type for default
66 * implementations.)
67 * - @ref GetOutputDataSize (see @ref alihltcomponent-type for default
68 * implementations.)
69 * - @ref Spawn
bfccbf68 70 *
a655eae3 71 * @subsection alihltcomponent-opt-mehods Optional handlers
72 * - @ref DoInit
73 * - @ref DoDeinit
de6593d0 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.
a655eae3 78 *
79 * @subsection alihltcomponent-processing-mehods Data processing
80 *
81 *
82 * @subsection alihltcomponent-type Component type
83 * Components can be of type
90ebac25 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
a655eae3 87 *
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.
98 *
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.
102 *
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
107 * GetOutputDataSize.
108 *
109 * @subsection alihltcomponent-environment Running environment
bfccbf68 110 *
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.
b6800be0 116 *
a655eae3 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.
126 *
b6800be0 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
135 * again.
136 *
b426991e 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
142 * <pre>
616eb170 143 * \#include \<cerrno\>
b426991e 144 * </pre>
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
152 *
a655eae3 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.
160 *
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
181 *
182 * In addition, the processing methods are simplified a bit by cutting out most of
79c114b5 183 * the parameters.
184 * @see
185 * - @ref AliHLTProcessor::DoEvent
186 * - @ref AliHLTDataSource::GetEvent
187 * - @ref AliHLTDataSink::DumpEvent
a655eae3 188 *
8451168b 189 * \em IMPORTANT: objects and block descriptors provided by the high-level interface
190 * <b>MUST NOT BE DELETED</b> by the caller.
191 *
a655eae3 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
201 *
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
208 *
209 *
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)
218 *
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>
223 *
224 * Assume you have an implemetation <tt> AliHLTDetMyAnalysis </tt>, another class <tt>
225 * AliHLTDetMyAnalysisComponent </tt> contains:
226 * <pre>
227 * private:
228 * AliHLTDetMyAnalysis* fMyAnalysis; //!
229 * </pre>
230 * The object should then be instantiated in the DoInit handler of
231 * <tt>AliHLTDetMyAnalysisComponent </tt>, and cleaned in the DoDeinit handler.
232 *
233 * Further rules:
234 * - avoid big static arrays in the component, allocate the memory at runtime
235 *
b22e91eb 236 * @ingroup alihlt_component
a655eae3 237 * @section alihltcomponent-members Class members
bfccbf68 238 */
5ec8e281 239class AliHLTComponent : public AliHLTLogging {
f23a6e1a 240 public:
bfccbf68 241 /** standard constructor */
f23a6e1a 242 AliHLTComponent();
bfccbf68 243 /** standard destructor */
f23a6e1a 244 virtual ~AliHLTComponent();
245
bfccbf68 246 /** component type definitions */
f23a6e1a 247 enum TComponentType { kUnknown=0, kSource=1, kProcessor=2, kSink=3 };
bfccbf68 248
249 /**
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
256 * calls
70ed7d01 257 * @param environParam additionel parameter for function calls, the pointer
bfccbf68 258 * is passed as it is
259 * @param argc size of the argument array
260 * @param argv agument array for component initialization
261 */
70ed7d01 262 virtual int Init( AliHLTComponentEnvironment* environ, void* environParam, int argc, const char** argv );
bfccbf68 263
264 /**
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.
269 */
f23a6e1a 270 virtual int Deinit();
bfccbf68 271
272 /**
273 * Processing of one event.
3cde846d 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.
277 *
278 * @param evtData
279 * @param blocks
280 * @param trigData
281 * @param outputPtr
282 * @param size
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
285 * @param edd
286 * @return neg. error code if failed
287 */
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 );
293
294 /**
295 * Internal processing of one event.
bfccbf68 296 * The method is pure virtual and implemented by the child classes
297 * - @ref AliHLTProcessor
298 * - @ref AliHLTDataSource
299 * - @ref AliHLTDataSink
300 *
301 * @param evtData
302 * @param blocks
303 * @param trigData
304 * @param outputPtr
305 * @param size
2d7ff710 306 * @param outputBlocks out: the output block array is allocated internally
bfccbf68 307 * @param edd
308 * @return neg. error code if failed
309 */
3cde846d 310 virtual int DoProcessing( const AliHLTComponentEventData& evtData, const AliHLTComponentBlockData* blocks,
8ede8717 311 AliHLTComponentTriggerData& trigData, AliHLTUInt8_t* outputPtr,
a655eae3 312 AliHLTUInt32_t& size,
313 vector<AliHLTComponentBlockData>& outputBlocks,
8ede8717 314 AliHLTComponentEventDoneData*& edd ) = 0;
f23a6e1a 315
316 // Information member functions for registration.
bfccbf68 317
318 /**
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
322 */
f23a6e1a 323 virtual TComponentType GetComponentType() = 0; // Source, sink, or processor
bfccbf68 324
325 /**
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)
330 */
f23a6e1a 331 virtual const char* GetComponentID() = 0;
bfccbf68 332
333 /**
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
337 */
8ede8717 338 virtual void GetInputDataTypes( vector<AliHLTComponentDataType>& ) = 0;
bfccbf68 339
340 /**
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
344 */
8ede8717 345 virtual AliHLTComponentDataType GetOutputDataType() = 0;
bfccbf68 346
347 /**
de6593d0 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
355 */
356 virtual int GetOutputDataTypes(vector<AliHLTComponentDataType>& tgtList);
357
358 /**
bfccbf68 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
362 * input data volume
363 * @param inputMultiplier <i>return</i>: multiplication ratio
364 * @return values in the reference variables
365 */
71d7c760 366 virtual void GetOutputDataSize( unsigned long& constBase, double& inputMultiplier ) = 0;
f23a6e1a 367
bfccbf68 368 /**
369 * Spawn function.
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
373 */
f23a6e1a 374 virtual AliHLTComponent* Spawn() = 0;
0c0c9d99 375
bfccbf68 376 /**
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
383 */
8ede8717 384 int FindMatchingDataTypes(AliHLTComponent* pConsumer, vector<AliHLTComponentDataType>* tgtList);
f23a6e1a 385
bfccbf68 386 /**
387 * Set the global component handler.
388 * The static method is needed for the automatic registration of components.
389 */
85869391 390 static int SetGlobalComponentHandler(AliHLTComponentHandler* pCH, int bOverwrite=0);
bfccbf68 391
392 /**
393 * Clear the global component handler.
394 * The static method is needed for the automatic registration of components.
395 */
85869391 396 static int UnsetGlobalComponentHandler();
bfccbf68 397
9ce4bf4a 398 /**
399 * Helper function to convert the data type to a string.
400 */
401 static string DataType2Text( const AliHLTComponentDataType& type );
402
403 /**
5f5b708b 404 * Helper function to print content of data type.
405 */
406 void PrintDataTypeContent(AliHLTComponentDataType& dt, const char* format=NULL) const;
407
408 /**
9ce4bf4a 409 * helper function to initialize AliHLTComponentEventData structure
410 */
411 static void FillEventData(AliHLTComponentEventData& evtData);
412
413 /**
414 * Print info on an AliHLTComponentDataType structure
415 * This is just a helper function to examine an @ref AliHLTComponentDataType
416 * structur.
417 */
418 void PrintComponentDataTypeInfo(const AliHLTComponentDataType& dt);
419
90ebac25 420 /**
421 * Stopwatch type for benchmarking.
422 */
423 enum AliHLTStopwatchType {
424 /** total time for event processing */
425 kSWBase,
426 /** detector algorithm w/o interface callbacks */
427 kSWDA,
428 /** data sources */
429 kSWInput,
430 /** data sinks */
431 kSWOutput,
432 /** number of types */
433 kSWTypeCount
434 };
435
436 /**
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.
444 */
445 class AliHLTStopwatchGuard {
446 public:
447 /** standard constructor (not for use) */
448 AliHLTStopwatchGuard();
449 /** constructor */
450 AliHLTStopwatchGuard(TStopwatch* pStart);
451 /** copy constructor (not for use) */
e419b223 452 AliHLTStopwatchGuard(const AliHLTStopwatchGuard&);
453 /** assignment operator (not for use) */
454 AliHLTStopwatchGuard& operator=(const AliHLTStopwatchGuard&);
90ebac25 455 /** destructor */
456 ~AliHLTStopwatchGuard();
457
458 private:
459 /**
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
465 * be started<br>
466 * 0 if it controls the same stopwatch
467 */
468 int Hold(TStopwatch* pSucc);
469
470 /**
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
476 * be stopped<br>
477 * 0 if it controls the same stopwatch
478 */
479 int Resume(TStopwatch* pSucc);
480
481 /** the stopwatch controlled by this guard */
482 TStopwatch* fpStopwatch; //!transient
483
484 /** previous stopwatch guard, put on hold during existence of the guard */
485 AliHLTStopwatchGuard* fpPrec; //!transient
486
487 /** active stopwatch guard */
488 static AliHLTStopwatchGuard* fgpCurrent; //!transient
489 };
490
491 /**
492 * Set a stopwatch for a given purpose.
493 * @param pSW stopwatch object
494 * @param type type of the stopwatch
495 */
496 int SetStopwatch(TObject* pSW, AliHLTStopwatchType type=kSWBase);
497
498 /**
499 * Init a set of stopwatches.
500 * @param pStopwatches object array of stopwatches
501 */
502 int SetStopwatches(TObjArray* pStopwatches);
a655eae3 503
f23a6e1a 504 protected:
71d7c760 505
bfccbf68 506 /**
8ede8717 507 * Fill AliHLTComponentBlockData structure with default values.
bfccbf68 508 * @param blockData reference to data structure
509 */
70ed7d01 510 void FillBlockData( AliHLTComponentBlockData& blockData ) const;
bfccbf68 511
512 /**
8ede8717 513 * Fill AliHLTComponentShmData structure with default values.
bfccbf68 514 * @param shmData reference to data structure
515 */
70ed7d01 516 void FillShmData( AliHLTComponentShmData& shmData ) const;
bfccbf68 517
518 /**
8ede8717 519 * Fill AliHLTComponentDataType structure with default values.
bfccbf68 520 * @param dataType reference to data structure
521 */
70ed7d01 522 void FillDataType( AliHLTComponentDataType& dataType ) const;
f23a6e1a 523
bfccbf68 524 /**
2d7ff710 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
529 */
530 void CopyDataType(AliHLTComponentDataType& tgtdt, const AliHLTComponentDataType& srcdt);
531
532 /**
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
21745ddc 539 * @ref kAliHLTComponentDataTypefOriginSize respectively and not necessarily with
2d7ff710 540 * a terminating zero.
9ce4bf4a 541 * @param tgtdt target data type structure
2d7ff710 542 * @param id ID string
543 * @param origin Origin string
544 */
545 void SetDataType(AliHLTComponentDataType& tgtdt, const char* id, const char* origin);
546
547 /**
bfccbf68 548 * Default method for the internal initialization.
549 * The method is called by @ref Init
550 */
53feaef5 551 virtual int DoInit( int argc, const char** argv );
f23a6e1a 552
bfccbf68 553 /**
554 * Default method for the internal clean-up.
555 * The method is called by @ref Deinit
556 */
53feaef5 557 virtual int DoDeinit();
f23a6e1a 558
bfccbf68 559 /**
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.
566 */
85869391 567 void* AllocMemory( unsigned long size );
f23a6e1a 568
bfccbf68 569 /**
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.
577 */
8ede8717 578 int MakeOutputDataBlockList( const vector<AliHLTComponentBlockData>& blocks, AliHLTUInt32_t* blockCount,
579 AliHLTComponentBlockData** outputBlocks );
f23a6e1a 580
bfccbf68 581 /**
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.
586 */
8ede8717 587 int GetEventDoneData( unsigned long size, AliHLTComponentEventDoneData** edd );
f23a6e1a 588
bfccbf68 589 /**
590 * Helper function to convert the data type to a string.
591 */
70ed7d01 592 void DataType2Text(const AliHLTComponentDataType& type, char output[kAliHLTComponentDataTypefIDsize+kAliHLTComponentDataTypefOriginSize+2]) const;
fa2e9b7c 593
3cde846d 594 /**
595 * Get event number.
596 * @return value of the internal event counter
597 */
70ed7d01 598 int GetEventCount() const;
3cde846d 599
a655eae3 600 /**
601 * Get the number of input blocks.
602 * @return number of input blocks
603 */
66043029 604 int GetNumberOfInputBlocks() const;
a655eae3 605
606 /**
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
8451168b 614 * silently abondoned, unless the \em bForce parameter is set.<br>
615 * \em Note: THE OBJECT MUST NOT BE DELETED by the caller.
a655eae3 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
621 * available
622 */
623 const TObject* GetFirstInputObject(const AliHLTComponentDataType& dt=kAliHLTAnyDataType,
624 const char* classname=NULL,
625 int bForce=0);
626
627 /**
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
8451168b 636 * silently abondoned, unless the \em bForce parameter is set.<br>
637 * \em Note: THE OBJECT MUST NOT BE DELETED by the caller.
a655eae3 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
644 * available
645 */
646 const TObject* GetFirstInputObject(const char* dtID,
647 const char* dtOrigin,
648 const char* classname=NULL,
649 int bForce=0);
650
651 /**
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
8451168b 656 * to the previous @ref GetFirstInputObject call.<br>
657 * \em Note: THE OBJECT MUST NOT BE DELETED by the caller.
a655eae3 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
661 */
662 const TObject* GetNextInputObject(int bForce=0);
663
664 /**
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
668 * specified.
669 * @param pObject pointer to TObject
670 * @return data specification, kAliHLTVoidDataSpec if failed
671 */
672 AliHLTComponentDataType GetDataType(const TObject* pObject=NULL);
673
674 /**
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
678 * specified.
679 * @param pObject pointer to TObject
680 * @return data specification, kAliHLTVoidDataSpec if failed
681 */
682 AliHLTUInt32_t GetSpecification(const TObject* pObject=NULL);
683
684 /**
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
8451168b 687 * to be used within the high-level interface.<br>
688 * \em Note: THE BLOCK DESCRIPTOR MUST NOT BE DELETED by the caller.
a655eae3 689 * @param dt data type of the block
690 * @return pointer to @ref AliHLTComponentBlockData
691 */
692 const AliHLTComponentBlockData* GetFirstInputBlock(const AliHLTComponentDataType& dt=kAliHLTAnyDataType);
693
694 /**
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
8451168b 698 * to be used within the high-level interface.<br>
699 * \em Note: THE BLOCK DESCRIPTOR MUST NOT BE DELETED by the caller.
a655eae3 700 * @param dtID data type ID of the block
701 * @param dtOrigin data type origin of the block
702 * @return pointer to @ref AliHLTComponentBlockData
703 */
704 const AliHLTComponentBlockData* GetFirstInputBlock(const char* dtID,
705 const char* dtOrigin);
706
707 /**
8451168b 708 * Get input block by index.<br>
709 * \em Note: THE BLOCK DESCRIPTOR MUST NOT BE DELETED by the caller.
a655eae3 710 * @return pointer to AliHLTComponentBlockData, NULL if index out of range
711 */
712 const AliHLTComponentBlockData* GetInputBlock(int index);
713
714 /**
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.
8451168b 718 * To be used within the high-level interface.<br>
719 * \em Note: THE BLOCK DESCRIPTOR MUST NOT BE DELETED by the caller.
a655eae3 720 */
721 const AliHLTComponentBlockData* GetNextInputBlock();
722
723 /**
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
727 * specified.
728 * @param pBlock pointer to input block
729 * @return data specification, kAliHLTVoidDataSpec if failed
730 */
731 AliHLTUInt32_t GetSpecification(const AliHLTComponentBlockData* pBlock=NULL);
732
733 /**
734 * Insert an object into the output.
79c114b5 735 * If header is specified, it will be inserted before the root object,
736 * default is no header.
a655eae3 737 * @param pObject pointer to root object
738 * @param dt data type of the object
739 * @param spec data specification
79c114b5 740 * @param pHeader pointer to header
741 * @param headerSize size of Header
a655eae3 742 * @return neg. error code if failed
743 */
744 int PushBack(TObject* pObject, const AliHLTComponentDataType& dt,
79c114b5 745 AliHLTUInt32_t spec=kAliHLTVoidDataSpec,
746 void* pHeader=NULL, int headerSize=0);
a655eae3 747
748 /**
749 * Insert an object into the output.
79c114b5 750 * If header is specified, it will be inserted before the root object,
751 * default is no header.
a655eae3 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
79c114b5 756 * @param pHeader pointer to header
757 * @param headerSize size of Header
a655eae3 758 * @return neg. error code if failed
759 */
760 int PushBack(TObject* pObject, const char* dtID, const char* dtOrigin,
79c114b5 761 AliHLTUInt32_t spec=kAliHLTVoidDataSpec,
762 void* pHeader=NULL, int headerSize=0);
763
a655eae3 764 /**
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
9d9ffd37 770 * @param pHeader pointer to header
7c4091c1 771 * @param headerSize size of Header
a655eae3 772 * @return neg. error code if failed
773 */
774 int PushBack(void* pBuffer, int iSize, const AliHLTComponentDataType& dt,
9d9ffd37 775 AliHLTUInt32_t spec=kAliHLTVoidDataSpec,
776 void* pHeader=NULL, int headerSize=0);
a655eae3 777
778 /**
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
9d9ffd37 785 * @param pHeader pointer to header
7c4091c1 786 * @param headerSize size of Header
a655eae3 787 * @return neg. error code if failed
788 */
789 int PushBack(void* pBuffer, int iSize, const char* dtID, const char* dtOrigin,
9d9ffd37 790 AliHLTUInt32_t spec=kAliHLTVoidDataSpec,
791 void* pHeader=NULL, int headerSize=0);
a655eae3 792
793 /**
8451168b 794 * Estimate size of a TObject
795 * @param pObject
796 * @return buffer size in byte
797 */
798 int EstimateObjectSize(TObject* pObject) const;
799
800 /**
79c114b5 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
806 * output stream.
807 *
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
814 */
815 AliHLTMemoryFile* CreateMemoryFile(int capacity, const char* dtID, const char* dtOrigin,
816 AliHLTUInt32_t spec=kAliHLTVoidDataSpec);
817
818 /**
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
824 * output stream.
825 *
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
831 */
832 AliHLTMemoryFile* CreateMemoryFile(int capacity,
833 const AliHLTComponentDataType& dt=kAliHLTAnyDataType,
834 AliHLTUInt32_t spec=kAliHLTVoidDataSpec);
835
836 /**
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
842 * output stream.
843 *
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
850 */
851 AliHLTMemoryFile* CreateMemoryFile(const char* dtID, const char* dtOrigin,
852 AliHLTUInt32_t spec=kAliHLTVoidDataSpec,
853 float capacity=1.0);
854
855 /**
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
861 * output stream.
862 *
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
868 */
869 AliHLTMemoryFile* CreateMemoryFile(const AliHLTComponentDataType& dt=kAliHLTAnyDataType,
870 AliHLTUInt32_t spec=kAliHLTVoidDataSpec,
871 float capacity=1.0);
872
873 /**
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
881 */
882 int Write(AliHLTMemoryFile* pFile, const TObject* pObject, const char* key=NULL, int option=TObject::kOverwrite);
883
884 /**
885 * Close object memory file.
886 * @param pFile file handle
887 * @return neg. error code if failed
888 * - -ENOSPC buffer size too small
889 */
890 int CloseMemoryFile(AliHLTMemoryFile* pFile);
891
892 /**
a655eae3 893 * Insert event-done data information into the output.
894 * @param edd event-done data information
895 */
896 int CreateEventDoneData(AliHLTComponentEventDoneData edd);
897
559631d5 898 /**
899 * Get current run number
900 */
901 AliHLTUInt32_t GetRunNo() const;
902
903 /**
904 * Get the current run type.
905 */
906 AliHLTUInt32_t GetRunType() const;
907
908 /**
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
912 * to zero.<br>
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
559631d5 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
920 */
83fec083 921 int CopyStruct(void* pStruct, unsigned int iStructSize, unsigned int iBlockNo,
559631d5 922 const char* structname="", const char* eventname="");
923
f23a6e1a 924 private:
b426991e 925 /** copy constructor prohibited */
559631d5 926 AliHLTComponent(const AliHLTComponent&);
b426991e 927 /** assignment operator prohibited */
559631d5 928 AliHLTComponent& operator=(const AliHLTComponent&);
929
3cde846d 930 /**
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
a655eae3 935 * @internal
3cde846d 936 */
937 int IncrementEventCounter();
938
a655eae3 939 /**
940 * Find the first input block of specified data type beginning at index.
1edbbe49 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
943 * size minus 4.
a655eae3 944 * @param dt data type
945 * @param startIdx index to start the search
1edbbe49 946 * @param bObject check if this is an object
a655eae3 947 * @return index of the block, -ENOENT if no block found
948 *
949 * @internal
950 */
1edbbe49 951 int FindInputBlock(const AliHLTComponentDataType& dt, int startIdx=-1, int bObject=0) const;
a655eae3 952
953 /**
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
958 *
959 * @internal
960 */
66043029 961 int FindInputBlock(const AliHLTComponentBlockData* pBlock) const;
a655eae3 962
963 /**
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
969 *
970 * @internal
971 */
972 TObject* CreateInputObject(int idx, int bForce=0);
973
974 /**
975 * Get input object
8451168b 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.
a655eae3 979 * @param idx index in the input block list
980 * @param classname name of the class, object is checked for correct class
981 * name if set
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
985 *
986 * @internal
987 */
988 TObject* GetInputObject(int idx, const char* classname=NULL, int bForce=0);
989
990 /**
8451168b 991 * Clean the list of input objects.
992 * Cleanup is done at the end of each event processing.
993 */
994 int CleanupInputObjects();
995
996 /**
a655eae3 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
79c114b5 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.
a655eae3 1003 * @param pBuffer pointer to buffer
32db4144 1004 * @param iBufferSize size of the buffer in byte
a655eae3 1005 * @param dt data type
1006 * @param spec data specification
79c114b5 1007 * @param pHeader pointer to header
1008 * @param iHeaderSize size of Header
b6800be0 1009 * @return neg. error code if failed
a655eae3 1010 */
79c114b5 1011 int InsertOutputBlock(void* pBuffer, int iBufferSize,
a655eae3 1012 const AliHLTComponentDataType& dt,
79c114b5 1013 AliHLTUInt32_t spec,
1014 void* pHeader=NULL, int iHeaderSize=0);
a655eae3 1015
bfccbf68 1016 /** The global component handler instance */
a655eae3 1017 static AliHLTComponentHandler* fgpComponentHandler; //! transient
70ed7d01 1018
bfccbf68 1019 /** The environment where the component is running in */
a655eae3 1020 AliHLTComponentEnvironment fEnvironment; // see above
f23a6e1a 1021
a655eae3 1022 /** Set by ProcessEvent before the processing starts */
1023 AliHLTEventID_t fCurrentEvent; // see above
f23a6e1a 1024
3cde846d 1025 /** internal event no */
a655eae3 1026 int fEventCount; // see above
1027
1028 /** the number of failed events */
1029 int fFailedEvents; // see above
1030
1031 /** event data struct of the current event under processing */
1032 AliHLTComponentEventData fCurrentEventData; // see above
1033
1034 /** array of input data blocks of the current event */
1035 const AliHLTComponentBlockData* fpInputBlocks; //! transient
1036
1037 /** index of the current input block */
1038 int fCurrentInputBlock; // see above
1039
1040 /** data type of the last block search */
1041 AliHLTComponentDataType fSearchDataType; // see above
1042
1043 /** name of the class for the object to search for */
1044 string fClassName; // see above
1045
1046 /** array of generated input objects */
1047 TObjArray* fpInputObjects; //! transient
1048
1049 /** the output buffer */
1050 AliHLTUInt8_t* fpOutputBuffer; //! transient
1051
1052 /** size of the output buffer */
1053 AliHLTUInt32_t fOutputBufferSize; // see above
1054
1055 /** size of data written to output buffer */
1056 AliHLTUInt32_t fOutputBufferFilled; // see above
1057
1058 /** list of ouput block data descriptors */
1059 vector<AliHLTComponentBlockData> fOutputBlocks; // see above
3cde846d 1060
90ebac25 1061 /** stopwatch array */
1062 TObjArray* fpStopwatches; //! transient
1063
79c114b5 1064 /** array of memory files AliHLTMemoryFile */
1065 vector<AliHLTMemoryFile*> fMemFiles; //! transient
1066
559631d5 1067 /** descriptor of the current run */
1068 AliHLTRunDesc* fpRunDesc; //! transient
1069
1070 /** the current DDL list */
1071 AliHLTEventDDL* fpDDLList; //! transient
1072
79c114b5 1073 ClassDef(AliHLTComponent, 3)
f23a6e1a 1074};
1075#endif