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