cfcc1a6fafe45005723e9e9e94c26ef9574f5de7
[u/mrichter/AliRoot.git] / HLT / BASE / AliHLTComponent.h
1 //-*- Mode: C++ -*-
2 // $Id$
3
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                               *
9
10 //  @file   AliHLTComponent.h
11 //  @author Matthias Richter, Timm Steinbeck
12 //  @date   
13 //  @brief  Base class declaration for HLT components. 
14 //  @note   The class is both used in Online (PubSub) and Offline (AliRoot)
15 //          context
16
17
18 /**
19  * @defgroup alihlt_component Component handling of the HLT module
20  * This section describes the the component base classes and handling for
21  * the HLT module.
22  *
23  * @section alihlt_component_intro General remarks
24  * HLT analysis is organized in so called components. Each component can
25  * subscribe to the data produced by other components and can from the
26  * analysis publish new data for the subsequent components. Only the
27  * input data blocks and entries from CDB are available for the analysis. 
28  *
29  * @section alihlt_component_implementation Component implementation
30  * AliHLTComponent provides the interface for all components, see there
31  * for details. Three types are provided:
32  * - AliHLTProcessor
33  * - AliHLTDataSource
34  * - AliHLTDataSink
35  *
36  * The two last represent data sinks and sources for the HLT integration
37  * into AliRoot. When running only, only the processors are relevant,
38  * sources and sinks are provided by the HLT PubSub framework. Please check
39  * AliHLTComponent for detailed description.
40  *
41  * @section alihlt_component_registration Component registration
42  * Components need to be registered with the AliHLTComponentHandler in
43  * order to be used with the system. Registration is purely done from the
44  * module library. Two methods are possible:
45  * - the module library implements an AliHLTModuleAgent and overloads the
46  *   AliHLTModuleAgent::RegisterComponents() function
47  * - in the implementation file, one object is defined. The global object is
48  *   automatically instantiated when the library is loaded for the first
49  *   time and the object is used for registration.
50  *
51  * In both cases, the library must be loaded via the method
52  * <pre>
53  *  AliHLTComponentHandler::LoadComponentLibraries()
54  * </pre>
55  * For the global object approach it is important that the library is
56  * not loaded elsewhere before (e.g. a gSystem->Load operation in your
57  * rootlogon.C).
58  *
59  *
60  */
61
62 #include <vector>
63 #include <string>
64 #include "AliHLTLogging.h"
65 #include "AliHLTDataTypes.h"
66 #include "AliHLTCommonCDBEntries.h"
67
68 /* Matthias Dec 2006
69  * The names have been changed for Aliroot's coding conventions sake
70  * The old names are defined for backward compatibility with the 
71  * stand alone SampleLib package
72  */
73 typedef AliHLTComponentLogSeverity AliHLTComponent_LogSeverity;
74 typedef AliHLTComponentEventData AliHLTComponent_EventData;
75 typedef AliHLTComponentShmData AliHLTComponent_ShmData;
76 typedef AliHLTComponentDataType AliHLTComponent_DataType;
77 typedef AliHLTComponentBlockData AliHLTComponent_BlockData;
78 typedef AliHLTComponentTriggerData AliHLTComponent_TriggerData;
79 typedef AliHLTComponentEventDoneData AliHLTComponent_EventDoneData;
80
81 class AliHLTComponentHandler;
82 class TObjArray;
83 class TMap;
84 class TStopwatch;
85 class AliHLTComponent;
86 class AliHLTMemoryFile;
87 class AliHLTCTPData;
88
89 /** list of component data type structures */
90 typedef vector<AliHLTComponentDataType>   AliHLTComponentDataTypeList;
91 /** list of component block data structures */
92 typedef vector<AliHLTComponentBlockData>  AliHLTComponentBlockDataList;
93 /** list of component statistics struct */
94 typedef vector<AliHLTComponentStatistics> AliHLTComponentStatisticsList;
95 /** list of component pointers */
96 typedef vector<AliHLTComponent*>          AliHLTComponentPList;
97 /** list of memory file pointers */
98 typedef vector<AliHLTMemoryFile*>         AliHLTMemoryFilePList;
99
100 /**
101  * @class AliHLTComponent
102  * Base class of HLT data processing components.
103  * The class provides a common interface for HLT data processing components.
104  * The interface can be accessed from the online HLT framework or the AliRoot
105  * offline analysis framework.
106  * @section alihltcomponent-properties Component identification and properties
107  * Each component must provide a unique ID, input and output data type indications,
108  * and a spawn function.
109  * @subsection alihltcomponent-req-methods Required property methods
110  * - @ref GetComponentID
111  * - @ref GetInputDataTypes (see @ref alihltcomponent-type for default
112  *   implementations.)
113  * - @ref GetOutputDataType (see @ref alihltcomponent-type for default
114  *   implementations.)
115  * - @ref GetOutputDataSize (see @ref alihltcomponent-type for default
116  *   implementations.)
117  * - @ref Spawn
118  *
119  * @subsection alihltcomponent-opt-mehods Optional handlers
120  * - @ref DoInit
121  * - @ref DoDeinit
122  * - @ref GetOutputDataTypes
123  *   If the component has multiple output data types @ref GetOutputDataType
124  *   should return @ref kAliHLTMultipleDataType. The framework will invoke
125  *   @ref GetOutputDataTypes, a list can be filled.
126  * - @ref Reconfigure
127  *   This function is invoked by the framework on a special event which
128  *   triggers the reconfiguration of the component.
129  *
130  * @subsection alihltcomponent-processing-mehods Data processing
131  * 
132  * 
133  * @subsection alihltcomponent-type Component type
134  * Components can be of type
135  * - @ref kSource     components which only produce data 
136  * - @ref kProcessor  components which consume and produce data
137  * - @ref kSink       components which only consume data
138  *
139  * where data production and consumption refer to the analysis data stream. In
140  * order to indicate the type, a child component can overload the
141  * @ref GetComponentType function.
142  * @subsubsection alihltcomponent-type-std Standard implementations
143  * Components in general do not need to implement this function, standard
144  * implementations of the 3 types are available:
145  * - AliHLTDataSource for components of type @ref kSource <br>
146  *   All types of data sources can inherit from AliHLTDataSource and must
147  *   implement the @ref AliHLTDataSource::GetEvent method. The class
148  *   also implements a standard method for @ref GetInputDataTypes.
149  *   
150  * - AliHLTProcessor for components of type @ref kProcessor <br>
151  *   All types of data processors can inherit from AliHLTProcessor and must
152  *   implement the @ref AliHLTProcessor::DoEvent method.
153  *
154  * - AliHLTDataSink for components of type @ref kSink <br>
155  *   All types of data processors can inherit from AliHLTDataSink and must
156  *   implement the @ref AliHLTDataSink::DumpEvent method. The class
157  *   also implements a standard method for @ref GetOutputDataType and @ref
158  *   GetOutputDataSize.
159  *
160  * @subsection alihltcomponent-environment Running environment
161  *
162  * In order to adapt to different environments (on-line/off-line), the component
163  * gets an environment structure with function pointers. The base class provides
164  * member functions for those environment dependend functions. The member 
165  * functions are used by the component implementation and are re-mapped to the
166  * corresponding functions.
167  *
168  * @section alihltcomponent-interfaces Component interfaces
169  * Each of the 3 standard component base classes AliHLTProcessor, AliHLTDataSource
170  * and AliHLTDataSink provides it's own processing method (see
171  * @ref alihltcomponent-type-std), which splits into a high and a low-level
172  * method. For the @ref alihltcomponent-low-level-interface, all parameters are
173  * shipped as function arguments, the component is supposed to write data to the
174  * output buffer and handle all block descriptors. 
175  * The @ref alihltcomponent-high-level-interface is the standard processing
176  * method and will be used whenever the low-level method is not overloaded.
177  *
178  * In both cases it is necessary to calculate/estimate the size of the output
179  * buffer before the processing. Output buffers can never be allocated inside
180  * the component because of the push-architecture of the HLT.
181  * For that reason the @ref GetOutputDataSize function should return a rough
182  * estimatian of the data to be produced by the component. The component is
183  * responsible for checking the memory size and must return -ENOSPC if the
184  * available buffer is too small, and update the estimator respectively. The
185  * framework will allocate a buffer of appropriate size and call the processing
186  * again.
187  *
188  * @subsection alihltcomponent-error-codes Return values/Error codes
189  * For return codes, the following scheme applies:
190  * - The data processing methods have to indicate error conditions by a negative
191  * error/return code. Preferably the system error codes are used like
192  * e.g. -EINVAL. This requires to include the header
193  * <pre>
194  * \#include \<cerrno\>
195  * </pre>
196  * This schema aplies to all interface functions of the component base class.
197  * For data processing it is as follows:
198  * - If no suitable input block could be found (e.g. no clusters for the TPC cluster
199  * finder) set size to 0, block list is empty, return 0
200  * - If no ususable or significant signal could be found in the input blocks
201  * return an empty output block, set size accordingly, and return 0. An empty output
202  * block here could be either a real empty one of size 0 (in which case size also
203  * would have to be set to zero) or a block filled with just the minimum necessary
204  * accounting/meta-structures. E.g. in the TPC
205  *
206  * @subsection alihltcomponent-high-level-interface High-level interface
207  * The high-level component interface provides functionality to exchange ROOT
208  * structures between components. In contrast to the 
209  * @ref alihltcomponent-low-level-interface, a couple of functions can be used
210  * to access data blocks of the input stream
211  * and send data blocks or ROOT TObject's to the output stream. The functionality
212  * is hidden from the user and is implemented by using ROOT's TMessage class.
213  *
214  * @subsubsection alihltcomponent-high-level-int-methods Interface methods
215  * The interface provides a couple of methods in order to get objects from the
216  * input, data blocks (non TObject) from the input, and to push back objects and
217  * data blocks to the output. For convenience there are several functions of 
218  * identical name (and similar behavior) with different parameters defined.
219  * Please refer to the function documentation.
220  * - @ref GetNumberOfInputBlocks <br>
221  *        return the number of data blocks in the input stream
222  * - @ref GetFirstInputObject <br>
223  *        get the first object of a specific data type
224  * - @ref GetNextInputObject <br>
225  *        get the next object of same data type as last GetFirstInputObject/Block call
226  * - @ref GetFirstInputBlock <br>
227  *        get the first block of a specific data type
228  * - @ref GetNextInputBlock <br>
229  *        get the next block of same data type as last GetFirstInputBlock/Block call
230  * - @ref PushBack <br>
231  *        insert an object or data buffer into the output
232  * - @ref CreateEventDoneData <br>
233  *        add event information to the output
234  * 
235  * In addition, the processing methods are simplified a bit by cutting out most of
236  * the parameters.
237  * @see 
238  * - @ref AliHLTProcessor::DoEvent
239  * - @ref AliHLTDataSource::GetEvent
240  * - @ref AliHLTDataSink::DumpEvent
241  *
242  * \em IMPORTANT: objects and block descriptors provided by the high-level interface
243  *  <b>MUST NOT BE DELETED</b> by the caller.
244  *
245  * @subsubsection alihltcomponent-high-level-int-guidelines High-level interface guidelines
246  * - Structures must inherit from the ROOT object base class TObject in order be 
247  * transported by the transportation framework.
248  * - all pointer members must be transient (marked <tt>//!</tt> behind the member
249  * definition), i.e. will not be stored/transported, or properly marked
250  * (<tt>//-></tt>) in order to call the streamer of the object the member is pointing
251  * to. The latter is not recomended. Structures to be transported between components
252  * should be streamlined.
253  * - no use of stl vectors/strings, use appropriate ROOT classes instead 
254  * 
255  * @subsection alihltcomponent-low-level-interface Low-level interface
256  * The low-level component interface consists of the specific data processing
257  * methods for @ref AliHLTProcessor, @ref AliHLTDataSource, and @ref AliHLTDataSink.
258  * - @ref AliHLTProcessor::DoEvent
259  * - @ref AliHLTDataSource::GetEvent
260  * - @ref AliHLTDataSink::DumpEvent
261  * 
262  * The base class passes all relevant parameters for data access directly on to the
263  * component. Input blocks can be accessed by means of the array <tt> blocks </tt>.
264  * Output data are written directly to shared memory provided by the pointer
265  * <tt> outputPtr </tt> and output block descriptors are inserted directly to the
266  * list <tt> outputBlocks </tt>.
267  *
268  * \b NOTE: The high-level input data access methods can be used also from the low
269  * level interface. Also the PushBack functions can be used BUT ONLY if no data is
270  * written to the output buffer and no data block descriptors are inserted into the
271  * output block list.
272  *
273  * @section alihltcomponent-initialization Component initialization and configuration
274  * The component interface provides two optional methods for component initialization
275  * and configuration. The @ref DoInit function is called once before the processing.
276  * During the event processing, a special event can trigger a reconfiguration and the
277  * @ref Reconfigure method is called. There are three possible options of initialization
278  * and configuration:
279  * - default values: set directly in the source code
280  * - OCDB objects: all necessary information must be loaded from OCDB objects. The
281  *   Offline Conditions Data Base stores objects specifically valid for individual runs
282  *   or run ranges.
283  * - Component arguments: can be specified for every component in the chain
284  *   configuration. The arguments can be used to override specific parameters of the
285  *   component.
286  *
287  * As a general rule, the three options should be processed in that sequence, i.e
288  * default parameters might be overridden by OCDB configuration, and the latter one
289  * by component arguments.
290  *
291  * @subsection alihltcomponent-initialization-arguments Component arguments
292  * In normal operation, components are supposed to run without any additional argument,
293  * however such arguments can be useful for testing and debugging. The idea follows
294  * the format of command line arguments. A keyword is indicated by a dash and an
295  * optional argument might follow, e.g.:
296  * <pre>
297  * -argument1 0.5 -argument2
298  * </pre>
299  * In this case argument1 requires an additional parameter whereas argument2 does not.
300  * The arguments will be provided as an array of separated arguments.
301  *
302  * Component arguments can be classified into initialization arguments and configuration
303  * arguments. The latter are applicable for both the @ref DoInit and @ref Reconfigure
304  * method whereas initialization arguments are not applicable after DoInit.
305  *
306  * @subsection alihltcomponent-initialization-ocdb OCDB objects
307  * OCDB objects are ROOT <tt>TObjects</tt> and can be of any type. This is in particular
308  * useful for complex parameter sets. However in most cases, a simple approach of human
309  * readable command line arguments is appropriate. Such a string can be simply stored
310  * in a TObjString (take note that the TString does not derive from TObject). The
311  * same arguments as for the command line can be used. Take note that in the TObjString
312  * all arguments are separated by blanks, instead of being in an array of separate
313  * strings.
314  *
315  * The base class provides two functions regarding OCDB objects: 
316  * - LoadAndExtractOCDBObject() loads the OCDB entry for the specified path and extracts
317  *                              the TObject from it.
318  * - ConfigureFromCDBTObjString() can load a number of OCDB objects and calls the
319  *                              argument parsing ConfigureFromArgumentString
320  *
321  *
322  * @subsection alihltcomponent-initialization-sequence Initialization sequence
323  * Using the approach of <tt>TObjString</tt>-type configuration objects allows to treat
324  * configuration from both @ref DoInit and @ref Reconfigure in the same way.
325  *
326  * The base class provides the function ConfigureFromArgumentString() which loops over
327  * all arguments and calls the child's method ScanConfigurationArgument(). Here the
328  * actual treatment of the argument and its parameters needs to be implemented.
329  * ConfigureFromArgumentString() can treat both arrays of arguments and arguments in
330  * one single string separated by blanks. The two options can be mixed.
331  *
332  * A second bas class function ConfigureFromCDBTObjString() allows to configure
333  * directly from a number of OCDB objects. This requires the entries to be of
334  * type TObjString and the child implementation of ScanConfigurationArgument().
335  *
336  * @section alihltcomponent-handling Component handling 
337  * The handling of HLT analysis components is carried out by the AliHLTComponentHandler.
338  * Component are registered automatically at load-time of the component shared library
339  * under the following suppositions:
340  * - the component library has to be loaded from the AliHLTComponentHandler using the
341  *   @ref AliHLTComponentHandler::LoadLibrary method.
342  * - the library defines an AliHLTModuleAgent which registers all components.
343  *   See AliHLTModuleAgent::RegisterComponents                               <br>
344  *     or                                                                    <br>
345  * - the component implementation defines one global object (which is generated
346  *   when the library is loaded)                                             <br>
347  *
348  * @subsection alihltcomponent-design-rules General design considerations
349  * The analysis code should be implemented in one or more destict class(es). A 
350  * \em component should be implemented which interface the destict analysis code to the
351  * component interface. This component generates the analysis object dynamically. <br>
352  *
353  * Assume you have an implemetation <tt> AliHLTDetMyAnalysis </tt>, another class <tt>
354  * AliHLTDetMyAnalysisComponent </tt> contains:
355  * <pre>
356  * private:
357  *   AliHLTDetMyAnalysis* fMyAnalysis;  //!
358  * </pre>
359  * The object should then be instantiated in the DoInit handler of 
360  * <tt>AliHLTDetMyAnalysisComponent </tt>, and cleaned in the DoDeinit handler.
361  *
362  * Further rules:
363  * - avoid big static arrays in the component, allocate the memory at runtime
364  * - allocate all kind of complex data members (like classes, ROOT TObjects of
365  *   any kind) dynamically in DoInit and clean up in DoDeinit
366  *
367  * @section alihlt_component_arguments Default arguments
368  * The component base class provides some default arguments:
369  * <!-- NOTE: ignore the \li. <i> and </i>: it's just doxygen formatting -->
370  * \li -loglevel=level     <br>
371  * \li -object-compression=level     <br>
372  *      compression level for ROOT objects, default is defined by
373  *      @ref ALIHLTCOMPONENT_DEFAULT_OBJECT_COMPRESSION
374  * \li -pushback-period=period     <br>
375  *      scale down for PushBack of objects, shipped only for one event
376  *      every <i>period</i> seconds
377  *
378  * @ingroup alihlt_component
379  * @section alihltcomponent-members Class members
380  */
381 class AliHLTComponent : public AliHLTLogging {
382  public:
383   /** standard constructor */
384   AliHLTComponent();
385   /** standard destructor */
386   virtual ~AliHLTComponent();
387
388   /** component type definitions */
389   enum TComponentType { kUnknown=0, kSource=1, kProcessor=2, kSink=3 };
390
391   /**
392    * Init function to prepare data processing.
393    * Initialization of common data structures for a sequence of events.
394    * The call is redirected to the internal method DoInit which can be
395    * overridden by the child class.
396    * During Init also the environment structure is passed to the component.
397    * @param comenv         environment pointer with environment dependent function
398    *                       calls
399    * @param environParam   additional parameter for function calls, the pointer
400    *                       is passed as it is
401    * @param argc           size of the argument array
402    * @param argv           augment array for component initialization
403    */
404   virtual int Init( const AliHLTAnalysisEnvironment* comenv, void* environParam, int argc, const char** argv );
405
406   /**
407    * Clean-up function to terminate data processing.
408    * Clean-up of common data structures after data processing.
409    * The call is redirected to the internal method @ref DoDeinit which can be
410    * overridden by the child class.
411    */
412   virtual int Deinit();
413
414   /**
415    * Processing of one event.
416    * The method is the entrance of the event processing. The parameters are
417    * cached for uses with the high-level interface and the DoProcessing
418    * implementation is called.
419    *
420    * @param evtData
421    * @param blocks
422    * @param trigData
423    * @param outputPtr
424    * @param size
425    * @param outputBlockCnt  out: size of the output block array, set by the component
426    * @param outputBlocks    out: the output block array is allocated internally
427    * @param edd
428    * @return neg. error code if failed
429    */
430   int ProcessEvent( const AliHLTComponentEventData& evtData, const AliHLTComponentBlockData* blocks, 
431                             AliHLTComponentTriggerData& trigData, AliHLTUInt8_t* outputPtr, 
432                             AliHLTUInt32_t& size, AliHLTUInt32_t& outputBlockCnt, 
433                             AliHLTComponentBlockData*& outputBlocks,
434                             AliHLTComponentEventDoneData*& edd );
435
436   /**
437    * Internal processing of one event.
438    * The method is pure virtual and implemented by the child classes 
439    * - @ref AliHLTProcessor
440    * - @ref AliHLTDataSource
441    * - @ref AliHLTDataSink
442    *
443    * @param evtData
444    * @param blocks
445    * @param trigData
446    * @param outputPtr
447    * @param size
448    * @param outputBlocks    out: the output block array is allocated internally
449    * @param edd
450    * @return neg. error code if failed
451    */
452   virtual int DoProcessing( const AliHLTComponentEventData& evtData, const AliHLTComponentBlockData* blocks, 
453                             AliHLTComponentTriggerData& trigData, AliHLTUInt8_t* outputPtr, 
454                             AliHLTUInt32_t& size,
455                             AliHLTComponentBlockDataList& outputBlocks,
456                             AliHLTComponentEventDoneData*& edd ) = 0;
457
458   /**
459    * Init the CDB.
460    * The function must not be called when running in AliRoot unless it it
461    * really wanted. The CDB path will be set to the specified path, which might
462    * override the path initialized at the beginning of the AliRoot reconstruction.
463    *
464    * The method is used from the external interface in order to set the correct
465    * path when running on-line. The function also initializes the function
466    * callback for setting the run no during operation.
467    *
468    * A separation of library and component handling is maybe appropriate in the
469    * future. Using the global component handler here is maybe not the cleanest
470    * solution.
471    * @param cdbPath      path of the CDB
472    * @param pHandler     the component handler used for llibrary handling.
473    */
474   int InitCDB(const char* cdbPath, AliHLTComponentHandler* pHandler);
475
476   /**
477    * Set the run no for the CDB.
478    * The function must not be called when running in AliRoot unless it it
479    * really wanted. The CDB path will be set to the specified path, which might
480    * override the run no initialized at the beginning of the AliRoot reconstruction.
481    * InitCDB() has to be called before in order to really change the CDB settings.
482    *
483    * The method is used from the external interface in order to set the correct
484    * path when running on-line.
485    */
486   int SetCDBRunNo(int runNo);
487
488   /**
489    * Set the run description.
490    * The run description is set before the call of Init() -> DoInit().
491    * @note: This functionality has been added in Juli 2008. The transmission of
492    * run properties by a special SOR (SOD event in DAQ terminalogy but this was
493    * changed after the HLT interface was designed) event is not sufficient because
494    * the data might be needed already in the DoInit handler of the component.
495    * @param desc    run descriptor, currently only the run no member is used
496    * @param runType originally, run type was supposed to be a number and part
497    *                of the run descriptor. But it was defined as string later
498    */
499   int SetRunDescription(const AliHLTRunDesc* desc, const char* runType);
500
501   /**
502    * Set the component description.
503    * The description string can contain tokens separated by blanks, a token
504    * consists of a key and an optional value separated by '='.
505    * Possible keys:
506    * \li -chainid=id        string id within the chain of the instance
507    *
508    * @param desc    component description
509    */
510   int SetComponentDescription(const char* desc);
511
512   /**
513    * Set the running environment for the component.
514    * Originally, the environment was set in the Init function. However, the setup of
515    * the CDB is required before. In order to have proper logging functionality, the
516    * environment is required.
517    * @param comenv         environment pointer with environment dependent function
518    *                       calls
519    * @param environParam   additional parameter for function calls, the pointer
520    *                       is passed as it is
521    */
522   int SetComponentEnvironment(const AliHLTAnalysisEnvironment* comenv, void* environParam);
523
524   // Information member functions for registration.
525
526   /**
527    * Get the type of the component.
528    * The function is pure virtual and must be implemented by the child class.
529    * @return component type id
530    */
531   virtual TComponentType GetComponentType() = 0; // Source, sink, or processor
532
533   /**
534    * Get the id of the component.
535    * Each component is identified by a unique id.
536    * The function is pure virtual and must be implemented by the child class.
537    * @return component id (string)
538    */
539   virtual const char* GetComponentID() = 0;
540
541   /**
542    * Get the input data types of the component.
543    * The function is pure virtual and must be implemented by the child class.
544    * @return list of data types in the vector reference
545    */
546   virtual void GetInputDataTypes( AliHLTComponentDataTypeList& ) = 0;
547
548   /**
549    * Get the output data type of the component.
550    * The function is pure virtual and must be implemented by the child class.
551    * @return output data type
552    */
553   virtual AliHLTComponentDataType GetOutputDataType() = 0;
554
555   /**
556    * Get the output data types of the component.
557    * The function can be implemented to indicate multiple output data types
558    * in the target array.
559    * @ref GetOutputDataType must return @ref kAliHLTMultipleDataType in order
560    * to invoke this method.
561    * @param tgtList          list to receive the data types
562    * @return no of output data types, data types in the target list
563    */
564   virtual int GetOutputDataTypes(AliHLTComponentDataTypeList& tgtList);
565
566   /**
567    * Get a ratio by how much the data volume is shrunken or enhanced.
568    * The function is pure virtual and must be implemented by the child class.
569    * @param constBase        <i>return</i>: additive part, independent of the
570    *                                   input data volume  
571    * @param inputMultiplier  <i>return</i>: multiplication ratio
572    * @return values in the reference variables
573    */
574   virtual void GetOutputDataSize( unsigned long& constBase, double& inputMultiplier ) = 0;
575
576   /**
577    * Get a list of OCDB object description.
578    * The list of objects is provided in a TMap
579    * - key: complete OCDB path, e.g. GRP/GRP/Data
580    * - value: short description why the object is needed
581    * Key and value objects created inside this class go into ownership of
582    * target TMap.
583    * @param targetMap   TMap instance receiving the list
584    * @return void
585    */
586   virtual void GetOCDBObjectDescription( TMap* const targetArray);
587
588   /**
589    * Spawn function.
590    * Each component must implement a spawn function to create a new instance of 
591    * the class. Basically the function must return <i>new <b>my_class_name</b></i>.
592    * @return new class instance
593    */
594   virtual AliHLTComponent* Spawn() = 0;
595
596   /**
597    * check the availability of the OCDB entry descriptions in the TMap
598    *  key : complete OCDB path of the entry
599    *  value : auxiliary object - short description
600    * if the external map was not provided the function invokes
601    * interface function GetOCDBObjectDescription() to retrieve the list.
602    * @param externList  map of entries to be tested
603    * @result 0 if all found, -ENOENT if objects not found
604    */
605   int CheckOCDBEntries(const TMap* const externList=NULL);
606
607   /**
608    * Find matching data types between this component and a consumer component.
609    * Currently, a component can produce only one type of data. This restriction is most
610    * likely to be abolished in the future.
611    * @param pConsumer a component and consumer of the data produced by this component
612    * @param tgtList   reference to a vector list to receive the matching data types.
613    * @return >= 0 success, neg. error code if failed
614    */ 
615   int FindMatchingDataTypes(AliHLTComponent* pConsumer, AliHLTComponentDataTypeList* tgtList);
616  
617   /**
618    * Set the global component handler.
619    * The static method is needed for the automatic registration of components. 
620    */
621   static int SetGlobalComponentHandler(AliHLTComponentHandler* pCH, int bOverwrite=0);
622
623   /**
624    * Clear the global component handler.
625    * The static method is needed for the automatic registration of components. 
626    */
627   static int UnsetGlobalComponentHandler();
628
629   /**
630    * Helper function to convert the data type to a string.
631    * @param type        data type structure
632    * @param mode        0 print string origin:type          <br>
633    *                    1 print chars                       <br>
634    *                    2 print numbers
635    */
636   static string DataType2Text( const AliHLTComponentDataType& type, int mode=0);
637
638   /**
639    * Calculate a CRC checksum of a data buffer.
640    * Polynomial for the calculation is 0xD8.
641    */
642   static AliHLTUInt32_t CalculateChecksum(const AliHLTUInt8_t* buffer, int size);
643
644   /**
645    * Helper function to print content of data type.
646    */
647   static void PrintDataTypeContent(AliHLTComponentDataType& dt, const char* format=NULL);
648
649   /**
650    * helper function to initialize AliHLTComponentEventData structure
651    */
652   static void FillEventData(AliHLTComponentEventData& evtData);
653
654   /**
655    * Print info on an AliHLTComponentDataType structure
656    * This is just a helper function to examine an @ref AliHLTComponentDataType
657    * structur.
658    */
659   static void PrintComponentDataTypeInfo(const AliHLTComponentDataType& dt);
660
661   /**
662    * Fill AliHLTComponentBlockData structure with default values.
663    * @param blockData   reference to data structure
664    */
665   static void FillBlockData( AliHLTComponentBlockData& blockData );
666
667   /**
668    * Fill AliHLTComponentShmData structure with default values.
669    * @param shmData   reference to data structure
670    */
671   static void FillShmData( AliHLTComponentShmData& shmData );
672
673   /**
674    * Fill AliHLTComponentDataType structure with default values.
675    * @param dataType   reference to data structure
676    */
677   static void FillDataType( AliHLTComponentDataType& dataType );
678   
679   /**
680    * Copy data type structure
681    * Copies the value an AliHLTComponentDataType structure to another one
682    * @param[out] tgtdt   target structure
683    * @param[in] srcdt   source structure
684    */
685   static void CopyDataType(AliHLTComponentDataType& tgtdt, const AliHLTComponentDataType& srcdt);
686
687   /**
688    * Set the ID and Origin of an AliHLTComponentDataType structure.
689    * The function sets the fStructureSize member and copies the strings
690    * to the ID and Origin. Only characters from the valid part of the string
691    * are copied, the rest is filled with 0's. <br>
692    * Please note that the fID and fOrigin members are not strings, just arrays of
693    * chars of size @ref kAliHLTComponentDataTypefIDsize and
694    * @ref kAliHLTComponentDataTypefOriginSize respectively and not necessarily with
695    * a terminating zero. <br>
696    * It is possible to pass NULL pointers as id or origin argument, in that case they
697    * are just ignored.
698    * @param tgtdt   target data type structure
699    * @param id      ID string
700    * @param origin  Origin string
701    */
702   static void SetDataType(AliHLTComponentDataType& tgtdt, const char* id, const char* origin);
703
704   /**
705    * Set the ID and Origin of an AliHLTComponentDataType structure.
706    * Given the fact that the data type ID is 64bit wide and origin 32, this helper
707    * function sets the data type from those two parameters.
708    * @param dt      target data type structure
709    * @param id      64bit id
710    * @param orig    32bit origin
711    */
712   static void SetDataType(AliHLTComponentDataType& dt, AliHLTUInt64_t id, AliHLTUInt32_t orig); 
713
714   /**
715    * Extract a component table entry from the payload buffer.
716    * The entry consists of the AliHLTComponentTableEntry structure, the array of
717    * parents and a description string of the format 'chain-id{component-id:component-args}'.
718    * The function fills all the variables after a consistency check.
719    */
720   static int ExtractComponentTableEntry(const AliHLTUInt8_t* pBuffer, AliHLTUInt32_t size,
721                                         string& chainId, string& compId, string& compParam,
722                                         vector<AliHLTUInt32_t>& parents);
723   /**
724    * Stopwatch type for benchmarking.
725    */
726   enum AliHLTStopwatchType {
727     /** total time for event processing */
728     kSWBase,
729     /** detector algorithm w/o interface callbacks */
730     kSWDA,
731     /** data sources */
732     kSWInput,
733     /** data sinks */
734     kSWOutput,
735     /** number of types */
736     kSWTypeCount
737   };
738
739   /**
740    * Helper class for starting and stopping a stopwatch.
741    * The guard can be used by instantiating an object in a function. The
742    * specified stopwatch is started and the previous stopwatch put on
743    * hold. When the function is terminated, the object is deleted automatically
744    * deleted, stopping the stopwatch and starting the one on hold.<br>
745    * \em IMPORTANT: never create dynamic objects from this guard as this violates
746    * the idea of a guard.
747    */
748   class AliHLTStopwatchGuard {
749   public:
750     /** standard constructor (not for use) */
751     AliHLTStopwatchGuard();
752     /** constructor */
753     AliHLTStopwatchGuard(TStopwatch* pStart);
754     /** copy constructor (not for use) */
755     AliHLTStopwatchGuard(const AliHLTStopwatchGuard&);
756     /** assignment operator (not for use) */
757     AliHLTStopwatchGuard& operator=(const AliHLTStopwatchGuard&);
758     /** destructor */
759     ~AliHLTStopwatchGuard();
760
761   private:
762     /**
763      * Hold the previous guard for the existence of this guard.
764      * Checks whether this guard controls a new stopwatch. In that case, the
765      * previous guard and its stopwatch are put on hold.
766      * @param pSucc        instance of the stopwatch of the new guard
767      * @return    1 if pSucc is a different stopwatch which should
768      *            be started<br>
769      *            0 if it controls the same stopwatch
770      */
771     int Hold(const TStopwatch* pSucc);
772
773     /**
774      * Resume the previous guard.
775      * Checks whether the peceeding guard controls a different stopwatch. In that
776      * case, the its stopwatch is resumed.
777      * @param pSucc        instance of the stopwatch of the new guard
778      * @return    1 if pSucc is a different stopwatch which should
779      *            be stopped<br>
780      *            0 if it controls the same stopwatch
781      */
782     int Resume(const TStopwatch* pSucc);
783
784     /** the stopwatch controlled by this guard */
785     TStopwatch* fpStopwatch;                                                //!transient
786
787     /** previous stopwatch guard, put on hold during existence of the guard */
788     AliHLTStopwatchGuard* fpPrec;                                           //!transient
789
790     /** active stopwatch guard */
791     static AliHLTStopwatchGuard* fgpCurrent;                                //!transient
792   };
793
794   /**
795    * Set a stopwatch for a given purpose.
796    * @param pSW         stopwatch object
797    * @param type        type of the stopwatch
798    */
799   int SetStopwatch(TObject* pSW, AliHLTStopwatchType type=kSWBase);
800
801   /**
802    * Init a set of stopwatches.
803    * @param pStopwatches object array of stopwatches
804    */
805   int SetStopwatches(TObjArray* pStopwatches);
806
807   /**
808    * Customized logging function.
809    * The chain id, component id and pointer is added at the beginning of each message.
810    */
811   int LoggingVarargs(AliHLTComponentLogSeverity severity, 
812                      const char* originClass, const char* originFunc,
813                      const char* file, int line, ... ) const;
814
815   /**
816    * Get size of last serialized object.
817    * During PushBack, TObjects are serialized in a separate buffer. The
818    * size of the last object can be retrieved by this function.
819    *
820    * This might be especially useful for PushBack failures caused by too
821    * small output buffer.
822    */
823   int GetLastObjectSize() const {return fLastObjectSize;}
824
825  protected:
826
827   /**
828    * Default method for the internal initialization.
829    * The method is called by @ref Init
830    */
831   virtual int DoInit( int argc, const char** argv );
832
833   /**
834    * Default method for the internal clean-up.
835    * The method is called by @ref Deinit
836    */
837   virtual int DoDeinit();
838
839   /**
840    * Reconfigure the component.
841    * The method is called when an event of type @ref kAliHLTDataTypeComConf
842    * {COM_CONF:PRIV} is received by the component. If the event is sent as
843    * part of a normal event, the component configuration is called first.
844    *
845    * The CDB path parameter specifies the path in the CDB, i.e. without
846    * leading absolute path of the CDB location. The framework might also
847    * provide the id of the component in the analysis chain.
848    *
849    * The actual sequence of configuration depends on the component. As a
850    * general rule, the component should load the specific OCDB object if
851    * provided as parameter, and load the default objects if the parameter
852    * is NULL. However, other schemes are possible. See @ref 
853    *
854    * \b Note: The CDB will be initialized by the framework, either already set
855    * from AliRoot or from the wrapper interface during initialization.
856    *
857    * @param cdbEntry     path of the cdbEntry
858    * @param chainId      the id/name of the component in the current analysis
859    *                     chain. This is not necessarily the same as what is
860    *                     returned by the GetComponentID() method.
861    * @note both parameters can be NULL, check before usage
862    */
863   virtual int Reconfigure(const char* cdbEntry, const char* chainId);
864
865   /**
866    * Read the Preprocessor values.
867    * The function is invoked when the component is notified about available/
868    * updated data points from the detector Preprocessors. The 'modules'
869    * argument contains all detectors for which the Preprocessors have
870    * updated data points. The component has to implement the CDB access to
871    * get the desired data points.
872    * @param modules     detectors for which the Preprocessors have updated
873    *                    data points: TPC, TRD, ITS, PHOS, MUON, or ALL if
874    *                    no argument was received.
875    * @return neg. error code if failed
876    */
877   virtual int ReadPreprocessorValues(const char* modules);
878
879   /**
880    * Child implementation to scan a number of configuration arguments.
881    * The method is invoked by the framework in conjunction with the
882    * common framework functions ConfigureFromArgumentString and
883    * ConfigureFromCDBTObjString.
884    * Function needs to scan the argument and optional additional
885    * parameters and returns the number of elements in the array which
886    * have been treated.
887    * @param argc
888    * @param argv
889    * @return number of arguments which have been scanned or neg error
890    *         code if failed                                              <br>
891    *         \li -EINVAL      unknown argument
892    *         \li -EPROTO      protocol error, e.g. missing parameter
893    */
894   virtual int ScanConfigurationArgument(int argc, const char** argv);
895
896   /**
897    * Custom handler for the SOR event.
898    * Is invoked from the base class if an SOR event is in the block list.
899    * The handler is called before the processing function. The processing
900    * function is skipped if there are no other data blocks available.
901    *
902    * The SOR event is generated by the PubSub framework in response to
903    * the DAQ start of data (SOD - has been renamed after HLT interface
904    * was designed). The SOD event consists of 3 blocks:
905    * - ::kAliHLTDataTypeEvent block: spec ::gkAliEventTypeStartOfRun
906    * - SOD block of type ::kAliHLTDataTypeSOR, payload: AliHLTRunDesc struct
907    * - run type block ::kAliHLTDataTypeRunType, payload: run type string 
908    *
909    * Run properties can be retrieved by getters like GetRunNo().
910    * @return neg. error code if failed
911    */
912   virtual int StartOfRun();
913
914   /**
915    * Custom handler for the EOR event.
916    * Is invoked from the base class if an EOR event is in the block list.
917    * The handler is called before the processing function. The processing
918    * function is skipped if there are no other data blocks available.
919    *
920    * See StartOfRun() for more comments of the sequence of steering events.
921    *
922    * @return neg. error code if failed
923    */
924   virtual int EndOfRun();
925
926   /**
927    * Check whether a component requires all steering blocks.
928    * Childs can overload in order to indicate that they want to
929    * receive also the steering data blocks. There is also the
930    * possibility to add the required data types to the input
931    * data type list in GetInputDataTypes().
932    */
933   virtual bool RequireSteeringBlocks() const {return false;}
934
935   /**
936    * General memory allocation method.
937    * All memory which is going to be used 'outside' of the interface must
938    * be provided by the framework (online or offline).
939    * The method is redirected to a function provided by the current
940    * framework. Function pointers are transferred via the @ref
941    * AliHLTAnalysisEnvironment structure.
942    */
943   void* AllocMemory( unsigned long size );
944
945   /**
946    * Helper function to create a monolithic BlockData description block out
947    * of a list BlockData descriptors.
948    * For convenience, inside the interface vector lists are used, to make the
949    * interface pure C style, monilithic blocks must be exchanged. 
950    * The method is redirected to a function provided by the current
951    * framework. Function pointers are transferred via the @ref
952    * AliHLTAnalysisEnvironment structure.
953    */
954   int MakeOutputDataBlockList( const AliHLTComponentBlockDataList& blocks, AliHLTUInt32_t* blockCount,
955                                AliHLTComponentBlockData** outputBlocks );
956
957   /**
958    * Fill the EventDoneData structure.
959    * The method is redirected to a function provided by the current
960    * framework. Function pointers are transferred via the @ref
961    * AliHLTAnalysisEnvironment structure.
962    */
963   int GetEventDoneData( unsigned long size, AliHLTComponentEventDoneData** edd ) const;
964
965   /**
966    * Allocate an EventDoneData structure for the current event .
967    * The method allocates the memory internally and does not interact with the current Framework.
968    * The allocated data structure is empty initially and can be filled by calls to the 
969    * @ref PushEventDoneData method. The memory will be automatically released after the event has been processed.
970    * 
971    */
972   int ReserveEventDoneData( unsigned long size );
973
974   /**
975    * Push a 32 bit word of data into event done data for the current event which
976    * has previously been allocated by the @ref ReserveEventDoneData method.
977    */
978   int PushEventDoneData( AliHLTUInt32_t eddDataWord );
979
980   /**
981    * Release event done data previously reserved by @ref ReserveEventDoneData
982    */
983    void ReleaseEventDoneData();
984
985   /**
986    * Get the pointer to the event done data available/built so far for the current event via
987    * @ref ReserveEventDoneData and @ref PushEventDoneData
988    */
989   AliHLTComponentEventDoneData* GetCurrentEventDoneData() const
990     {
991     return fEventDoneData;
992     }
993
994   /**
995    * Helper function to convert the data type to a string.
996    */
997   void DataType2Text(const AliHLTComponentDataType& type, char output[kAliHLTComponentDataTypefIDsize+kAliHLTComponentDataTypefOriginSize+2]) const;
998
999   /**
1000    * Loop through a list of component arguments.
1001    * The list can be either an array of separated strings or one single
1002    * string containing blank separated arguments, or both mixed.
1003    * ScanConfigurationArgument() is called to allow the component to treat
1004    * the individual arguments.
1005    * @return neg. error code if failed
1006    */
1007   int ConfigureFromArgumentString(int argc, const char** argv);
1008
1009   /**
1010    * Read configuration objects from OCDB and configure from
1011    * the content of TObjString entries.
1012    * @param entries   blank separated list of OCDB paths
1013    * @return neg. error code if failed
1014    */
1015   int ConfigureFromCDBTObjString(const char* entries);
1016
1017   /**
1018    * Load specified entry from the OCDB and extract the object.
1019    * The entry is explicitely unloaded from the cache before it is loaded.
1020    * @param path      path of the entry under to root of the OCDB
1021    * @param version   version of the entry
1022    * @param subVersion  subversion of the entry
1023    */
1024   TObject* LoadAndExtractOCDBObject(const char* path, int version = -1, int subVersion = -1);
1025
1026
1027   /**
1028    * Get event number.
1029    * @return value of the internal event counter
1030    */
1031   int GetEventCount() const;
1032
1033   /**
1034    * Get the number of input blocks.
1035    * @return number of input blocks
1036    */
1037   int GetNumberOfInputBlocks() const;
1038
1039   /**
1040    * Get id of the current event
1041    * @return event id
1042    */
1043   AliHLTEventID_t GetEventId() const;
1044
1045   /**
1046    * Get the first object of a specific data type from the input data.
1047    * The High-level methods provide functionality to transfer ROOT data
1048    * structures which inherit from TObject.
1049    *
1050    * The method looks for the first ROOT object of type dt in the input stream.
1051    * If also the class name is provided, the object is checked for the right
1052    * class type. The input data block needs a certain structure, namely the 
1053    * buffer size as first word. If the cross check fails, the retrieval is
1054    * silently abandoned, unless the \em bForce parameter is set.<br>
1055    * \b Note: THE OBJECT MUST NOT BE DELETED by the caller.
1056    *
1057    * If called without parameters, the function tries to create objects from
1058    * all available input blocks, also the ones of data type kAliHLTVoidDataType
1059    * which are not matched by kAliHLTAnyDataType.
1060    *
1061    * @param dt          data type of the object
1062    * @param classname   class name of the object
1063    * @param bForce      force the retrieval of an object, error messages
1064    *                    are suppressed if \em bForce is not set
1065    * @return pointer to @ref TObject, NULL if no objects of specified type
1066    *         available
1067    */
1068   const TObject* GetFirstInputObject(const AliHLTComponentDataType& dt=kAliHLTAllDataTypes,
1069                                      const char* classname=NULL,
1070                                      int bForce=0);
1071
1072   /**
1073    * Get the first object of a specific data type from the input data.
1074    * The High-level methods provide functionality to transfer ROOT data
1075    * structures which inherit from TObject.
1076    * The method looks for the first ROOT object of type specified by the ID and 
1077    * Origin strings in the input stream.
1078    * If also the class name is provided, the object is checked for the right
1079    * class type. The input data block needs a certain structure, namely the 
1080    * buffer size as first word. If the cross check fails, the retrieval is
1081    * silently abandoned, unless the \em bForce parameter is set.<br>
1082    * \em Note: THE OBJECT MUST NOT BE DELETED by the caller.
1083    * @param dtID        data type ID of the object
1084    * @param dtOrigin    data type origin of the object
1085    * @param classname   class name of the object
1086    * @param bForce      force the retrieval of an object, error messages
1087    *                    are suppressed if \em bForce is not set
1088    * @return pointer to @ref TObject, NULL if no objects of specified type
1089    *         available
1090    */
1091   const TObject* GetFirstInputObject(const char* dtID, 
1092                                      const char* dtOrigin,
1093                                      const char* classname=NULL,
1094                                      int bForce=0);
1095
1096   /**
1097    * Get the next object of a specific data type from the input data.
1098    * The High-level methods provide functionality to transfer ROOT data
1099    * structures which inherit from TObject.
1100    * The method looks for the next ROOT object of type and class specified
1101    * to the previous @ref GetFirstInputObject call.<br>
1102    * \em Note: THE OBJECT MUST NOT BE DELETED by the caller.
1103    * @param bForce      force the retrieval of an object, error messages
1104    *                    are suppressed if \em bForce is not set
1105    * @return pointer to @ref TObject, NULL if no more objects available
1106    */
1107   const TObject* GetNextInputObject(int bForce=0);
1108
1109   /**
1110    * Get data type of an input block.
1111    * Get data type of the object previously fetched via
1112    * GetFirstInputObject/NextInputObject or the last one if no object
1113    * specified.
1114    * @param pObject     pointer to TObject
1115    * @return data specification, kAliHLTVoidDataSpec if failed
1116    */
1117   AliHLTComponentDataType GetDataType(const TObject* pObject=NULL);
1118
1119   /**
1120    * Get data specification of an input block.
1121    * Get data specification of the object previously fetched via
1122    * GetFirstInputObject/NextInputObject or the last one if no object
1123    * specified.
1124    * @param pObject     pointer to TObject
1125    * @return data specification, kAliHLTVoidDataSpec if failed
1126    */
1127   AliHLTUInt32_t GetSpecification(const TObject* pObject=NULL);
1128
1129   /**
1130    * Get the first block of a specific data type from the input data.
1131    * The method looks for the first block of type dt in the input stream.
1132    * It is intended to be used within the high-level interface.<br>
1133    * \em Note: THE BLOCK DESCRIPTOR MUST NOT BE DELETED by the caller.
1134    *
1135    * If called without parameters, the function works on all input blocks,
1136    * also the ones of data type kAliHLTVoidDataType which are not matched by
1137    * kAliHLTAnyDataType.
1138    *
1139    * @param dt          data type of the block
1140    * @return pointer to @ref AliHLTComponentBlockData
1141    */
1142   const AliHLTComponentBlockData* GetFirstInputBlock(const AliHLTComponentDataType& dt=kAliHLTAllDataTypes);
1143
1144   /**
1145    * Get the first block of a specific data type from the input data.
1146    * The method looks for the first block of type specified by the ID and 
1147    * Origin strings in the input stream.  It is intended
1148    * to be used within the high-level interface.<br>
1149    * \em Note: THE BLOCK DESCRIPTOR MUST NOT BE DELETED by the caller.
1150    * @param dtID        data type ID of the block
1151    * @param dtOrigin    data type origin of the block
1152    * @return pointer to @ref AliHLTComponentBlockData
1153    */
1154   const AliHLTComponentBlockData* GetFirstInputBlock(const char* dtID, 
1155                                                       const char* dtOrigin);
1156
1157   /**
1158    * Get input block by index.<br>
1159    * \em Note: THE BLOCK DESCRIPTOR MUST NOT BE DELETED by the caller.
1160    * @return pointer to AliHLTComponentBlockData, NULL if index out of range
1161    */
1162   const AliHLTComponentBlockData* GetInputBlock(int index) const;
1163
1164   /**
1165    * Get the next block of a specific data type from the input data.
1166    * The method looks for the next block  of type and class specified
1167    * to the previous @ref GetFirstInputBlock call.
1168    * To be used within the high-level interface.<br>
1169    * \em Note: THE BLOCK DESCRIPTOR MUST NOT BE DELETED by the caller.
1170    */
1171   const AliHLTComponentBlockData* GetNextInputBlock();
1172
1173   /**
1174    * Get data specification of an input block.
1175    * Get data specification of the input block previously fetched via
1176    * GetFirstInputObject/NextInputObject or the last one if no block
1177    * specified.
1178    * @param pBlock     pointer to input block
1179    * @return data specification, kAliHLTVoidDataSpec if failed
1180    */
1181   AliHLTUInt32_t GetSpecification(const AliHLTComponentBlockData* pBlock);
1182
1183   /**
1184    * Forward an input object to the output.
1185    * Forward the input block of an object previously fetched via
1186    * GetFirstInputObject/NextInputObject or the last one if no object
1187    * specified.
1188    * The block descriptor of the input block is forwarded to the
1189    * output block list.
1190    * @param pObject     pointer to TObject
1191    * @return neg. error code if failed
1192    */
1193   int Forward(const TObject* pObject);
1194
1195   /**
1196    * Forward an input block to the output.
1197    * Forward the input block fetched via GetFirstInputObject/
1198    * NextInputBlock or the last one if no block specified.
1199    * The block descriptor of the input block is forwarded to the
1200    * output block list.
1201    * @param pBlock     pointer to input block
1202    * @return neg. error code if failed
1203    */
1204   int Forward(const AliHLTComponentBlockData* pBlock=NULL);
1205
1206   /**
1207    * Insert an object into the output.
1208    * If header is specified, it will be inserted before the root object,
1209    * default is no header.
1210    * The publishing can be downscaled by means of the -pushback-period
1211    * parameter. This is especially useful for histograms which do not
1212    * need to be sent for every event.
1213    * @param pObject     pointer to root object
1214    * @param dt          data type of the object
1215    * @param spec        data specification
1216    * @param pHeader     pointer to header
1217    * @param headerSize  size of Header
1218    * @return neg. error code if failed 
1219    */
1220   int PushBack(TObject* pObject, const AliHLTComponentDataType& dt, 
1221                AliHLTUInt32_t spec=kAliHLTVoidDataSpec, 
1222                void* pHeader=NULL, int headerSize=0);
1223
1224   /**
1225    * Insert an object into the output.
1226    * If header is specified, it will be inserted before the root object,
1227    * default is no header.
1228    * The publishing can be downscaled by means of the -pushback-period
1229    * parameter. This is especially useful for histograms which do not
1230    * need to be sent for every event.
1231    * @param pObject     pointer to root object
1232    * @param dtID        data type ID of the object
1233    * @param dtOrigin    data type origin of the object
1234    * @param spec        data specification
1235    * @param pHeader     pointer to header
1236    * @param headerSize  size of Header
1237    * @return neg. error code if failed 
1238    */
1239   int PushBack(TObject* pObject, const char* dtID, const char* dtOrigin,
1240                AliHLTUInt32_t spec=kAliHLTVoidDataSpec,
1241                void* pHeader=NULL, int headerSize=0);
1242  
1243   /**
1244    * Insert an object into the output.
1245    * @param pBuffer     pointer to buffer
1246    * @param iSize       size of the buffer
1247    * @param dt          data type of the object
1248    * @param spec        data specification
1249    * @param pHeader     pointer to header
1250    * @param headerSize size of Header
1251    * @return neg. error code if failed 
1252    */
1253   int PushBack(const void* pBuffer, int iSize, const AliHLTComponentDataType& dt,
1254                AliHLTUInt32_t spec=kAliHLTVoidDataSpec,
1255                const void* pHeader=NULL, int headerSize=0);
1256
1257   /**
1258    * Insert an object into the output.
1259    * @param pBuffer     pointer to buffer
1260    * @param iSize       size of the buffer
1261    * @param dtID        data type ID of the object
1262    * @param dtOrigin    data type origin of the object
1263    * @param spec        data specification
1264    * @param pHeader     pointer to header
1265    * @param headerSize size of Header
1266    * @return neg. error code if failed 
1267    */
1268   int PushBack(const void* pBuffer, int iSize, const char* dtID, const char* dtOrigin,
1269                AliHLTUInt32_t spec=kAliHLTVoidDataSpec,
1270                const void* pHeader=NULL, int headerSize=0);
1271
1272   /**
1273    * Estimate size of a TObject
1274    * @param pObject
1275    * @return buffer size in byte
1276    */
1277   int EstimateObjectSize(TObject* pObject) const;
1278
1279   /**
1280    * Create a memory file in the output stream.
1281    * This method creates a TFile object which stores all data in
1282    * memory instead of disk. The TFile object is published as binary data.
1283    * The instance can be used like a normal TFile object. The TFile::Close
1284    * or @ref CloseMemoryFile method has to be called in order to flush the
1285    * output stream.
1286    *
1287    * \b Note: The returned object is deleted by the framework.
1288    * @param capacity    total size reserved for the memory file
1289    * @param dtID        data type ID of the file
1290    * @param dtOrigin    data type origin of the file
1291    * @param spec        data specification
1292    * @return file handle, NULL if failed 
1293    */
1294   AliHLTMemoryFile* CreateMemoryFile(int capacity, const char* dtID, const char* dtOrigin,
1295                                      AliHLTUInt32_t spec=kAliHLTVoidDataSpec);
1296
1297   /**
1298    * Create a memory file in the output stream.
1299    * This method creates a TFile object which stores all data in
1300    * memory instead of disk. The TFile object is published as binary data.
1301    * The instance can be used like a normal TFile object. The TFile::Close
1302    * or @ref CloseMemoryFile method has to be called in order to flush the
1303    * output stream.
1304    *
1305    * \b Note: The returned object is deleted by the framework.
1306    * @param capacity    total size reserved for the memory file
1307    * @param dt          data type of the file
1308    * @param spec        data specification
1309    * @return file handle, NULL if failed 
1310    */
1311   AliHLTMemoryFile* CreateMemoryFile(int capacity, 
1312                                      const AliHLTComponentDataType& dt=kAliHLTAnyDataType,
1313                                      AliHLTUInt32_t spec=kAliHLTVoidDataSpec);
1314
1315   /**
1316    * Create a memory file in the output stream.
1317    * This method creates a TFile object which stores all data in
1318    * memory instead of disk. The TFile object is published as binary data.
1319    * The instance can be used like a normal TFile object. The TFile::Close
1320    * or @ref CloseMemoryFile method has to be called in order to flush the
1321    * output stream.
1322    *
1323    * \b Note: The returned object is deleted by the framework.
1324    * @param dtID        data type ID of the file
1325    * @param dtOrigin    data type origin of the file
1326    * @param spec        data specification
1327    * @param capacity    fraction of the available output buffer size
1328    * @return file handle, NULL if failed 
1329    */
1330   AliHLTMemoryFile* CreateMemoryFile(const char* dtID, const char* dtOrigin,
1331                                      AliHLTUInt32_t spec=kAliHLTVoidDataSpec,
1332                                      float capacity=1.0);
1333
1334   /**
1335    * Create a memory file in the output stream.
1336    * This method creates a TFile object which stores all data in
1337    * memory instead of disk. The TFile object is published as binary data.
1338    * The instance can be used like a normal TFile object. The TFile::Close
1339    * or @ref CloseMemoryFile method has to be called in order to flush the
1340    * output stream.
1341    *
1342    * \b Note: The returned object is deleted by the framework.
1343    * @param dt          data type of the file
1344    * @param spec        data specification
1345    * @param capacity    fraction of the available output buffer size
1346    * @return file handle, NULL if failed 
1347    */
1348   AliHLTMemoryFile* CreateMemoryFile(const AliHLTComponentDataType& dt=kAliHLTAnyDataType,
1349                                      AliHLTUInt32_t spec=kAliHLTVoidDataSpec,
1350                                      float capacity=1.0);
1351
1352   /**
1353    * Write an object to memory file in the output stream.
1354    * @param pFile       file handle
1355    * @param pObject     pointer to root object
1356    * @param key         key in ROOT file
1357    * @param option      options, see TObject::Write
1358    * @return neg. error code if failed
1359    *         - -ENOSPC    no space left
1360    */
1361   int Write(AliHLTMemoryFile* pFile, const TObject* pObject, const char* key=NULL, int option=TObject::kOverwrite);
1362
1363   /**
1364    * Close object memory file.
1365    * @param pFile       file handle
1366    * @return neg. error code if failed
1367    *         - -ENOSPC    buffer size too small
1368    */
1369   int CloseMemoryFile(AliHLTMemoryFile* pFile);
1370
1371   /**
1372    * Insert event-done data information into the output.
1373    * @param edd          event-done data information
1374    */
1375   int CreateEventDoneData(AliHLTComponentEventDoneData edd);
1376
1377   /**
1378    * Get current run number
1379    */
1380   AliHLTUInt32_t GetRunNo() const;
1381
1382   /**
1383    * Get the current run type.
1384    */
1385   AliHLTUInt32_t GetRunType() const;
1386
1387   /**
1388    * Get the chain id of the component.
1389    */
1390   const char* GetChainId() const {return fChainId.c_str();}
1391
1392   /**
1393    * Get a timestamp of the current event
1394    * Exact format needs to be documented.
1395    */
1396   AliHLTUInt32_t    GetTimeStamp() const;
1397
1398   /**
1399    * Get the period number.
1400    * Upper 28 bits (36 to 63) of the 64-bit event id 
1401    */
1402   AliHLTUInt32_t    GetPeriodNumber() const;
1403
1404   /**
1405    * Get the period number.
1406    * 24 bits, 12 to 35 of the 64-bit event id 
1407    */
1408   AliHLTUInt32_t    GetOrbitNumber() const;
1409
1410   /**
1411    * Get the bunch crossing number.
1412    * 12 bits, 0 to 12 of the 64-bit event id 
1413    */
1414   AliHLTUInt16_t    GetBunchCrossNumber() const;
1415
1416   /**
1417    * Setup the CTP accounting functionality of the base class.
1418    * The method can be invoked from DoInit() for componenets which want to
1419    * use the CTP functionality of the base class.
1420    *
1421    * The AliHLTCTPData is initialized with the trigger classes from the ECS
1422    * parameters. The base class automatically increments the counters according
1423    * to the trigger pattern in the CDH before the event processing. 
1424    */
1425   int SetupCTPData();
1426
1427   /**
1428    * Get the instance of the CTP data.
1429    */
1430   const AliHLTCTPData* CTPData() const {return fpCTPData;}
1431
1432   /**
1433    * Check whether a combination of trigger classes is fired.
1434    * The expression can contain trigger class ids and logic operators
1435    * like &&, ||, !, and ^, and may be grouped by parentheses.
1436    * @note the function requires the setup of the CTP handling for the component by
1437    * invoking SetupCTPData() from DoInit()
1438    * @param expression     a logic expression of trigger class ids
1439    * @param trigData       the trigger data data
1440    */
1441   bool EvaluateCTPTriggerClass(const char* expression, AliHLTComponentTriggerData& trigData) const;
1442
1443   /**
1444    * Check state of a trigger class.
1445    * If the class name is not part of the current trigger setup (i.e. ECS parameter
1446    * does not contain a trigger definition for this class name) the function
1447    * returns -1
1448    * @note the function requires the setup of the CTP handling for the component by
1449    * invoking SetupCTPData() from DoInit()
1450    * @return -1 class name not initialized, 
1451    *          0 trigger not active
1452    *          1 trigger active
1453    */
1454   int CheckCTPTrigger(const char* name) const;
1455
1456   /**
1457    * Get the overall solenoid field.
1458    */
1459   Double_t GetBz();
1460   /**
1461    * Get the solenoid field at point r.
1462    */
1463   Double_t GetBz(const Double_t *r);
1464   /**
1465    * Get the solenoid field components at point r.
1466    */
1467   void GetBxByBz(const Double_t r[3], Double_t b[3]);
1468
1469   /**
1470    * Check whether the current event is a valid data event.
1471    * @param pTgt    optional pointer to get the event type
1472    * @return true if the current event is a real data event
1473    */
1474   bool IsDataEvent(AliHLTUInt32_t* pTgt=NULL) const;
1475
1476   /**
1477    * Set a bit to 1 in a readout list ( = AliHLTEventDDL )
1478    * -> enable DDL for readout
1479    * @param list        readout list
1480    * @param ddlId       DDL Id to be turned on ( Decimal )
1481    */
1482   void EnableDDLBit(AliHLTEventDDL &list, Int_t ddlId ) const {
1483     SetDDLBit( list, ddlId, kTRUE ); 
1484   }
1485
1486   /**
1487    * Set a bit to 0 in a readout list ( = AliHLTEventDDL )
1488    * -> disable DDL for readout
1489    * @param list        readout list
1490    * @param ddlId       DDL Id to be turned on ( Decimal )
1491    */
1492   void DisableDDLBit(AliHLTEventDDL &list, Int_t ddlId ) const { 
1493     SetDDLBit( list, ddlId, kFALSE );  
1494   }
1495   
1496   /**
1497    * Set or unset  bit a readout list ( = AliHLTEventDDL )
1498    * -> enable or disable DDL for readout
1499    * @param list        readout list
1500    * @param ddlId       DDL Id to be turned on ( Decimal )
1501    * @param state       kTRUE sets it, kFALSE unsets it
1502    */
1503   void SetDDLBit(AliHLTEventDDL &list, Int_t ddlId, Bool_t state ) const;
1504   
1505   /**
1506    * Get the first word of a detector, which has a set DDL bit. 
1507    * Beware, this only works if DDLs of 1 detector are set. In the 
1508    * case of the TPC and TOF, which use 8 and 3 words, the first 
1509    * word is returned.
1510    * @param list        readout list
1511    * @return            returns the detector index, -1 if no bit is set
1512    *                    at all or several detectors (=error)
1513    */
1514   Int_t GetFirstUsedDDLWord(AliHLTEventDDL &list) const;
1515
1516   /**
1517    * Copy a struct from block data.
1518    * The function checks for block size and struct size. The least common
1519    * size will be copied to the target struct, remaining fields are initialized
1520    * to zero.<br>
1521    * The target struct must have a 32bit struct size indicator as first member.
1522    * @param pStruct     target struct
1523    * @param iStructSize size of the struct
1524    * @param iBlockNo    index of input block
1525    * @param structname  name of the struct (log messages)
1526    * @param eventname   name of the event (log messages)
1527    * @return size copied, neg. error if failed
1528    */
1529   int CopyStruct(void* pStruct, unsigned int iStructSize, unsigned int iBlockNo,
1530                  const char* structname="", const char* eventname="");
1531
1532  private:
1533   /** copy constructor prohibited */
1534   AliHLTComponent(const AliHLTComponent&);
1535   /** assignment operator prohibited */
1536   AliHLTComponent& operator=(const AliHLTComponent&);
1537
1538   /**
1539    * Increment the internal event counter.
1540    * To be used by the friend classes AliHLTProcessor, AliHLTDataSource
1541    * and AliHLTDataSink.
1542    * @return new value of the internal event counter
1543    * @internal
1544    */
1545   int IncrementEventCounter();
1546
1547   /**
1548    * Find the first input block of specified data type beginning at index.
1549    * Input blocks containing a TObject have the size of the object as an
1550    * unsigned 32 bit number in the first 4 bytes. This has to match the block
1551    * size minus 4.
1552    *
1553    * kAliHLTAllDataTypes is a special data type which includes both 
1554    * kAliHLTVoidDataType and kAliHLTAnyDataType.
1555    *
1556    * @param dt          data type
1557    * @param startIdx    index to start the search
1558    * @param bObject     check if this is an object
1559    * @return index of the block, -ENOENT if no block found
1560    *
1561    * @internal
1562    */
1563   int FindInputBlock(const AliHLTComponentDataType& dt, int startIdx=-1, int bObject=0) const;
1564
1565   /**
1566    * Get index in the array of input bocks.
1567    * Calculate index and check integrety of a block data structure pointer.
1568    * @param pBlock      pointer to block data
1569    * @return index of the block, -ENOENT if no block found
1570    *
1571    * @internal
1572    */
1573   int FindInputBlock(const AliHLTComponentBlockData* pBlock) const;
1574
1575   /**
1576    * Create an object from a specified input block.
1577    * @param idx         index of the input block
1578    * @param bForce      force the retrieval of an object, error messages
1579    *                    are suppressed if \em bForce is not set
1580    * @return pointer to TObject, caller must delete the object after use
1581    *
1582    * @internal
1583    */
1584   TObject* CreateInputObject(int idx, int bForce=0);
1585
1586   /**
1587    * Get input object
1588    * Get object from the input block list. The methods first checks whether the
1589    * object was already created. If not, it is created by @ref CreateInputObject
1590    * and inserted into the list of objects.
1591    * @param idx         index in the input block list
1592    * @param classname   name of the class, object is checked for correct class
1593    *                    name if set
1594    * @param bForce      force the retrieval of an object, error messages
1595    *                    are suppressed if \em bForce is not set
1596    * @return pointer to TObject
1597    *
1598    * @internal
1599    */
1600   TObject* GetInputObject(int idx, const char* classname=NULL, int bForce=0);
1601
1602   /**
1603    * Clean the list of input objects.
1604    * Cleanup is done at the end of each event processing.
1605    */
1606   int CleanupInputObjects();
1607
1608   /**
1609    * Insert a buffer into the output block stream.
1610    * This is the only method to insert blocks into the output stream, called
1611    * from all types of the Pushback method. The actual data might have been
1612    * written to the output buffer already. In that case NULL can be provided
1613    * as buffer, only the block descriptor will be build. If a header is specified, 
1614    * it will be inserted before the buffer, default is no header.
1615    * @param pBuffer     pointer to buffer
1616    * @param iBufferSize size of the buffer in byte
1617    * @param dt          data type
1618    * @param spec        data specification
1619    * @param pHeader     pointer to header
1620    * @param iHeaderSize size of Header
1621    * @return neg. error code if failed
1622    */
1623   int InsertOutputBlock(const void* pBuffer, int iBufferSize,
1624                         const AliHLTComponentDataType& dt,
1625                         AliHLTUInt32_t spec,
1626                         const void* pHeader=NULL, int iHeaderSize=0);
1627
1628   /**
1629    * Add a component statistics block to the output.
1630    * @return size of the added data
1631    */
1632   int AddComponentStatistics(AliHLTComponentBlockDataList& blocks, 
1633                              AliHLTUInt8_t* buffer,
1634                              AliHLTUInt32_t bufferSize,
1635                              AliHLTUInt32_t offset,
1636                              AliHLTComponentStatisticsList& stats) const;
1637
1638   /**
1639    * Add a component table entry (descriptor) to the output
1640    * This is done at SOR/EOR. The component table is a list of chain ids
1641    * and 32bit ids calculated by a crc algorithm from the chian id. This
1642    * allows to tag data blocks with the id number rather than the string.
1643    *
1644    * The kAliHLTDataTypeComponentTable data block currently has the string
1645    * as payload and the crc id as specification.
1646    * @return size of the added data
1647    */
1648   int  AddComponentTableEntry(AliHLTComponentBlockDataList& blocks, 
1649                               AliHLTUInt8_t* buffer,
1650                               AliHLTUInt32_t bufferSize,
1651                               AliHLTUInt32_t offset,
1652                               const vector<AliHLTUInt32_t>& parents) const;
1653
1654   /**
1655    * Scan the ECS parameter string.
1656    * The framework provides both the parameters of CONFIGURE and ENGAGE
1657    * in one string in a special data block kAliHLTDataTypeECSParam
1658    * {ECSPARAM:PRIV}. The general format is
1659    * <command>;<parameterkey>=<parametervalue>;<parameterkey>=<parametervalue>;...
1660    */
1661   int ScanECSParam(const char* ecsParam);
1662
1663   /**
1664    * The trigger classes are determined from the trigger and propagated by
1665    * ECS as part of the ENGAGE command parameter which is sent through the
1666    * framework during the SOR event. This function treats the value of the
1667    * parameter key CTP_TRIGGER_CLASS.
1668    */
1669   int InitCTPTriggerClasses(const char* ctpString);
1670
1671   enum {
1672     kRequireSteeringBlocks = 0x1,
1673     kDisableComponentStat = 0x2
1674   };
1675
1676   /** The global component handler instance */
1677   static AliHLTComponentHandler* fgpComponentHandler;              //! transient
1678
1679   /** The environment where the component is running in */
1680   AliHLTAnalysisEnvironment fEnvironment;                         // see above
1681
1682   /** Set by ProcessEvent before the processing starts */
1683   AliHLTEventID_t fCurrentEvent;                                   // see above
1684
1685   /** internal event no */
1686   int fEventCount;                                                 // see above
1687
1688   /** the number of failed events */
1689   int fFailedEvents;                                               // see above
1690
1691   /** event data struct of the current event under processing */
1692   AliHLTComponentEventData fCurrentEventData;                      // see above
1693
1694   /** array of input data blocks of the current event */
1695   const AliHLTComponentBlockData* fpInputBlocks;                   //! transient
1696
1697   /** index of the current input block */
1698   int fCurrentInputBlock;                                          // see above
1699
1700   /** data type of the last block search */
1701   AliHLTComponentDataType fSearchDataType;                         // see above
1702
1703   /** name of the class for the object to search for */
1704   string fClassName;                                               // see above
1705
1706   /** array of generated input objects */
1707   TObjArray* fpInputObjects;                                       //! transient
1708  
1709   /** the output buffer */
1710   AliHLTUInt8_t* fpOutputBuffer;                                   //! transient
1711
1712   /** size of the output buffer */
1713   AliHLTUInt32_t fOutputBufferSize;                                // see above
1714
1715   /** size of data written to output buffer */
1716   AliHLTUInt32_t fOutputBufferFilled;                              // see above
1717
1718   /** list of ouput block data descriptors */
1719   AliHLTComponentBlockDataList fOutputBlocks;                      // see above
1720
1721   /** stopwatch array */
1722   TObjArray* fpStopwatches;                                        //! transient
1723
1724   /** array of memory files AliHLTMemoryFile */
1725   AliHLTMemoryFilePList fMemFiles;                                 //! transient
1726
1727   /** descriptor of the current run */
1728   AliHLTRunDesc* fpRunDesc;                                        //! transient
1729
1730   /** the current DDL list */
1731   AliHLTEventDDL* fpDDLList;                                       //! transient
1732
1733   /** external fct to set CDB run no, indicates external CDB initialization */
1734   void (*fCDBSetRunNoFunc)();                                      //! transient
1735
1736   /** id of the component in the analysis chain */
1737   string fChainId;                                                 //! transient
1738
1739   /** crc value of the chainid, used as a 32bit id */
1740   AliHLTUInt32_t fChainIdCrc;                                      //! transient
1741
1742   /** optional benchmarking for the component statistics */
1743   TStopwatch* fpBenchmark;                                         //! transient
1744
1745   /** component flags, cleared in Deinit */
1746   AliHLTUInt32_t fFlags;                                           //! transient
1747
1748   /** current event type */
1749   AliHLTUInt32_t fEventType;                                       //! transient
1750
1751   /** component arguments */
1752   string fComponentArgs;                                           //! transient
1753
1754
1755   /** event done data */
1756   AliHLTComponentEventDoneData* fEventDoneData;                    //! transient
1757
1758   /** Reserved size of the memory stored at fEventDoneData */
1759   unsigned long fEventDoneDataSize;                                //! transient
1760
1761   /** Comression level for ROOT objects */
1762   int fCompressionLevel;                                           //! transient
1763
1764   /** size of last PushBack-serialized object */
1765   int fLastObjectSize;                                             //! transient
1766
1767  /**  array of trigger class descriptors */
1768   AliHLTCTPData* fpCTPData;                                        //! transient
1769
1770   /// update period for PushBack calls
1771   int fPushbackPeriod;                                             //! transient
1772   /// time of last executed PushBack
1773   int fLastPushBackTime;                                           //! transient
1774
1775   ClassDef(AliHLTComponent, 14)
1776 };
1777 #endif