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