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