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   /** 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