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