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 AliHLTComponentBlockData;
  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 task object creates and deletes the component object
  33  * - the data buffer which receives the result of the component and provides
  34  *   the data to other tasks/components
  35  * - a list of all dependencies
  36  * - a list of consumers
  37  * - the task object holds an external pointer to the configuration object;
  38  *   \b Note: the configuration object must exist through the existence of the
  39  *   task object!!!
  40  *
  41  *
  42  * @note This class is only used for the @ref alihlt_system.
  43  *
  44  * @ingroup alihlt_system
  45  */
  46 class AliHLTTask : public TObject, public AliHLTLogging {
  47  public:
  48   /** standard constructor */
  49   AliHLTTask();
  50   /** constructor
  51       @param pConf pointer to configuration descriptor
  52    */
  53   AliHLTTask(AliHLTConfiguration* pConf);
  54   /** not a valid copy constructor, defined according to effective C++ style */
  55   AliHLTTask(const AliHLTTask&);
  56   /** not a valid assignment op, but defined according to effective C++ style */
  57   AliHLTTask& operator=(const AliHLTTask&);
  58   /** destructor */
  59   virtual ~AliHLTTask();
  60
  61   /**
  62    * Initialize the task.
  63    * The task is initialized with a configuration descriptor. It needs a
  64    * component handler instance to create the analysis component. The
  65    * component is created and initialized.
  66    * @param pConf pointer to configuration descriptor, can be NULL if it
  67    *              was already provided to the constructor
  68    * @param pCH   the HLT component handler
  69    */
  70   int Init(AliHLTConfiguration* pConf, AliHLTComponentHandler* pCH);
  71
  72   /**
  73    * De-Initialize the task.
  74    * Final cleanup after the run. The @ref AliHLTComponent::Deinit method of
  75    * the component is called. The analysis component is deleted.
  76    */
  77   int Deinit();
  78
  79   /**
  80    * Get the name of the object.
  81    * This is an overridden TObject function in order to return the configuration
  82    * name instead of the class name. Enables use of TList standard functions.
  83    * @return name of the configuration
  84    */
  85   const char *GetName() const;
  86
  87   /**
  88    * Return pointer to configuration.
  89    * The tasks holds internally the configuration object.
  90    * @return pointer to configuration
  91    */
  92   AliHLTConfiguration* GetConf() const;
  93
  94   /**
  95    * Return pointer to component, which the task internally holds.
  96    * <b>Never delete this object!!!</b>
  97    * @return instance of the component
  98    */
  99   AliHLTComponent* GetComponent() const;
 100
 101   /**
 102    * Find a dependency with a certain <i>name id</i>.
 103    * Searches in the list of dependencies for a task.
 104    * @param id      the id of the <b>CONFIGURATION</b><br>
 105    *                <b>NOTE:</b> the id does NOT specify a COMPONENT
 106    * @return pointer to task
 107    */
 108   AliHLTTask* FindDependency(const char* id);
 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    * Clear a dependency.
 122    * The ROOT TList touches the object which is in the list, even though
 123    * it shouldn't care about. Thats why all lists have to be cleared before
 124    * objects are deleted.
 125    */
 126   int UnsetDependency(AliHLTTask* pDep);
 127
 128   /**
 129    * Return number of unresolved dependencies.
 130    * Iterate through all the configurations the task depends on and check
 131    * whether a corresponding task is available in the list.
 132    * @return number of unresolved dependencies
 133    */
 134   int CheckDependencies();
 135
 136   /**
 137    * Check whether the current task depends on the task pTask.
 138    * @param pTask pointer to Task descriptor
 139    * @return 1 the current task depends on pTask <br>
 140    *         0 no dependency <br>
 141    *         neg. error code if failed
 142    */
 143   int Depends(AliHLTTask* pTask);
 144
 145   /**
 146    * Find a target with a certain id.
 147    * Tasks which depend on the current task are referred to be <i>targets</i>.
 148    * @param id      configuration id to search for
 149    * @return pointer to task instance
 150    */
 151   AliHLTTask* FindTarget(const char* id);
 152
 153   /**
 154    * Insert task into target list.
 155    * The target list specifies all the tasks which depend on the current task.
 156    * @param pDep    pointer task object
 157    * @return >=0 if succeeded, neg. error code if failed
 158    */
 159   int SetTarget(AliHLTTask* pDep);
 160
 161   /**
 162    * Clear a target.
 163    * The ROOT TList touches the object which is in the list, even though
 164    * it shouldn't care about. Thats why all lists have to be cleared before
 165    * objects are deleted.
 166    */
 167   int UnsetTarget(AliHLTTask* pTarget);
 168
 169   /**
 170    * Prepare the task for event processing.
 171    * The method initializes the Data Buffer and calls the
 172    * @ref AliHLTComponent::Init method of the component.<br>
 173    * The @ref ProcessTask method can be called an arbitrary number of times
 174    * as soon as the task is in <i>running</i> mode.
 175    */
 176   int StartRun();
 177
 178   /**
 179    * Clean-up the task after event processing.
 180    * The method cleans up internal structures.
 181    */
 182   int EndRun();
 183
 184   /**
 185    * Process the task.
 186    * If all dependencies are resolved the tasks subscribes to the data of
 187    * all source tasks, builds the block descriptor and calls the
 188    * @ref AliHLTComponent::ProcessEvent method of the component, after
 189    * processing, the data blocks are released. <br>
 190    * The @ref StartRun method must be called before.
 191    */
 192   int ProcessTask(Int_t eventNo);
 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) const;
 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) const;
 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                 AliHLTComponentBlockData* 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(AliHLTComponentBlockData* 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() const {return fListDependencies.GetSize();}
 270
 271  private:
 272   /** the configuration descriptor (external pointer) */
 273   AliHLTConfiguration* fpConfiguration;                           //! transient
 274   /** the component described by this task (created and deleted internally) */
 275   AliHLTComponent* fpComponent;                                   //! transient
 276   /** the data buffer for the component processing */
 277   AliHLTDataBuffer* fpDataBuffer;                                 //! transient
 278   /** the list of targets (tasks which depend upon the current one) */
 279   TList fListTargets;                                             // see above
 280   /** the list of sources (tasks upon which the current one depends) */
 281   TList fListDependencies;                                        // see above
 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   AliHLTComponentBlockData* fpBlockDataArray;                     //! transient
 289   /** size of the block data array */
 290   int fBlockDataArraySize;                                        // see above
 291
 292   ClassDef(AliHLTTask, 1);
 293 };
 294
 295 #endif