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 class AliRawStream;
  33 class AliHLTOUTHandler;
  34 class AliHLTOUT;
  35
  36 /**
  37  * @class AliHLTModuleAgent
  38  * @brief Agent helper class for HLT sub modules, e.g. PHOS, TPC, Trigger
  39  *
  40  * This class implements the agent base class for the HLT sub modules.
  41  * The agent of a library gives information on the features of the library/
  42  * components, like the configurations to run and other component libraries
  43  * it depends on.
  44  * @note There must not be more than one agent per module/library.
  45  *
  46  * If a run loader is available, reconstruction is performed on simulated
  47  * data as part of <tt>AliSimulation</tt>, if the raw reader is present on
  48  * raw data as part of <tt>AliReconstruction</tt>. The configurations
  49  * can adapt to the two cases.
  50  *
  51  * All HLT component libraries are loaded on demand through the HLT steering
  52  * instance (@ref AliHLTSystem). A library can implement an agent derived
  53  * from this base class, and has to define one global object of this agent
  54  * in the code. The agent will be registered automatically, and the features
  55  * can be queried when required.
  56  *
  57  * This is usually done during running the AliRoot reconstruction (see AliRoot
  58  * documentation on <tt> AliSimulation </tt> and <tt> AliReconstruction </tt>).
  59  * The HLT implemets the @ref AliHLTSimulation and @ref
  60  * AliHLTReconstructor which hold the HLT steering object. Several flags can
  61  * be specified as options via the <tt>SetRunHLT</tt> method of
  62  * <tt>AliSimulation</tt> and the <tt>SetOption</tt> method of
  63  * <tt>AliReconstruction</tt>, including the component libraries to be loaded.
  64  *
  65  * @section alihltmoduleagent_interface Agent interface
  66  * The child can implement the following functions:
  67  * - @ref CreateConfigurations                                              <br>
  68  *       Create HLT configuration forming an HLT analysis chain.            <br>
  69  *       Reconstruction of raw data or simulated data from digits needs
  70  *       usually different configurations. If a run loader is available,
  71  *       reconstruction is performed on simulated data, on raw data if the
  72  *       raw reader is present.
  73  *
  74  * - @ref GetReconstructionChains                                           <br>
  75  *       Configurations run during event reconstruction.                    <br>
  76  *       Define chains to be run during the recunstruction step,
  77  *       Depending on the availability of AliRoot run loader or raw reader
  78  *                                                                          <br>
  79  *
  80  * - @ref GetRequiredComponentLibraries                                     <br>
  81  *       can indicate further libraries which are required for running the
  82  *       chains (e.g. if components of another library are used).
  83  *
  84  * - @ref RegisterComponents                                                <br>
  85  *       register componens, this can be used to avoid the component
  86  *       registration via global objects
  87  *       @see @ref alihltcomponent-handling
  88  *                                                                          <br>
  89  * - @ref GetHandlerDescription                                             <br>
  90  *       the agent can announce which part of the HLTOUT data can be treated
  91  *       by the library and through which method. Different types of handlers
  92  *       are defined to fit the various formats of the HLTOUT data.
  93  *       @see AliHLTOUTHandlerType
  94  *
  95  * - @ref GetOutputHandler                                                  <br>
  96  *       Return AliHLTOUTHandler for a given data type and specification.
  97  *       This is mainly intended to treat detector proprietary data.
  98  *
  99  * - @ref GetRawStream                                                      <br>
 100  *       Return an AliRawStream object which is capable of treating the
 101  *       specified data type and specification. Rawstream must be provided
 102  *       for data blocks intended to be the input for AliRoot detector
 103  *       reconstruction by replacing the normal input stream.
 104  *
 105  * @section alihltmoduleagent_references References
 106  * @see @ref AliHLTReconstructor interface to the AliRoot reconstruction
 107  * @see @ref AliHLTAgentSample agent for the libAliHLTSample library
 108  *
 109  * @ingroup alihlt_system
 110  */
 111 class AliHLTModuleAgent : public TObject, public AliHLTLogging {
 112  public:
 113   /**
 114    * standard constructor. The agent is automatically registered in the
 115    * global agent manager
 116    */
 117   AliHLTModuleAgent();
 118   /** destructor */
 119   virtual ~AliHLTModuleAgent();
 120
 121   /**
 122    * Print status info.
 123    * Short summary on registered agents. This function acts globally on the
 124    * list of agents if no specific agent is specified.
 125    */
 126   static void PrintStatus(const char* agent=NULL);
 127
 128   /**
 129    * Get the first agent in the list
 130    * @return  pointer to first agent in the list, NULL if empty
 131    */
 132   static AliHLTModuleAgent* GetFirstAgent();
 133
 134   /**
 135    * Get the next agent in the list
 136    * @return  pointer to next agent in the list, NULL if end of list
 137    */
 138   static AliHLTModuleAgent* GetNextAgent();
 139
 140   /**
 141    * Activate a component handler for this agent.
 142    * The @ref RegisterComponents method will be called in order to allow
 143    * the agent to register components. Once activated, the function can
 144    * be called repeatedly with the same handler and gently ignores the
 145    * invocation. In the current stage of development, only one handler
 146    * can be activated per agent. This is sufficient for the current
 147    * operation, but can be extended.
 148    * @param pHandler  [in] the component handler instance
 149    */
 150   int ActivateComponentHandler(AliHLTComponentHandler* pHandler);
 151
 152   /**
 153    * Register all configurations belonging to this module with the
 154    * AliHLTConfigurationHandler. The agent can adapt the configurations
 155    * to be registered to the current AliRoot setup by checking the
 156    * runloader and the raw reader. <br>
 157    * Run loader and raw reader are usually not present at the same time.
 158    * If a run loader is available, reconstruction is performed on simulated
 159    * data, if the raw reader is present on raw data. The configurations
 160    * can adapt to the two cases.
 161    *
 162    * @param handler   [in] the configuration handler
 163    * @param rawReader [in] AliRoot RawReader instance
 164    * @param runloader [in] AliRoot runloader
 165    * @return neg. error code if failed
 166    */
 167   virtual int CreateConfigurations(AliHLTConfigurationHandler* handler,
 168                                    AliRawReader* rawReader=NULL,
 169                                    AliRunLoader* runloader=NULL) const;
 170
 171   /**
 172    * Get the top configurations for event reconstruction.
 173    * A top configuration describes a processing chain. It can simply be
 174    * described by the last configuration(s) in the chain.
 175    * The agent can adapt the configurations to be registered to the current
 176    * AliRoot setup by checking the run loader and the raw reader.
 177    * @param rawReader [in] AliRoot RawReader instance
 178    * @param runloader [in] AliRoot runloader
 179    * @return string containing the top configurations separated by blanks
 180    */
 181   virtual const char* GetReconstructionChains(AliRawReader* rawReader=NULL,
 182                                               AliRunLoader* runloader=NULL) const;
 183
 184   /**
 185    * Component libraries which the configurations of this agent depend on. <br>
 186    * @note This is not the right place to specify libraries which this component
 187    * library depends. Dependencies must be linked or loaded before.
 188    * @return list of component libraries as a blank-separated string.
 189    */
 190   virtual const char* GetRequiredComponentLibraries() const;
 191
 192   /**
 193    * Register components.
 194    * This method can be used to register components for the module instead
 195    * of the 'static object approach'. Registration is done by passing a
 196    * sample object to the AliHLTComponentHandler via
 197    * - @ref AliHLTComponentHandler::RegisterComponent                      <br>
 198    *        The sample object is owned by the agent, make sure to delete it.
 199    * - @ref AliHLTComponentHandler::AddComponent                           <br>
 200    *        Same functionality but handler deletes the object at the end.
 201    *
 202    * @param pHandler  [in] instance of the component handler
 203    */
 204   virtual int RegisterComponents(AliHLTComponentHandler* pHandler) const;
 205
 206   /**
 207    * IDs for output handlers.
 208    * The agent can provide output handlers in order to treat the output
 209    * data coming from the HLTOUT nodes.
 210    */
 211   enum AliHLTOUTHandlerType {
 212     kUnknownOutput =0,
 213     /** output is in ESD format */
 214     kEsd,
 215     /** agent can create a raw stream */
 216     kRawstream,
 217     /** agent provides a chain */
 218     kChain,
 219     /** agent provides detector specific handler */
 220     kProprietary,
 221     kLastOutputHandler
 222   };
 223
 224   /**
 225    * Output handler description.
 226    * \em fModule: module name specific for the handler type
 227    *              - kRawStream: class name of the Rawstream class
 228    *              - kChain:     blank separated list of chains
 229    *              - kProprietary: name of the handler class
 230    */
 231   struct AliHLTOUTHandlerDesc {
 232     /** type of the handler */
 233     AliHLTOUTHandlerType    fHType;
 234     /** data type treated by the handler */
 235     AliHLTComponentDataType fDt;
 236     /** class or chain name */
 237     const char*             fModule;
 238   };
 239
 240   /**
 241    * Get handler description for a data block.
 242    * @param dt        [in] data type of the block
 243    * @param spec      [in] specification of the block
 244    * @param desc      [out] handler description
 245    * @return 1 if the agent can provide a handler, 0 if not
 246    */
 247   virtual int GetHandlerDescription(AliHLTComponentDataType dt,
 248                                     AliHLTUInt32_t spec,
 249                                     AliHLTOUTHandlerDesc& desc) const;
 250   /**
 251    * Get handler for a data block of the HLTOUT data.
 252    * @param dt        [in] data type of the block
 253    * @param spec      [in] specification of the block
 254    */
 255   virtual AliHLTOUTHandler* GetOutputHandler(AliHLTComponentDataType dt,
 256                                              AliHLTUInt32_t spec) const;
 257
 258   /**
 259    * Get raw stream for a data block.
 260    * @param dt        [in] data type of the block
 261    * @param spec      [in] specification of the block
 262    * @param pData     [in] data control object
 263    * @return Rawstream object, NULL if no Rawstream available for data type/spec
 264    */
 265   virtual AliRawStream* GetRawStream(AliHLTComponentDataType dt,
 266                                      AliHLTUInt32_t spec,
 267                                      const AliHLTOUT* pData) const;
 268
 269   /**
 270    * Old method kept for backward compatibility, redirected to @ref
 271    * GetReconstructionChains.
 272    */
 273   const char* GetTopConfigurations(AliRunLoader* runloader=NULL) const {
 274     return GetReconstructionChains(NULL,runloader);
 275   }
 276
 277  protected:
 278
 279  private:
 280   /** copy constructor prohibited */
 281   AliHLTModuleAgent(const AliHLTModuleAgent&);
 282   /** assignment operator prohibited */
 283   AliHLTModuleAgent& operator=(const AliHLTModuleAgent&);
 284
 285   /**
 286    * Register agent in the global list.
 287    * @return neg. error code if failed
 288    */
 289   static int Register(AliHLTModuleAgent* pAgent);
 290
 291   /**
 292    * Unregister agent in the global list.
 293    * @return neg. error code if failed
 294    */
 295   static int Unregister(AliHLTModuleAgent* pAgent);
 296
 297   /** the list of active agents */
 298   static AliHLTModuleAgent* fAnchor;                               //! transient
 299
 300   /** next element in the list */
 301   AliHLTModuleAgent* fpNext;                                       //! transient
 302
 303   /** the current object link (list position) */
 304   static AliHLTModuleAgent* fCurrent;                              //! transient
 305
 306   /** number of agents */
 307   static int fCount;                                               //! transient
 308
 309   /* instance of the active component handler */
 310   AliHLTComponentHandler* fpComponentHandler;                      //! transient
 311
 312   ClassDef(AliHLTModuleAgent, 2);
 313 };
 314
 315 #endif