high-level component interface added
[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  * @subsubsection alihltcomponent-high-level-int-guidelines High-level interface guidelines
147  * - Structures must inherit from the ROOT object base class TObject in order be 
148  * transported by the transportation framework.
149  * - all pointer members must be transient (marked <tt>//!</tt> behind the member
150  * definition), i.e. will not be stored/transported, or properly marked
151  * (<tt>//-></tt>) in order to call the streamer of the object the member is pointing
152  * to. The latter is not recomended. Structures to be transported between components
153  * should be streamlined.
154  * - no use of stl vectors/strings, use appropriate ROOT classes instead 
155  * 
156  * @subsection alihltcomponent-low-level-interface Low-level interface
157  * The low-level component interface consists of the specific data processing
158  * methods for @ref AliHLTProcessor, @ref AliHLTDataSource, and @ref AliHLTDataSink.
159  * - @ref AliHLTProcessor::DoEvent
160  * - @ref AliHLTDataSource::GetEvent
161  * - @ref AliHLTDataSink::DumpEvent
162  * 
163  * 
164  * @section alihltcomponent-handling Component handling 
165  * The handling of HLT analysis components is carried out by the AliHLTComponentHandler.
166  * Component are registered automatically at load-time of the component shared library
167  * under the following suppositions:
168  * - the component library has to be loaded from the AliHLTComponentHandler using the
169  *   @ref AliHLTComponentHandler::LoadLibrary method.
170  * - the component implementation defines one global object (which is generated
171  *   when the library is loaded)
172  *
173  * @subsection alihltcomponent-design-rules General design considerations
174  * The analysis code should be implemented in one or more destict class(es). A 
175  * \em component should be implemented which interface the destict analysis code to the
176  * component interface. This component generates the analysis object dynamically. <br>
177  *
178  * Assume you have an implemetation <tt> AliHLTDetMyAnalysis </tt>, another class <tt>
179  * AliHLTDetMyAnalysisComponent </tt> contains:
180  * <pre>
181  * private:
182  *   AliHLTDetMyAnalysis* fMyAnalysis;  //!
183  * </pre>
184  * The object should then be instantiated in the DoInit handler of 
185  * <tt>AliHLTDetMyAnalysisComponent </tt>, and cleaned in the DoDeinit handler.
186  *
187  * Further rules:
188  * - avoid big static arrays in the component, allocate the memory at runtime
189  *
190  * @ingroup alihlt_component
191  * @section alihltcomponent-members Class members
192  */
193 class AliHLTComponent : public AliHLTLogging {
194  public:
195   /** standard constructor */
196   AliHLTComponent();
197   /** not a valid copy constructor, defined according to effective C++ style */
198   AliHLTComponent(const AliHLTComponent&);
199   /** not a valid assignment op, but defined according to effective C++ style */
200   AliHLTComponent& operator=(const AliHLTComponent&);
201   /** standard destructor */
202   virtual ~AliHLTComponent();
203
204   /** component type definitions */
205   enum TComponentType { kUnknown=0, kSource=1, kProcessor=2, kSink=3 };
206
207   /**
208    * Init function to prepare data processing.
209    * Initialization of common data structures for a sequence of events.
210    * The call is redirected to the internal method @ref DoInit which can be
211    * overridden by the child class.<br>
212    * During Init also the environment structure is passed to the component.
213    * @param environ        environment pointer with environment dependend function
214    *                       calls
215    * @param environParam   additionel parameter for function calls, the pointer
216    *                       is passed as it is
217    * @param argc           size of the argument array
218    * @param argv           agument array for component initialization
219    */
220   virtual int Init( AliHLTComponentEnvironment* environ, void* environParam, int argc, const char** argv );
221
222   /**
223    * Clean-up function to terminate data processing.
224    * Clean-up of common data structures after data processing.
225    * The call is redirected to the internal method @ref DoDeinit which can be
226    * overridden by the child class.
227    */
228   virtual int Deinit();
229
230   /**
231    * Processing of one event.
232    * The method is the entrance of the event processing. The parameters are
233    * cached for uses with the high-level interface and the DoProcessing
234    * implementation is called.
235    *
236    * @param evtData
237    * @param blocks
238    * @param trigData
239    * @param outputPtr
240    * @param size
241    * @param outputBlockCnt  out: size of the output block array, set by the component
242    * @param outputBlocks    out: the output block array is allocated internally
243    * @param edd
244    * @return neg. error code if failed
245    */
246   int ProcessEvent( const AliHLTComponentEventData& evtData, const AliHLTComponentBlockData* blocks, 
247                             AliHLTComponentTriggerData& trigData, AliHLTUInt8_t* outputPtr, 
248                             AliHLTUInt32_t& size, AliHLTUInt32_t& outputBlockCnt, 
249                             AliHLTComponentBlockData*& outputBlocks,
250                             AliHLTComponentEventDoneData*& edd );
251
252   /**
253    * Internal processing of one event.
254    * The method is pure virtual and implemented by the child classes 
255    * - @ref AliHLTProcessor
256    * - @ref AliHLTDataSource
257    * - @ref AliHLTDataSink
258    *
259    * @param evtData
260    * @param blocks
261    * @param trigData
262    * @param outputPtr
263    * @param size
264    * @param outputBlocks    out: the output block array is allocated internally
265    * @param edd
266    * @return neg. error code if failed
267    */
268   virtual int DoProcessing( const AliHLTComponentEventData& evtData, const AliHLTComponentBlockData* blocks, 
269                             AliHLTComponentTriggerData& trigData, AliHLTUInt8_t* outputPtr, 
270                             AliHLTUInt32_t& size,
271                             vector<AliHLTComponentBlockData>& outputBlocks,
272                             AliHLTComponentEventDoneData*& edd ) = 0;
273
274   // Information member functions for registration.
275
276   /**
277    * Get the type of the component.
278    * The function is pure virtual and must be implemented by the child class.
279    * @return component type id
280    */
281   virtual TComponentType GetComponentType() = 0; // Source, sink, or processor
282
283   /**
284    * Get the id of the component.
285    * Each component is identified by a unique id.
286    * The function is pure virtual and must be implemented by the child class.
287    * @return component id (string)
288    */
289   virtual const char* GetComponentID() = 0;
290
291   /**
292    * Get the input data types of the component.
293    * The function is pure virtual and must be implemented by the child class.
294    * @return list of data types in the vector reference
295    */
296   virtual void GetInputDataTypes( vector<AliHLTComponentDataType>& ) = 0;
297
298   /**
299    * Get the output data type of the component.
300    * The function is pure virtual and must be implemented by the child class.
301    * @return output data type
302    */
303   virtual AliHLTComponentDataType GetOutputDataType() = 0;
304
305   /**
306    * Get a ratio by how much the data volume is shrinked or enhanced.
307    * The function is pure virtual and must be implemented by the child class.
308    * @param constBase        <i>return</i>: additive part, independent of the
309    *                                   input data volume  
310    * @param inputMultiplier  <i>return</i>: multiplication ratio
311    * @return values in the reference variables
312    */
313   virtual void GetOutputDataSize( unsigned long& constBase, double& inputMultiplier ) = 0;
314
315   /**
316    * Spawn function.
317    * Each component must implement a spawn function to create a new instance of 
318    * the class. Basically the function must return <i>new <b>my_class_name</b></i>.
319    * @return new class instance
320    */
321   virtual AliHLTComponent* Spawn() = 0;
322
323   /**
324    * Find matching data types between this component and a consumer component.
325    * Currently, a component can produce only one type of data. This restriction is most
326    * likely to be abolished in the future.
327    * @param pConsumer a component and consumer of the data produced by this component
328    * @param tgtList   reference to a vector list to receive the matching data types.
329    * @return >= 0 success, neg. error code if failed
330    */ 
331   int FindMatchingDataTypes(AliHLTComponent* pConsumer, vector<AliHLTComponentDataType>* tgtList);
332  
333   /**
334    * Set the global component handler.
335    * The static method is needed for the automatic registration of components. 
336    */
337   static int SetGlobalComponentHandler(AliHLTComponentHandler* pCH, int bOverwrite=0);
338
339   /**
340    * Clear the global component handler.
341    * The static method is needed for the automatic registration of components. 
342    */
343   static int UnsetGlobalComponentHandler();
344
345   /**
346    * Helper function to convert the data type to a string.
347    */
348   static string DataType2Text( const AliHLTComponentDataType& type );
349
350   /**
351    * helper function to initialize AliHLTComponentEventData structure
352    */
353   static void FillEventData(AliHLTComponentEventData& evtData);
354
355   /**
356    * Print info on an AliHLTComponentDataType structure
357    * This is just a helper function to examine an @ref AliHLTComponentDataType
358    * structur.
359    */
360   void PrintComponentDataTypeInfo(const AliHLTComponentDataType& dt);
361
362
363  protected:
364
365   /**
366    * Fill AliHLTComponentBlockData structure with default values.
367    * @param blockData   reference to data structure
368    */
369   void FillBlockData( AliHLTComponentBlockData& blockData ) const;
370
371   /**
372    * Fill AliHLTComponentShmData structure with default values.
373    * @param shmData   reference to data structure
374    */
375   void FillShmData( AliHLTComponentShmData& shmData ) const;
376
377   /**
378    * Fill AliHLTComponentDataType structure with default values.
379    * @param dataType   reference to data structure
380    */
381   void FillDataType( AliHLTComponentDataType& dataType ) const;
382   
383   /**
384    * Copy data type structure
385    * Copies the value an AliHLTComponentDataType structure to another one
386    * @param[out] tgtdt   target structure
387    * @param[in] srcdt   source structure
388    */
389   void CopyDataType(AliHLTComponentDataType& tgtdt, const AliHLTComponentDataType& srcdt);
390
391   /**
392    * Set the ID and Origin of an AliHLTComponentDataType structure.
393    * The function sets the fStructureSize member and copies the strings
394    * to the ID and Origin. Only characters from the valid part of the string
395    * are copied, the rest is fille with 0's.
396    * Please note that the fID and fOrigin members are not strings, just arrays of
397    * chars of size @ref kAliHLTComponentDataTypefIDsize and
398    * @ref kAliHLTComponentDataTypefOriginSize respectively and not necessarily with
399    * a terminating zero.
400    * @param tgtdt   target data type structure
401    * @param id      ID string
402    * @param origin  Origin string
403    */
404   void SetDataType(AliHLTComponentDataType& tgtdt, const char* id, const char* origin);
405
406   /**
407    * Default method for the internal initialization.
408    * The method is called by @ref Init
409    */
410   virtual int DoInit( int argc, const char** argv );
411
412   /**
413    * Default method for the internal clean-up.
414    * The method is called by @ref Deinit
415    */
416   virtual int DoDeinit();
417
418   /**
419    * General memory allocation method.
420    * All memory which is going to be used 'outside' of the interface must
421    * be provided by the framework (online or offline).
422    * The method is redirected to a function provided by the current
423    * framework. Function pointers are transferred via the @ref
424    * AliHLTComponentEnvironment structure.
425    */
426   void* AllocMemory( unsigned long size );
427
428   /**
429    * Helper function to create a monolithic BlockData description block out
430    * of a list BlockData descriptors.
431    * For convenience, inside the interface vector lists are used, to make the
432    * interface pure C style, monilithic blocks must be exchanged. 
433    * The method is redirected to a function provided by the current
434    * framework. Function pointers are transferred via the @ref
435    * AliHLTComponentEnvironment structure.
436    */
437   int MakeOutputDataBlockList( const vector<AliHLTComponentBlockData>& blocks, AliHLTUInt32_t* blockCount,
438                                AliHLTComponentBlockData** outputBlocks );
439
440   /**
441    * Fill the EventDoneData structure.
442    * The method is redirected to a function provided by the current
443    * framework. Function pointers are transferred via the @ref
444    * AliHLTComponentEnvironment structure.
445    */
446   int GetEventDoneData( unsigned long size, AliHLTComponentEventDoneData** edd );
447
448   /**
449    * Helper function to convert the data type to a string.
450    */
451   void DataType2Text(const AliHLTComponentDataType& type, char output[kAliHLTComponentDataTypefIDsize+kAliHLTComponentDataTypefOriginSize+2]) const;
452
453   /**
454    * Get event number.
455    * @return value of the internal event counter
456    */
457   int GetEventCount() const;
458
459   /**
460    * Get the number of input blocks.
461    * @return number of input blocks
462    */
463   int GetNumberOfInputBlocks();
464
465   /**
466    * Get the first object of a specific data type from the input data.
467    * The hight-level methods provide functionality to transfer ROOT data
468    * structures which inherit from TObject.
469    * The method looks for the first ROOT object of type dt in the input stream.
470    * If also the class name is provided, the object is checked for the right
471    * class type. The input data block needs a certain structure, namely the 
472    * buffer size as first word. If the cross check fails, the retrieval is
473    * silently abondoned, unless the \em bForce parameter is set.
474    * @param dt          data type of the object
475    * @param classname   class name of the object
476    * @param bForce      force the retrieval of an object, error messages
477    *                    are suppressed if \em bForce is not set
478    * @return pointer to @ref TObject, NULL if no objects of specified type
479    *         available
480    */
481   const TObject* GetFirstInputObject(const AliHLTComponentDataType& dt=kAliHLTAnyDataType,
482                                      const char* classname=NULL,
483                                      int bForce=0);
484
485   /**
486    * Get the first object of a specific data type from the input data.
487    * The hight-level methods provide functionality to transfer ROOT data
488    * structures which inherit from TObject.
489    * The method looks for the first ROOT object of type specified by the ID and 
490    * Origin strings in the input stream.
491    * If also the class name is provided, the object is checked for the right
492    * class type. The input data block needs a certain structure, namely the 
493    * buffer size as first word. If the cross check fails, the retrieval is
494    * silently abondoned, unless the \em bForce parameter is set.
495    * @param dtID        data type ID of the object
496    * @param dtOrigin    data type origin of the object
497    * @param classname   class name of the object
498    * @param bForce      force the retrieval of an object, error messages
499    *                    are suppressed if \em bForce is not set
500    * @return pointer to @ref TObject, NULL if no objects of specified type
501    *         available
502    */
503   const TObject* GetFirstInputObject(const char* dtID, 
504                                      const char* dtOrigin,
505                                      const char* classname=NULL,
506                                      int bForce=0);
507
508   /**
509    * Get the next object of a specific data type from the input data.
510    * The hight-level methods provide functionality to transfer ROOT data
511    * structures which inherit from TObject.
512    * The method looks for the next ROOT object of type and class specified
513    * to the previous @ref GetFirstInputObject call.
514    * @param bForce      force the retrieval of an object, error messages
515    *                    are suppressed if \em bForce is not set
516    * @return pointer to @ref TObject, NULL if no more objects available
517    */
518   const TObject* GetNextInputObject(int bForce=0);
519
520   /**
521    * Get data type of an input block.
522    * Get data type of the object previously fetched via
523    * GetFirstInputObject/NextInputObject or the last one if no object
524    * specified.
525    * @param pObject     pointer to TObject
526    * @return data specification, kAliHLTVoidDataSpec if failed
527    */
528   AliHLTComponentDataType GetDataType(const TObject* pObject=NULL);
529
530   /**
531    * Get data specification of an input block.
532    * Get data specification of the object previously fetched via
533    * GetFirstInputObject/NextInputObject or the last one if no object
534    * specified.
535    * @param pObject     pointer to TObject
536    * @return data specification, kAliHLTVoidDataSpec if failed
537    */
538   AliHLTUInt32_t GetSpecification(const TObject* pObject=NULL);
539
540   /**
541    * Get the first block of a specific data type from the input data.
542    * The method looks for the first block of type dt in the input stream. It is intended
543    * to be used within the high-level interface.
544    * @param dt          data type of the block
545    * @return pointer to @ref AliHLTComponentBlockData
546    */
547   const AliHLTComponentBlockData* GetFirstInputBlock(const AliHLTComponentDataType& dt=kAliHLTAnyDataType);
548
549   /**
550    * Get the first block of a specific data type from the input data.
551    * The method looks for the first block of type specified by the ID and 
552    * Origin strings in the input stream.  It is intended
553    * to be used within the high-level interface.
554    * @param dtID        data type ID of the block
555    * @param dtOrigin    data type origin of the block
556    * @return pointer to @ref AliHLTComponentBlockData
557    */
558   const AliHLTComponentBlockData* GetFirstInputBlock(const char* dtID, 
559                                                       const char* dtOrigin);
560
561   /**
562    * Get input block by index
563    * @return pointer to AliHLTComponentBlockData, NULL if index out of range
564    */
565   const AliHLTComponentBlockData* GetInputBlock(int index);
566
567   /**
568    * Get the next block of a specific data type from the input data.
569    * The method looks for the next block  of type and class specified
570    * to the previous @ref GetFirstInputBlock call.
571    * To be used within the high-level interface.
572    */
573   const AliHLTComponentBlockData* GetNextInputBlock();
574
575   /**
576    * Get data specification of an input block.
577    * Get data specification of the input bblock previously fetched via
578    * GetFirstInputObject/NextInputObject or the last one if no block
579    * specified.
580    * @param pBlock     pointer to input block
581    * @return data specification, kAliHLTVoidDataSpec if failed
582    */
583   AliHLTUInt32_t GetSpecification(const AliHLTComponentBlockData* pBlock=NULL);
584
585   /**
586    * Insert an object into the output.
587    * @param pObject     pointer to root object
588    * @param dt          data type of the object
589    * @param spec        data specification
590    * @return neg. error code if failed 
591    */
592   int PushBack(TObject* pObject, const AliHLTComponentDataType& dt, 
593                AliHLTUInt32_t spec=kAliHLTVoidDataSpec);
594
595   /**
596    * Insert an object into the output.
597    * @param pObject     pointer to root object
598    * @param dtID        data type ID of the object
599    * @param dtOrigin    data type origin of the object
600    * @param spec        data specification
601    * @return neg. error code if failed 
602    */
603   int PushBack(TObject* pObject, const char* dtID, const char* dtOrigin,
604                AliHLTUInt32_t spec=kAliHLTVoidDataSpec);
605
606   /**
607    * Insert an object into the output.
608    * @param pBuffer     pointer to buffer
609    * @param iSize       size of the buffer
610    * @param dt          data type of the object
611    * @param spec        data specification
612    * @return neg. error code if failed 
613    */
614   int PushBack(void* pBuffer, int iSize, const AliHLTComponentDataType& dt,
615                AliHLTUInt32_t spec=kAliHLTVoidDataSpec);
616
617   /**
618    * Insert an object into the output.
619    * @param pBuffer     pointer to buffer
620    * @param iSize       size of the buffer
621    * @param dtID        data type ID of the object
622    * @param dtOrigin    data type origin of the object
623    * @param spec        data specification
624    * @return neg. error code if failed 
625    */
626   int PushBack(void* pBuffer, int iSize, const char* dtID, const char* dtOrigin,
627                AliHLTUInt32_t spec=kAliHLTVoidDataSpec);
628
629   /**
630    * Insert event-done data information into the output.
631    * @param edd          event-done data information
632    */
633   int CreateEventDoneData(AliHLTComponentEventDoneData edd);
634
635  private:
636   /**
637    * Increment the internal event counter.
638    * To be used by the friend classes AliHLTProcessor, AliHLTDataSource
639    * and AliHLTDataSink.
640    * @return new value of the internal event counter
641    * @internal
642    */
643   int IncrementEventCounter();
644
645   /**
646    * Find the first input block of specified data type beginning at index.
647    * @param dt          data type
648    * @param startIdx    index to start the search
649    * @return index of the block, -ENOENT if no block found
650    *
651    * @internal
652    */
653   int FindInputBlock(const AliHLTComponentDataType& dt, int startIdx=-1);
654
655   /**
656    * Get index in the array of input bocks.
657    * Calculate index and check integrety of a block data structure pointer.
658    * @param pBlock      pointer to block data
659    * @return index of the block, -ENOENT if no block found
660    *
661    * @internal
662    */
663   int FindInputBlock(const AliHLTComponentBlockData* pBlock);
664
665   /**
666    * Create an object from a specified input block.
667    * @param idx         index of the input block
668    * @param bForce      force the retrieval of an object, error messages
669    *                    are suppressed if \em bForce is not set
670    * @return pointer to TObject, caller must delete the object after use
671    *
672    * @internal
673    */
674   TObject* CreateInputObject(int idx, int bForce=0);
675
676   /**
677    * Get input object
678    * Get object from the input block list
679    * @param idx         index in the input block list
680    * @param classname   name of the class, object is checked for correct class
681    *                    name if set
682    * @param bForce      force the retrieval of an object, error messages
683    *                    are suppressed if \em bForce is not set
684    * @return pointer to TObject
685    *
686    * @internal
687    */
688   TObject* GetInputObject(int idx, const char* classname=NULL, int bForce=0);
689
690   /**
691    * Insert a buffer into the output block stream.
692    * This is the only method to insert blocks into the output stream, called
693    * from all types of the Pushback method. The actual data might have been
694    * written to the output buffer already. In that case NULL can be provided
695    * as buffer, only the block descriptor will be build.
696    * @param pBuffer     pointer to buffer
697    * @param iSize       size of the buffer in byte
698    * @param dt          data type
699    * @param spec        data specification
700    */
701   int InsertOutputBlock(void* pBuffer, int iSize,
702                         const AliHLTComponentDataType& dt,
703                         AliHLTUInt32_t spec);
704
705
706   /** The global component handler instance */
707   static AliHLTComponentHandler* fgpComponentHandler;              //! transient
708
709   /** The environment where the component is running in */
710   AliHLTComponentEnvironment fEnvironment;                         // see above
711
712   /** Set by ProcessEvent before the processing starts */
713   AliHLTEventID_t fCurrentEvent;                                   // see above
714
715   /** internal event no */
716   int fEventCount;                                                 // see above
717
718   /** the number of failed events */
719   int fFailedEvents;                                               // see above
720
721   /** event data struct of the current event under processing */
722   AliHLTComponentEventData fCurrentEventData;                      // see above
723
724   /** array of input data blocks of the current event */
725   const AliHLTComponentBlockData* fpInputBlocks;                   //! transient
726
727   /** index of the current input block */
728   int fCurrentInputBlock;                                          // see above
729
730   /** data type of the last block search */
731   AliHLTComponentDataType fSearchDataType;                         // see above
732
733   /** name of the class for the object to search for */
734   string fClassName;                                               // see above
735
736   /** array of generated input objects */
737   TObjArray* fpInputObjects;                                       //! transient
738  
739   /** the output buffer */
740   AliHLTUInt8_t* fpOutputBuffer;                                   //! transient
741
742   /** size of the output buffer */
743   AliHLTUInt32_t fOutputBufferSize;                                // see above
744
745   /** size of data written to output buffer */
746   AliHLTUInt32_t fOutputBufferFilled;                              // see above
747
748   /** list of ouput block data descriptors */
749   vector<AliHLTComponentBlockData> fOutputBlocks;                  // see above
750
751   ClassDef(AliHLTComponent, 1)
752 };
753 #endif