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