HLT/BASE/AliHLTTask.h

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