HLT/BASE/AliHLTModuleAgent.h

   1 //-*- Mode: C++ -*-
   2 // @(#) $Id$
   3
   4 #ifndef ALIHLTMODULEAGENT_H
   5 #define ALIHLTMODULEAGENT_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   AliHLTModuleAgent.h
  11     @author Matthias Richter
  12     @date
  13     @brief  Agent helper class for component libraries.
  14     @note   The class is used in Offline (AliRoot) context
  15 */
  16
  17 // see below for class documentation
  18 // or
  19 // refer to README to build package
  20 // or
  21 // visit http://web.ift.uib.no/~kjeks/doc/alice-hlt
  22
  23 #include <TObject.h>
  24 #include <TList.h>
  25 #include "AliHLTLogging.h"
  26 #include "AliHLTConfiguration.h"
  27 #include "AliHLTConfigurationHandler.h"
  28
  29 class AliRunLoader;
  30
  31 /**
  32  * @class AliHLTModuleAgent
  33  * @brief Agent helper class for HLT sub modules, e.g. PHOS, TPC, Trigger
  34  *
  35  * This class implements the agent base class for the HLT sub modules.
  36  * The agent of a library gives information on the features of the library/
  37  * components, like the configurations to run and other component libraries
  38  * it depends on.
  39  * @note There must not be more than one agent per module/library.
  40  *
  41  * All HLT component libraries are loaded on demand through the HLT steering
  42  * instance (@ref AliHLTSystem). A library can implement an agent derived
  43  * from this base class, and has to define one global object of this agent
  44  * in the code. The agent will be registered automatically, and the features
  45  * can be queried when required.
  46  *
  47  * This is usually done during running the AliRoot reconstruction (see AliRoot
  48  * documentation on <tt> AliReconstruction</tt>). The HLT implemets the @ref
  49  * AliHLTReconstructor which holds the HLT steering object. Several flags can
  50  * be specified as options via the <tt>SetOption</tt> method of
  51  * <tt>AliReconstruction</tt>, including the component libraries to be loaded.
  52  *
  53  * @section alihltmoduleagent_interface Agent interface
  54  * The child can implement the following functions:
  55  * - @ref CreateConfigurations                                              <br>
  56  *       create HLT configuration forming an HLT analysis chain.
  57  *
  58  * - @ref GetLocalRecConfigurations                                         <br>
  59  *       configurations run during local event reconstruction.
  60  *       @note Local event reconstruction is the first step of the
  61  *       reconstruction chain. All events are processed at once.
  62  *                                                                          <br>
  63  * - @ref GetEventRecConfigurations                                         <br>
  64  *       configurations run during event reconstruction.
  65  *       @note This is the reconstruction on event by event basis.
  66  *                                                                          <br>
  67  * - @ref GetRequiredComponentLibraries                                     <br>
  68  *       can indicate further libraries which are required for running the
  69  *       chains (e.g. if components of another library are used).
  70  *
  71  * - @ref RegisterComponents                                                <br>
  72  *       register componens, this can be used to avoid the component
  73  *       registration via global objects
  74  *       @see @ref alihltcomponent-handling
  75  *                                                                          <br>
  76  * @section alihltmoduleagent_references References
  77  * @see @ref AliHLTReconstructor interface to the AliRoot reconstruction
  78  * @see @ref AliHLTAgentSample agent for the libAliHLTSample library
  79  *
  80  * @ingroup alihlt_system
  81  */
  82 class AliHLTModuleAgent : public TObject, public AliHLTLogging {
  83  public:
  84   /**
  85    * standard constructor. The agent is automatically registered in the
  86    * global agent manager
  87    */
  88   AliHLTModuleAgent();
  89   /** not a valid copy constructor, defined according to effective C++ style */
  90   AliHLTModuleAgent(const AliHLTModuleAgent&);
  91   /** not a valid assignment op, but defined according to effective C++ style */
  92   AliHLTModuleAgent& operator=(const AliHLTModuleAgent&);
  93   /** destructor */
  94   virtual ~AliHLTModuleAgent();
  95
  96   /**
  97    * Print status info.
  98    * Short summary on registered agents. This function acts globally on the
  99    * list of agents if no specific agent is specified.
 100    */
 101   static void PrintStatus(const char* agent=NULL);
 102
 103   /**
 104    * Get the first agent in the list
 105    * @return  pointer to first agent in the list, NULL if empty
 106    */
 107   static AliHLTModuleAgent* GetFirstAgent();
 108
 109   /**
 110    * Get the next agent in the list
 111    * @return  pointer to next agent in the list, NULL if end of list
 112    */
 113   static AliHLTModuleAgent* GetNextAgent();
 114
 115   /**
 116    * Register all configurations belonging to this module with the
 117    * AliHLTConfigurationHandler. The agent can adapt the configurations
 118    * to be registered to the current AliRoot setup by checking the
 119    * runloader.
 120    * @param handler   [in] the configuration handler
 121    * @param runloader [in] AliRoot runloader
 122    * @return neg. error code if failed
 123    */
 124   virtual int CreateConfigurations(AliHLTConfigurationHandler* handler,
 125                                    AliRunLoader* runloader=NULL) const;
 126
 127   /**
 128    * Get the top configurations for local event reconstruction.
 129    * A top configuration describes a processing chain. It can simply be
 130    * described by the last configuration(s) in the chain.
 131    * The agent can adapt the configurations to be registered to the current
 132    * AliRoot setup by checking the runloader.
 133    * @param runloader  [in] AliRoot runloader
 134    * @return string containing the top configurations separated by blanks
 135    */
 136   virtual const char* GetLocalRecConfigurations(AliRunLoader* runloader=NULL) const;
 137
 138   /**
 139    * Get the top configurations for event reconstruction.
 140    * The same as for @ref GetLocalRecConfigurations, but for the reconstruction on
 141    * event by event basis.
 142    * @param runloader  [in] AliRoot runloader
 143    * @return string containing the top configurations separated by blanks
 144    */
 145   virtual const char* GetEventRecConfigurations(AliRunLoader* runloader=NULL) const;
 146
 147   /**
 148    * Component libraries which the configurations of this agent depend on.
 149    * @return list of component libraries as a blank-separated string.
 150    */
 151   virtual const char* GetRequiredComponentLibraries() const;
 152
 153   /**
 154    * Register componets.
 155    * This method can be used to register components for the module instead
 156    * of the 'static object approach'. Registration is don by passing a
 157    * sample object to @ref AliHLTComponentHandler::RegisterComponent<br>
 158    * \em Note: The sample object is owned by the agent, make sure to delete
 159    * it.
 160    */
 161   virtual int RegisterComponents(AliRunLoader* runloader=NULL) const;
 162
 163   /**
 164    * Old method kept for backward compatibility, redirected to @ref
 165    * GetLocalRecConfigurations.
 166    */
 167   const char* GetTopConfigurations(AliRunLoader* runloader=NULL) const {
 168     return GetLocalRecConfigurations(runloader);
 169   }
 170
 171  protected:
 172
 173  private:
 174   /**
 175    * Register agent in the global list.
 176    * @return neg. error code if failed
 177    */
 178   static int Register(AliHLTModuleAgent* pAgent);
 179
 180   /**
 181    * Unregister agent in the global list.
 182    * @return neg. error code if failed
 183    */
 184   static int Unregister(AliHLTModuleAgent* pAgent);
 185
 186   /** the list of active agents */
 187   static AliHLTModuleAgent* fAnchor;                               //! transient
 188
 189   /** next element in the list */
 190   AliHLTModuleAgent* fpNext;                                       //! transient
 191
 192   /** the current object link (list position) */
 193   static AliHLTModuleAgent* fCurrent;                              //! transient
 194
 195   /** number of agents */
 196   static int fCount;                                               //! transient
 197
 198   ClassDef(AliHLTModuleAgent, 1);
 199 };
 200
 201 #endif