components return -ENOSPC if output buffer too small, second trial by the AliRoot...
[u/mrichter/AliRoot.git] / HLT / BASE / AliHLTTask.h
1 //-*- Mode: C++ -*-
2 // $Id$
3
4 #ifndef ALIHLTTASK_H
5 #define ALIHLTTASK_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   AliHLTTask.h
11     @author Matthias Richter
12     @date   
13     @brief  base class for HLT tasks
14 */
15
16 // see below for class documentation
17 // or
18 // refer to README to build package
19 // or
20 // visit http://web.ift.uib.no/~kjeks/doc/alice-hlt   
21
22 #include <cerrno>
23 #include <TObject.h>
24 #include <TList.h>
25 #include "AliHLTDataTypes.h"
26 #include "AliHLTLogging.h"
27 #include "AliHLTDataBuffer.h"
28
29 struct AliHLTComponentBlockData;
30 class AliHLTComponent;
31 class AliHLTComponentHandler;
32
33 /******************************************************************************/
34
35 /**
36  * @class AliHLTTask
37  * A task collects all the information which is necessary to process a certain
38  * step in the HLT data processing chain.
39  * - the instance of the component
40  *   the task object creates and deletes the component object
41  * - the data buffer which receives the result of the component and provides
42  *   the data to other tasks/components
43  * - a list of all dependencies
44  * - a list of consumers
45  * - the task object holds an external pointer to the configuration object; 
46  *   \b Note: the configuration object must exist through the existence of the
47  *   task object!!!
48  *  
49  *
50  * @note This class is only used for the @ref alihlt_system.
51  *
52  * @ingroup alihlt_system
53  */
54 class AliHLTTask : public TObject, public AliHLTLogging {
55  public:
56   /** standard constructor */
57   AliHLTTask();
58   /** constructor 
59       @param pConf pointer to configuration descriptor
60    */
61   AliHLTTask(AliHLTConfiguration* pConf);
62   /** not a valid copy constructor, defined according to effective C++ style */
63   AliHLTTask(const AliHLTTask&);
64   /** not a valid assignment op, but defined according to effective C++ style */
65   AliHLTTask& operator=(const AliHLTTask&);
66   /** destructor */
67   virtual ~AliHLTTask();
68
69   /**
70    * Initialize the task.
71    * The task is initialized with a configuration descriptor. It needs a
72    * component handler instance to create the analysis component. The
73    * component is created and initialized.
74    * @param pConf pointer to configuration descriptor, can be NULL if it
75    *              was already provided to the constructor
76    * @param pCH   the HLT component handler
77    */
78   int Init(AliHLTConfiguration* pConf, AliHLTComponentHandler* pCH);
79
80   /**
81    * De-Initialize the task.
82    * Final cleanup after the run. The @ref AliHLTComponent::Deinit method of
83    * the component is called. The analysis component is deleted.
84    */
85   int Deinit();
86
87   /**
88    * Get the name of the object.
89    * This is an overridden TObject function in order to return the configuration
90    * name instead of the class name. Enables use of TList standard functions.
91    * @return name of the configuration
92    */
93   const char *GetName() const;
94
95   /**
96    * Return pointer to configuration.
97    * The tasks holds internally the configuration object.
98    * @return pointer to configuration
99    */
100   AliHLTConfiguration* GetConf() const;
101
102   /**
103    * Return pointer to component, which the task internally holds.
104    * <b>Never delete this object!!!</b>
105    * @return instance of the component
106    */
107   AliHLTComponent* GetComponent() const;
108
109   /**
110    * Find a dependency with a certain <i>name id</i>. 
111    * Searches in the list of dependencies for a task.
112    * @param id      the id of the <b>CONFIGURATION</b><br>
113    *                <b>NOTE:</b> the id does NOT specify a COMPONENT
114    * @return pointer to task
115    */
116   AliHLTTask* FindDependency(const char* id);
117
118   /**
119    * Add a dependency for the task.
120    * The task maintains a list of other tasks it depends on.
121    * @param   pDep  pointer to a task descriptor
122    * @return 0 if suceeded, neg error code if failed <br>
123    *    -EEXIST : the dependencie exists already
124    *
125    */
126   int SetDependency(AliHLTTask* pDep);
127
128   /**
129    * Clear a dependency.
130    * The ROOT TList touches the object which is in the list, even though
131    * it shouldn't care about. Thats why all lists have to be cleared before
132    * objects are deleted.
133    */
134   int UnsetDependency(AliHLTTask* pDep);
135
136   /**
137    * Return number of unresolved dependencies.
138    * Iterate through all the configurations the task depends on and check
139    * whether a corresponding task is available in the list.
140    * @return number of unresolved dependencies
141    */
142   int CheckDependencies();
143
144   /**
145    * Check whether the current task depends on the task pTask.
146    * @param pTask pointer to Task descriptor
147    * @return 1 the current task depends on pTask <br>
148    *         0 no dependency <br>
149    *         neg. error code if failed
150    */
151   int Depends(AliHLTTask* pTask);
152
153   /**
154    * Find a target with a certain id.
155    * Tasks which depend on the current task are referred to be <i>targets</i>. 
156    * @param id      configuration id to search for
157    * @return pointer to task instance
158    */
159   AliHLTTask* FindTarget(const char* id);
160
161   /**
162    * Insert task into target list.
163    * The target list specifies all the tasks which depend on the current task.
164    * @param pDep    pointer task object
165    * @return >=0 if succeeded, neg. error code if failed 
166    */
167   int SetTarget(AliHLTTask* pDep);
168
169   /**
170    * Clear a target.
171    * The ROOT TList touches the object which is in the list, even though
172    * it shouldn't care about. Thats why all lists have to be cleared before
173    * objects are deleted.
174    */
175   int UnsetTarget(AliHLTTask* pTarget);
176
177   /**
178    * Prepare the task for event processing.
179    * The method initializes the Data Buffer and calls the
180    * @ref AliHLTComponent::Init method of the component.<br>
181    * The @ref ProcessTask method can be called an arbitrary number of times
182    * as soon as the task is in <i>running</i> mode. 
183    */
184   int StartRun();
185
186   /**
187    * Clean-up the task after event processing.
188    * The method cleans up internal structures.
189    */
190   int EndRun();
191
192   /**
193    * Process the task.
194    * If all dependencies are resolved the tasks subscribes to the data of 
195    * all source tasks, builds the block descriptor and calls the
196    * @ref AliHLTComponent::ProcessEvent method of the component, after
197    * processing, the data blocks are released. <br>
198    * The @ref StartRun method must be called before.
199    */
200   int ProcessTask(Int_t eventNo);
201
202   /**
203    * Determine the number of matching data block between the component and the
204    * data buffer of a consumer component. It checks which data types from the
205    * list of input data types of the consumer component can be provided by data
206    * blocks of the current component.
207    * @param pConsumerTask   the task which subscribes to the data
208    * @return number of matching data blocks
209    */
210   int GetNofMatchingDataBlocks(const AliHLTTask* pConsumerTask) const;
211
212   /**
213    * Determine the number of matching data types between the component and a
214    * consumer component. It checks which data types from the list of input data
215    * types of the consumer component can be provided by the current component.
216    * @param pConsumerTask   the task which subscribes to the data
217    * @return number of matching data types
218    */
219   int GetNofMatchingDataTypes(const AliHLTTask* pConsumerTask) const;
220
221   /**
222    * Subscribe to the data of a source task.
223    * The function prepares the block descriptors for subsequent use with the
224    * @ref AliHLTComponent::ProcessEvent method, the method prepares all block
225    * descriptors which match the input data type of the consumer the function
226    * returns the number of blocks which would be prepared in case the target
227    * array is big enough.
228    * @param pConsumerTask   the task which subscribes to the data
229    * @param arrayBlockDesc  pointer to block descriptor to be filled
230    * @param iArraySize      size of the block descriptor array
231    * @return number of matching data blocks, negative error code if failed
232    */
233   int Subscribe(const AliHLTTask* pConsumerTask,
234                 AliHLTComponentBlockData* arrayBlockDesc, int iArraySize);
235
236   /**
237    * Release a block descriptor.
238    * Notification from consumer task.  
239    * @param pBlockDesc      descriptor of the data segment
240    * @param pConsumerTask   the task which subscribed to the data
241    * @return: >0 if success, negative error code if failed
242    */
243   int Release(AliHLTComponentBlockData* pBlockDesc,
244               const AliHLTTask* pConsumerTask);
245
246   /**
247    * Print the status of the task with component, dependencies and targets.
248    */
249   void PrintStatus();
250
251   /**
252    * Search task dependency list recursively to find a dependency.
253    * @param id              id of the task to search for
254    * @param pTgtList        (optional) target list to receive dependency tree
255    * @return 0 if not found, >0 found in the n-th level, 
256              dependency list in the target list  
257    */
258   int FollowDependency(const char* id, TList* pTgtList=NULL);
259
260   /**
261    * Print the tree for a certain dependency either from the task or
262    * configuration list.
263    * Each task posseses two "link lists": The configurations are the origin
264    * of the  task list. In case of an error during the built of the task list,
265    * the dependencies for the task list might be incomplete. In this case the
266    * configurations can give infomation on the error reason.  
267    * @param id              id of the dependency to search for
268    * @param bMode           0 (default) from task dependency list, <br> 
269    *                        1 from configuration list
270    */
271   void PrintDependencyTree(const char* id, int bMode=0);
272
273   /**
274    * Get number of source tasks.
275    * @return number of source tasks
276    */
277   int GetNofSources() const {return fListDependencies.GetSize();}
278
279  private:
280   /** the configuration descriptor (external pointer) */
281   AliHLTConfiguration* fpConfiguration;                           //! transient
282   /** the component described by this task (created and deleted internally) */
283   AliHLTComponent* fpComponent;                                   //! transient
284   /** the data buffer for the component processing */
285   AliHLTDataBuffer* fpDataBuffer;                                 //! transient
286   /** the list of targets (tasks which depend upon the current one) */
287   TList fListTargets;                                             // see above
288   /** the list of sources (tasks upon which the current one depends) */ 
289   TList fListDependencies;                                        // see above
290
291   /**
292    * block data array to be passed as argument to the 
293    * @ref AliHLTComponent::ProcessEvent method. 
294    * Filled through subscription to source tasks (@ref Subscribe).
295    */
296   AliHLTComponentBlockData* fpBlockDataArray;                     //! transient
297   /** size of the block data array */
298   int fBlockDataArraySize;                                        // see above
299
300   ClassDef(AliHLTTask, 1);
301 };
302
303 #endif