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 #include "AliHLTComponentHandler.h"
  29
  30 class AliRunLoader;
  31 class AliRawReader;
  32
  33 /**
  34  * @class AliHLTModuleAgent
  35  * @brief Agent helper class for HLT sub modules, e.g. PHOS, TPC, Trigger
  36  *
  37  * This class implements the agent base class for the HLT sub modules.
  38  * The agent of a library gives information on the features of the library/
  39  * components, like the configurations to run and other component libraries
  40  * it depends on.
  41  * @note There must not be more than one agent per module/library.
  42  *
  43  * If a run loader is available, reconstruction is performed on simulated
  44  * data as part of <tt>AliSimulation</tt>, if the raw reader is present on
  45  * raw data as part of <tt>AliReconstruction</tt>. The configurations
  46  * can adapt to the two cases.
  47  *
  48  * All HLT component libraries are loaded on demand through the HLT steering
  49  * instance (@ref AliHLTSystem). A library can implement an agent derived
  50  * from this base class, and has to define one global object of this agent
  51  * in the code. The agent will be registered automatically, and the features
  52  * can be queried when required.
  53  *
  54  * This is usually done during running the AliRoot reconstruction (see AliRoot
  55  * documentation on <tt> AliSimulation </tt> and <tt> AliReconstruction </tt>).
  56  * The HLT implemets the @ref AliHLTSimulation and @ref
  57  * AliHLTReconstructor which hold the HLT steering object. Several flags can
  58  * be specified as options via the <tt>SetRunHLT</tt> method of
  59  * <tt>AliSimulation</tt> and the <tt>SetOption</tt> method of
  60  * <tt>AliReconstruction</tt>, including the component libraries to be loaded.
  61  *
  62  * @section alihltmoduleagent_interface Agent interface
  63  * The child can implement the following functions:
  64  * - @ref CreateConfigurations                                              <br>
  65  *       Create HLT configuration forming an HLT analysis chain.            <br>
  66  *       Reconstruction of raw data or simulated data from digits needs
  67  *       usually different configurations. If a run loader is available,
  68  *       reconstruction is performed on simulated data, on raw data if the
  69  *       raw reader is present.
  70  *
  71  * - @ref GetReconstructionChains                                           <br>
  72  *       Configurations run during event reconstruction.                    <br>
  73  *       Define chains to be run during the recunstruction step,
  74  *       Depending on the availability of AliRoot run loader or raw reader
  75  *                                                                          <br>
  76  *
  77  * - @ref GetRequiredComponentLibraries                                     <br>
  78  *       can indicate further libraries which are required for running the
  79  *       chains (e.g. if components of another library are used).
  80  *
  81  * - @ref RegisterComponents                                                <br>
  82  *       register componens, this can be used to avoid the component
  83  *       registration via global objects
  84  *       @see @ref alihltcomponent-handling
  85  *                                                                          <br>
  86  * @section alihltmoduleagent_references References
  87  * @see @ref AliHLTReconstructor interface to the AliRoot reconstruction
  88  * @see @ref AliHLTAgentSample agent for the libAliHLTSample library
  89  *
  90  * @ingroup alihlt_system
  91  */
  92 class AliHLTModuleAgent : public TObject, public AliHLTLogging {
  93  public:
  94   /**
  95    * standard constructor. The agent is automatically registered in the
  96    * global agent manager
  97    */
  98   AliHLTModuleAgent();
  99   /** destructor */
 100   virtual ~AliHLTModuleAgent();
 101
 102   /**
 103    * Print status info.
 104    * Short summary on registered agents. This function acts globally on the
 105    * list of agents if no specific agent is specified.
 106    */
 107   static void PrintStatus(const char* agent=NULL);
 108
 109   /**
 110    * Get the first agent in the list
 111    * @return  pointer to first agent in the list, NULL if empty
 112    */
 113   static AliHLTModuleAgent* GetFirstAgent();
 114
 115   /**
 116    * Get the next agent in the list
 117    * @return  pointer to next agent in the list, NULL if end of list
 118    */
 119   static AliHLTModuleAgent* GetNextAgent();
 120
 121   /**
 122    * Activate a component handler for this agent.
 123    * The @ref RegisterComponents method will be called in order to allow
 124    * the agent to register components. Once activated, the function can
 125    * be called repeatedly with the same handler and gently ignores the
 126    * invocation. In the current stage of development, only one handler
 127    * can be activated per agent. This is sufficient for the current
 128    * operation, but can be extended.
 129    * @param pHandler  [in] the component handler instance
 130    */
 131   int ActivateComponentHandler(AliHLTComponentHandler* pHandler);
 132
 133   /**
 134    * Register all configurations belonging to this module with the
 135    * AliHLTConfigurationHandler. The agent can adapt the configurations
 136    * to be registered to the current AliRoot setup by checking the
 137    * runloader and the raw reader. <br>
 138    * Run loader and raw reader are usually not present at the same time.
 139    * If a run loader is available, reconstruction is performed on simulated
 140    * data, if the raw reader is present on raw data. The configurations
 141    * can adapt to the two cases.
 142    *
 143    * @param handler   [in] the configuration handler
 144    * @param rawReader [in] AliRoot RawReader instance
 145    * @param runloader [in] AliRoot runloader
 146    * @return neg. error code if failed
 147    */
 148   virtual int CreateConfigurations(AliHLTConfigurationHandler* handler,
 149                                    AliRawReader* rawReader=NULL,
 150                                    AliRunLoader* runloader=NULL) const;
 151
 152   /**
 153    * Get the top configurations for event reconstruction.
 154    * A top configuration describes a processing chain. It can simply be
 155    * described by the last configuration(s) in the chain.
 156    * The agent can adapt the configurations to be registered to the current
 157    * AliRoot setup by checking the run loader and the raw reader.
 158    * @param rawReader [in] AliRoot RawReader instance
 159    * @param runloader [in] AliRoot runloader
 160    * @return string containing the top configurations separated by blanks
 161    */
 162   virtual const char* GetReconstructionChains(AliRawReader* rawReader=NULL,
 163                                               AliRunLoader* runloader=NULL) const;
 164
 165   /**
 166    * Component libraries which the configurations of this agent depend on. <br>
 167    * @note This is not the right place to specify libraries which this component
 168    * library depends. Dependencies must be linked or loaded before.
 169    * @return list of component libraries as a blank-separated string.
 170    */
 171   virtual const char* GetRequiredComponentLibraries() const;
 172
 173   /**
 174    * Register components.
 175    * This method can be used to register components for the module instead
 176    * of the 'static object approach'. Registration is done by passing a
 177    * sample object to the AliHLTComponentHandler via
 178    * - @ref AliHLTComponentHandler::RegisterComponent                      <br>
 179    *        The sample object is owned by the agent, make sure to delete it.
 180    * - @ref AliHLTComponentHandler::AddComponent                           <br>
 181    *        Same functionality but handler deletes the object at the end.
 182    *
 183    * @param pHandler  [in] instance of the component handler
 184    */
 185   virtual int RegisterComponents(AliHLTComponentHandler* pHandler) const;
 186
 187   /**
 188    * Old method kept for backward compatibility, redirected to @ref
 189    * GetReconstructionChains.
 190    */
 191   const char* GetTopConfigurations(AliRunLoader* runloader=NULL) const {
 192     return GetReconstructionChains(NULL,runloader);
 193   }
 194
 195  protected:
 196
 197  private:
 198   /** copy constructor prohibited */
 199   AliHLTModuleAgent(const AliHLTModuleAgent&);
 200   /** assignment operator prohibited */
 201   AliHLTModuleAgent& operator=(const AliHLTModuleAgent&);
 202
 203   /**
 204    * Register agent in the global list.
 205    * @return neg. error code if failed
 206    */
 207   static int Register(AliHLTModuleAgent* pAgent);
 208
 209   /**
 210    * Unregister agent in the global list.
 211    * @return neg. error code if failed
 212    */
 213   static int Unregister(AliHLTModuleAgent* pAgent);
 214
 215   /** the list of active agents */
 216   static AliHLTModuleAgent* fAnchor;                               //! transient
 217
 218   /** next element in the list */
 219   AliHLTModuleAgent* fpNext;                                       //! transient
 220
 221   /** the current object link (list position) */
 222   static AliHLTModuleAgent* fCurrent;                              //! transient
 223
 224   /** number of agents */
 225   static int fCount;                                               //! transient
 226
 227   /* instance of the active component handler */
 228   AliHLTComponentHandler* fpComponentHandler;                      //! transient
 229
 230   ClassDef(AliHLTModuleAgent, 2);
 231 };
 232
 233 #endif