HLT/BASE/AliHLTTask.h

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