HLT/BASE/AliHLTConfiguration.h

   1 // @(#) $Id$
   2
   3 #ifndef ALIHLTCONFIGURATION_H
   4 #define ALIHLTCONFIGURATION_H
   5 /* Copyright(c) 1998-1999, ALICE Experiment at CERN, All rights reserved. *
   6  * See cxx source for full Copyright notice                               */
   7
   8 /** @file   AliHLTConfiguration.h
   9     @author Matthias Richter
  10     @date
  11     @brief  base class and handling of HLT configurations.
  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 class AliHLTConfigurationHandler;
  22
  23 /**
  24  * @class AliHLTConfiguration
  25  * @brief Description of HLT processing chains.
  26  * @note Definition:
  27  * This class describes a certain configuration af an HLT processing step
  28  * by the following parameters:
  29  * - a unique id string/name
  30  * - the id of the component
  31  * - the ids of the configurations it requires input from
  32  * - the arguments, which are passed to the component when it is initialized
  33  *
  34  * The setup of a configuration requires simply the creation of a global object
  35  * of @ref AliHLTConfiguration. The Configuration is automatically registered
  36  * in the list of available configurations maintained by the @ref
  37  * AliHLTConfigurationHandler. The list is used by to resolve the dependencies
  38  * on other configurations. Hierarchies can be built up in an easy way.
  39  *
  40  * A configuration is interpreted by the @ref AliHLTConfigurationHandler and
  41  * transformed into a Task List.
  42  * @ingroup AliHLTbase
  43  */
  44 class AliHLTConfiguration : public TObject, public AliHLTLogging {
  45  public:
  46   /**
  47    * standard constructor. The configuration is automatically registered in the
  48    * global configuration manager
  49    */
  50   AliHLTConfiguration();
  51   /**
  52    * constructor. The configuration is automatically registered in the
  53    * global configuration manager
  54    * @param id         unique id of the configuration
  55    * @param component  component id
  56    * @param sources    blank separated list of source configuration ids
  57    * @param arguments  argument string passed to the component at initialization
  58    */
  59   AliHLTConfiguration(const char* id, const char* component,
  60                       const char* sources, const char* arguments);
  61   /** destructor */
  62   virtual ~AliHLTConfiguration();
  63
  64   /*****************************************************************************
  65    * global initialization
  66    */
  67
  68   /**
  69    * Global initialization of the configuration handler.
  70    */
  71   static int GlobalInit(AliHLTConfigurationHandler* pHandler);
  72
  73   /**
  74    * Global de-init and cleanup of the global configuration handler
  75    */
  76   static int GlobalDeinit();
  77
  78   /*****************************************************************************
  79    * properties of the configuration
  80    */
  81
  82   /**
  83    * Get configuration id, a unique name
  84    * This is an overridden TObject function in order to return the configuration
  85    * name instead of the class name. Enables use of TList standard functions.
  86    * @return configuration id
  87    */
  88   const char *GetName() const;
  89
  90   /**
  91    * Get id of the component.
  92    * The id is a unique string.
  93    * @return id of the component
  94    */
  95   const char* GetComponentID() {return fComponent;}
  96
  97   /**
  98    * Print status info.
  99    * Short summary on id, component, sources and unresolved sources.
 100    */
 101   void PrintStatus();
 102
 103   /**
 104    * Get a certain source.
 105    * @param  id of the source configuration
 106    * @result pointer to the corresponding configuration descriptor
 107    */
 108   AliHLTConfiguration* GetSource(const char* id);
 109
 110   /**
 111    * Try to find a dependency recursively in the list of sources.
 112    * @param id       the source to search for
 113    * @param pTgtList (optional) target list to receive the dependency tree
 114    * @return
 115    *   0 if not found
 116    *   n found in the n-th level
 117    *   dependency list in the target list
 118    */
 119   int FollowDependency(const char* id, TList* pTgtList=NULL);
 120
 121   /**
 122    * Get the number of resolved sources.
 123    * @return number of resolved sources
 124    */
 125   int GetNofSources() {return fListSources.size();}
 126
 127   /**
 128    * Check resolving status.
 129    * @param bAuto resolve if ==1
 130    * @return 1 if all sources resolved
 131    */
 132   int SourcesResolved(int bAuto=0);
 133
 134   /**
 135    * Start iteration and get the first source.
 136    * @result pointer to the first configuration descriptor
 137    */
 138   AliHLTConfiguration* GetFirstSource();
 139
 140   /**
 141    * Continue iteration and get the next source.
 142    * @result pointer to the next configuration descriptor in the list
 143    */
 144   AliHLTConfiguration* GetNextSource();
 145
 146   /**
 147    * Invalidate a dependency and mark the configuration to be re-evaluted.
 148    * @param pConf pointer to configuration descriptor
 149    */
 150   int InvalidateSource(AliHLTConfiguration* pConf);
 151
 152   /**
 153    * Mark the configuration to be re-evaluted.
 154    */
 155   int InvalidateSources() {fNofSources=-1; return 0;}
 156
 157   /**
 158    * Get the arguments array.
 159    * @param pArgv   pointer to receive argument array pointer
 160    * @return argc if succeeded, neg. error code if failed
 161    */
 162   int GetArguments(const char*** pArgv);
 163
 164  protected:
 165
 166
 167  private:
 168   /* extract the source configurations from the sources string
 169    */
 170   int ExtractSources();
 171
 172   /* extract arguments from the argument string
 173    */
 174   int ExtractArguments();
 175
 176   /* helper function to build a vector from an argument string
 177    */
 178   int InterpreteString(const char* arg, vector<char*>& argList);
 179
 180   /** id of this configuration */
 181   const char* fID;
 182   /** component id of this configuration */
 183   const char* fComponent;
 184
 185   /** the <i>sources</i> string as passed to the constructor */
 186   const char* fStringSources;
 187   /** number of resolved sources, -1 indicates re-evaluation */
 188   int fNofSources;
 189   /** list of sources */
 190   vector<AliHLTConfiguration*> fListSources;
 191   /** iterator for the above list */
 192   vector<AliHLTConfiguration*>::iterator fListSrcElement;
 193
 194   /**
 195    * The argument string as passed to the constructor.
 196    * Specifies the arguments for the Analysys component. The string will
 197    * be parsed and the separated arguments stored in the @ref fArgv array
 198    * and @ref fArgc member.
 199    */
 200   const char* fArguments;
 201   /** number of arguments */
 202   int fArgc;
 203   /** argument array */
 204   char** fArgv;
 205
 206   static AliHLTConfigurationHandler* fConfigurationHandler;
 207
 208   ClassDef(AliHLTConfiguration, 0);
 209 };
 210
 211 struct AliHLTComponent_BlockData;
 212 class AliHLTComponent;
 213 class AliHLTComponentHandler;
 214
 215 /******************************************************************************/
 216
 217  /**
 218   * @class AliHLTTask
 219   * A task collects all the information which is necessary to process a certain
 220   * step in the HLT data processing chain:
 221   * - the instance of the component
 222   * - the data buffer which receives the result of the component and provides
 223   *   the data to other tasks/components
 224   * - a list of all dependencies
 225   * - a list of consumers
 226   * - the task object holds the configuration object
 227   */
 228 class AliHLTTask : public TObject, public AliHLTLogging {
 229  public:
 230   /** standard constructor */
 231   AliHLTTask();
 232   /** constructor
 233       @param pConf pointer to configuration descriptor
 234       @param pCH   the HLT component handler
 235    */
 236   AliHLTTask(AliHLTConfiguration* pConf, AliHLTComponentHandler* pCH);
 237   /** destructor */
 238   virtual ~AliHLTTask();
 239
 240   /**
 241    * Initialize the task.
 242    * The task is initialized with a configuration descriptor. It needs a
 243    * component handler instance to create the analysis component.
 244    * @param pConf pointer to configuration descriptor
 245    * @param pCH   the HLT component handler
 246    */
 247   int Init(AliHLTConfiguration* pConf, AliHLTComponentHandler* pCH);
 248
 249   /**
 250    * Get the name of the object.
 251    * This is an overridden TObject function in order to return the configuration
 252    * name instead of the class name. Enables use of TList standard functions.
 253    * @return name of the configuration
 254    */
 255   const char *GetName() const;
 256
 257   /**
 258    * Return pointer to configuration.
 259    * The tasks holds internally the configuration object.
 260    * @return pointer to configuration
 261    */
 262   AliHLTConfiguration* GetConf() const;
 263
 264   /**
 265    * Return pointer to component, which the task internally holds.
 266    * <b>Never delete this object!!!</b>
 267    * @return instance of the component
 268    */
 269   AliHLTComponent* GetComponent() const;
 270
 271   /**
 272    * Find a dependency with a certain <i>name id</i>.
 273    * Searches in the list of dependencies for a task.
 274    * @param id      the id of the <b>CONFIGURATION</b><br>
 275    *                <b>NOTE:</b> the id does NOT specify a COMPONENT
 276    * @return pointer to task
 277    */
 278   AliHLTTask* FindDependency(const char* id);
 279
 280   /*
 281    * insert block data to the list
 282    * the data has to come from a task the current one depends on
 283    * result:
 284    *    -EEXIST : the block data from this task has already been inserted
 285    *    -ENOENT : no dependencies to the task the data is coming from
 286    */
 287   /*
 288    * this function is most likely depricated
 289   int InsertBlockData(AliHLTComponent_BlockData* pBlock, AliHLTTask* pSource);
 290   */
 291
 292   /**
 293    * Add a dependency for the task.
 294    * The task maintains a list of other tasks it depends on.
 295    * @param   pDep  pointer to a task descriptor
 296    * @return 0 if suceeded, neg error code if failed <br>
 297    *    -EEXIST : the dependencie exists already
 298    *
 299    */
 300   int SetDependency(AliHLTTask* pDep);
 301
 302   /**
 303    * Return number of unresolved dependencies.
 304    * Iterate through all the configurations the task depends on and check
 305    * whether a corresponding task is available in the list.
 306    * @return number of unresolved dependencies
 307    */
 308   int CheckDependencies();
 309
 310   /**
 311    * Check whether the current task depends on the task pTask.
 312    * @param pTask pointer to Task descriptor
 313    * @return 1 the current task depends on pTask <br>
 314    *         0 no dependency <br>
 315    *         neg. error code if failed
 316    */
 317   int Depends(AliHLTTask* pTask);
 318
 319   /**
 320    * Find a target with a certain id.
 321    * Tasks which depend on the current task are referred to be <i>targets</i>.
 322    * @param id      configuration id to search for
 323    * @return pointer to task instance
 324    */
 325   AliHLTTask* FindTarget(const char* id);
 326
 327   /**
 328    * Insert task into target list.
 329    * The target list specifies all the tasks which depend on the current task.
 330    * @param pDep    pointer task object
 331    * @return >=0 if succeeded, neg. error code if failed
 332    */
 333   int SetTarget(AliHLTTask* pDep);
 334
 335   // build a monolithic array of block data
 336   // @param pBlockData reference to the block data target
 337   // @return: array size, pointer to array in the target pTgt
 338   //
 339   /* this function is most likely depricated
 340   int BuildBlockDataArray(AliHLTComponent_BlockData*& pBlockData);
 341   */
 342
 343   /**
 344    * Prepare the task for event processing.
 345    * The method initializes the Data Buffer and calls the
 346    * @ref AliHLTComponent::Init method of the component.<br>
 347    * The @ref ProcessTask methode can be called an arbitrary number of times
 348    * as soon as the task is in <i>running</i> mode.
 349    */
 350   int StartRun();
 351
 352   /**
 353    * Clean-up the task after event processing.
 354    * The method cleans up internal structures and calls the
 355    * @ref AliHLTComponent::Deinit method of the component.
 356    */
 357   int EndRun();
 358
 359   /**
 360    * Process the task.
 361    * If all dependencies are resolved the tasks subscribes to the data of
 362    * all source tasks, builds the block descriptor and calls the
 363    * @ref AliHLTComponent::ProcessEvent method of the component, after
 364    * processing, the data blocks are released. <br>
 365    * The @ref StartRun method must be called before.
 366    */
 367   int ProcessTask();
 368
 369   // clear the list of source data blocks
 370   // the list of source data blocks has to be cleared at the beginning of
 371   // a new event
 372   /* this function is most likely depricated
 373   int ClearSourceBlocks();
 374   */
 375
 376   /**
 377    * Determine the number of matching data block between the component and the
 378    * data buffer of a consumer component. It checks which data types from the
 379    * list of input data types of the consumer component can be provided by data
 380    * blocks of the current component.
 381    * @param pConsumerTask   the task which subscribes to the data
 382    * @return number of matching data blocks
 383    */
 384   int GetNofMatchingDataBlocks(const AliHLTTask* pConsumerTask);
 385
 386   /**
 387    * Determine the number of matching data types between the component and a
 388    * consumer component. It checks which data types from the list of input data
 389    * types of the consumer component can be provided by the current component.
 390    * @param pConsumerTask   the task which subscribes to the data
 391    * @return number of matching data types
 392    */
 393   int GetNofMatchingDataTypes(const AliHLTTask* pConsumerTask);
 394
 395   /**
 396    * Subscribe to the data of a source task.
 397    * The function prepares the block descriptors for subsequent use with the
 398    * @ref AliHLTComponent::ProcessEvent method, the method prepares all block
 399    * descriptors which match the input data type of the consumer the function
 400    * returns the number of blocks which would be prepared in case the target
 401    * array is big enough.
 402    * @param pConsumerTask   the task which subscribes to the data
 403    * @param arrayBlockDesc  pointer to block descriptor to be filled
 404    * @param iArraySize      size of the block descriptor array
 405    * @return number of matching data blocks, negative error code if failed
 406    */
 407   int Subscribe(const AliHLTTask* pConsumerTask,
 408                 AliHLTComponent_BlockData* arrayBlockDesc, int iArraySize);
 409
 410   /**
 411    * Release a block descriptor.
 412    * Notification from consumer task.
 413    * @param pBlockDesc      descriptor of the data segment
 414    * @param pConsumerTask   the task which subscribed to the data
 415    * @return: >0 if success, negative error code if failed
 416    */
 417   int Release(AliHLTComponent_BlockData* pBlockDesc,
 418               const AliHLTTask* pConsumerTask);
 419
 420   /**
 421    * Print the status of the task with component, dependencies and targets.
 422    */
 423   void PrintStatus();
 424
 425   /**
 426    * Search task dependency list recursively to find a dependency.
 427    * @param id              id of the task to search for
 428    * @param pTgtList        (optional) target list to receive dependency tree
 429    * @return 0 if not found, >0 found in the n-th level,
 430              dependency list in the target list
 431    */
 432   int FollowDependency(const char* id, TList* pTgtList=NULL);
 433
 434   /**
 435    * Print the tree for a certain dependency either from the task or
 436    * configuration list.
 437    * Each task posseses two "link lists": The configurations are the origin
 438    * of the  task list. In case of an error during the built of the task list,
 439    * the dependencies for the task list might be incomplete. In this case the
 440    * configurations can give infomation on the error reason.
 441    * @param id              id of the dependency to search for
 442    * @param bMode           0 (default) from task dependency list, <br>
 443    *                        1 from configuration list
 444    */
 445   void PrintDependencyTree(const char* id, int bMode=0);
 446
 447   /**
 448    * Get number of source tasks.
 449    * @return number of source tasks
 450    */
 451   int GetNofSources() {return fListDependencies.GetSize();}
 452
 453  private:
 454   /** the configuration descriptor */
 455   AliHLTConfiguration* fpConfiguration;
 456   /** the component described by this task */
 457   AliHLTComponent* fpComponent;
 458   /** the data buffer for the component processing */
 459   AliHLTDataBuffer* fpDataBuffer;
 460   /** the list of targets (tasks which depend upon the current one) */
 461   TList fListTargets;
 462   /** the list of sources (tasks upon which the current one depends) */
 463   TList fListDependencies;
 464
 465   /**
 466    * block data array to be passed as argument to the
 467    * @ref AliHLTComponent::ProcessEvent method.
 468    * Filled through subscription to source tasks (@ref Subscribe).
 469    */
 470   AliHLTComponent_BlockData* fpBlockDataArray;
 471   /** size of the block data array */
 472   int fBlockDataArraySize;
 473
 474   ClassDef(AliHLTTask, 0);
 475 };
 476
 477 class AliHLTConfigurationHandler : public AliHLTLogging {
 478  public:
 479   AliHLTConfigurationHandler();
 480   //AliHLTConfigurationHandler(AliHLTConfiguration* pConf);
 481   virtual ~AliHLTConfigurationHandler();
 482
 483   /*****************************************************************************
 484    * registration
 485    */
 486
 487   // register a configuration to the global list of configurations
 488   int RegisterConfiguration(AliHLTConfiguration* pConf);
 489
 490   // create a configuration and register it
 491   int CreateConfiguration(const char* id, const char* component, const char* sources, const char* arguments);
 492
 493   // remove a configuration from the global list
 494   int RemoveConfiguration(AliHLTConfiguration* pConf);
 495   int RemoveConfiguration(const char* id);
 496
 497   // find a configuration from the global list
 498   AliHLTConfiguration* FindConfiguration(const char* id);
 499
 500   // print the registered configurations to the logging function
 501   void PrintConfigurations();
 502
 503
 504  private:
 505   static TList fListConfigurations; // the list of registered configurations
 506   static TList fListDynamicConfigurations; // the list of dynamic configurations (for proper cleanup)
 507
 508   ClassDef(AliHLTConfigurationHandler, 0);
 509 };
 510
 511 #endif