include/GaudiKernel/AlgTool.h

0001 /***********************************************************************************\
0002 * (c) Copyright 1998-2024 CERN for the benefit of the LHCb and ATLAS collaborations *
0003 *                                                                                   *
0004 * This software is distributed under the terms of the Apache version 2 licence,     *
0005 * copied verbatim in the file "LICENSE".                                            *
0006 *                                                                                   *
0007 * In applying this licence, CERN does not waive the privileges and immunities       *
0008 * granted to it by virtue of its status as an Intergovernmental Organization        *
0009 * or submit itself to any jurisdiction.                                             *
0010 \***********************************************************************************/
0011 #ifndef GAUDIKERNEL_ALGTOOL_H
0012 #define GAUDIKERNEL_ALGTOOL_H
0013 // ============================================================================
0014 // Include files
0015 #include <Gaudi/PluginService.h>
0016 #include <GaudiKernel/CommonMessaging.h>
0017 #include <GaudiKernel/DataObjID.h>
0018 #include <GaudiKernel/IAlgTool.h>
0019 #include <GaudiKernel/IAuditorSvc.h>
0020 #include <GaudiKernel/IDataProviderSvc.h>
0021 #include <GaudiKernel/IMessageSvc.h>
0022 #include <GaudiKernel/IMonitorSvc.h>
0023 #include <GaudiKernel/IProperty.h>
0024 #include <GaudiKernel/IService.h>
0025 #include <GaudiKernel/IStateful.h>
0026 #include <GaudiKernel/ISvcLocator.h>
0027 #include <GaudiKernel/IToolSvc.h>
0028 #include <GaudiKernel/PropertyHolder.h>
0029 #include <GaudiKernel/ToolHandle.h>
0030
0031 #include <GaudiKernel/DataHandle.h>
0032 #include <GaudiKernel/DataHandleHolderBase.h>
0033 #include <GaudiKernel/IDataHandleHolder.h>
0034
0035 template <class T>
0036 class DataObjectHandle;
0037
0038 class ToolHandleInfo;
0039
0040 #include <list>
0041 #include <vector>
0042
0043 // Forward declarations
0044 class ToolSvc;
0045
0046 class ToolVisitor;
0047
0048 /** @class AlgTool AlgTool.h GaudiKernel/AlgTool.h
0049  *
0050  *  Base class from which all the concrete tool classes
0051  *  should be derived. Specific methods for doing something
0052  *  useful should be implemented in the concrete tools.
0053  *  Sub-types of this class could implement an additional
0054  *  interface for behavior common to sets of concrete tools
0055  *  (for example vertexers).
0056  *
0057  *  @author Gloria Corti
0058  *  @author Pere Mato
0059  */
0060 class GAUDI_API AlgTool
0061     : public DataHandleHolderBase<
0062           PropertyHolder<CommonMessaging<implements<IAlgTool, IDataHandleHolder, IProperty, IStateful>>>> {
0063   friend ToolSvc;
0064   friend class ToolVisitor;
0065
0066 public:
0067   using Factory = Gaudi::PluginService::Factory<IAlgTool*( const std::string&, const std::string&, const IInterface* )>;
0068
0069   /// Query for a given interface
0070   StatusCode queryInterface( const InterfaceID& riid, void** ppvUnknown ) override;
0071
0072   /// Retrieve full identifying name of the concrete tool object.
0073   const std::string& name() const override;
0074
0075   /// Retrieve type (concrete class) of the sub-algtool.
0076   const std::string& type() const override;
0077
0078   /// Retrieve parent of the sub-algtool.
0079   const IInterface* parent() const override;
0080
0081   // State machine implementation
0082   StatusCode                 configure() override { return StatusCode::SUCCESS; }
0083   StatusCode                 initialize() override;
0084   StatusCode                 start() override;
0085   StatusCode                 stop() override;
0086   StatusCode                 finalize() override;
0087   StatusCode                 terminate() override { return StatusCode::SUCCESS; }
0088   StatusCode                 reinitialize() override;
0089   StatusCode                 restart() override;
0090   Gaudi::StateMachine::State FSMState() const override { return m_state; }
0091   Gaudi::StateMachine::State targetFSMState() const override { return m_targetState; }
0092
0093   /// Initialize AlgTool
0094   StatusCode sysInitialize() override;
0095
0096   /// Start AlgTool
0097   StatusCode sysStart() override;
0098
0099   /// Stop AlgTool
0100   StatusCode sysStop() override;
0101
0102   /// Finalize AlgTool
0103   StatusCode sysFinalize() override;
0104
0105   /// Initialize AlgTool
0106   StatusCode sysReinitialize() override;
0107
0108   /// Start AlgTool
0109   StatusCode sysRestart() override;
0110
0111 public:
0112   /** Standard Constructor.
0113    *  @param type the concrete class of the sub-algtool
0114    *  @param name the full name of the concrete sub-algtool
0115    *  @param parent the parent of the concrete sub-algtool
0116    */
0117   AlgTool( std::string type, std::string name, const IInterface* parent );
0118
0119   /// Retrieve pointer to service locator.
0120   SmartIF<ISvcLocator>& serviceLocator() const override;
0121
0122   /// shortcut for the method service locator
0123   ISvcLocator* svcLoc() const { return serviceLocator(); }
0124
0125   /** accessor to event service  service
0126    *  @return pointer to detector service
0127    */
0128   IDataProviderSvc* evtSvc() const;
0129
0130   /// The standard ToolSvc service, Return a pointer to the service if present
0131   IToolSvc* toolSvc() const;
0132
0133   /** Access a service by name,
0134    *  creating it if it doesn't already exist.
0135    */
0136   template <class T>
0137   [[deprecated( "use service<T>(name, createIf) -> SmartIF<T>" )]] StatusCode service( std::string_view name, T*& svc,
0138                                                                                        bool createIf = true ) const {
0139     return service_i( name, createIf, T::interfaceID(), (void**)&svc );
0140   }
0141
0142   /** Access a service by name, type creating it if it doesn't already exist.
0143    */
0144   template <class T>
0145   [[deprecated( "use service<T>(name, createIf) -> SmartIF<T>" )]] StatusCode
0146   service( std::string_view type, std::string_view name, T*& svc ) const {
0147     return service_i( type, name, T::interfaceID(), reinterpret_cast<void**>( &svc ) );
0148   }
0149
0150   /// Return a pointer to the service identified by name (or "type/name")
0151   SmartIF<IService> service( std::string_view name, const bool createIf = true, const bool quiet = false ) const;
0152
0153   template <typename T>
0154   SmartIF<T> service( std::string_view name, const bool createIf = true, const bool quiet = false ) const {
0155     return SmartIF<T>( service( name, createIf, quiet ) );
0156   }
0157
0158 protected:
0159   template <typename I>
0160   void declareInterface( I* i ) {
0161     m_interfaceList.emplace_back( I::interfaceID(), i );
0162   }
0163
0164 public:
0165   using PropertyHolderImpl::declareProperty;
0166
0167   template <class T>
0168   Gaudi::Details::PropertyBase* declareProperty( const std::string& name, ToolHandle<T>& hndl,
0169                                                  const std::string& doc = "none" ) {
0170     this->declareTool( hndl, hndl.typeAndName() ).ignore();
0171     return PropertyHolderImpl::declareProperty( name, hndl, doc );
0172   }
0173
0174   template <class T>
0175   StatusCode declareTool( ToolHandle<T>& handle, bool createIf = true ) {
0176     return this->declareTool( handle, handle.typeAndName(), createIf );
0177   }
0178
0179   template <class T>
0180   StatusCode declareTool( ToolHandle<T>& handle, const std::string& toolTypeAndName, bool createIf = true ) {
0181
0182     StatusCode sc = handle.initialize( toolTypeAndName, handle.isPublic() ? nullptr : this, createIf );
0183     if ( !sc ) {
0184       throw GaudiException{ std::string{ "Cannot create handle for " } + ( handle.isPublic() ? "public" : "private" ) +
0185                                 " tool " + toolTypeAndName,
0186                             name(), sc };
0187     }
0188
0189     m_toolHandles.push_back( &handle );
0190
0191     return sc;
0192   }
0193
0194   // ==========================================================================
0195   // declare ToolHandleArrays to the AlgTool
0196   template <class T>
0197   Gaudi::Details::PropertyBase* declareProperty( const std::string& name, ToolHandleArray<T>& hndlArr,
0198                                                  const std::string& doc = "none" ) {
0199     addToolsArray( hndlArr );
0200     return PropertyHolderImpl::declareProperty( name, hndlArr, doc );
0201   }
0202
0203   template <class T>
0204   void addToolsArray( ToolHandleArray<T>& hndlArr ) {
0205     m_toolHandleArrays.push_back( &hndlArr );
0206   }
0207
0208 public:
0209   void acceptDHVisitor( IDataHandleVisitor* ) const override;
0210
0211 public:
0212   void registerTool( IAlgTool* tool ) const {
0213     if ( msgLevel( MSG::DEBUG ) ) debug() << "Registering tool " << tool->name() << endmsg;
0214     m_tools.push_back( tool );
0215   }
0216
0217   void deregisterTool( IAlgTool* tool ) const {
0218     auto it = std::find( m_tools.begin(), m_tools.end(), tool );
0219     if ( it != m_tools.end() ) {
0220       if ( msgLevel( MSG::DEBUG ) ) debug() << "De-Registering tool " << tool->name() << endmsg;
0221       m_tools.erase( it );
0222     } else {
0223       if ( msgLevel( MSG::DEBUG ) ) debug() << "Could not de-register tool " << tool->name() << endmsg;
0224     }
0225   }
0226
0227   const std::vector<IAlgTool*>& tools() const;
0228
0229 protected:
0230   std::vector<IAlgTool*>& tools();
0231
0232   /// Hook for for derived classes to provide a custom visitor for data handles.
0233   std::unique_ptr<IDataHandleVisitor> m_updateDataHandles;
0234
0235 private:
0236   // place IAlgTools defined via ToolHandles in m_tools
0237   void initToolHandles() const;
0238
0239 public:
0240   // ==========================================================================
0241   /// Access the auditor service
0242   IAuditorSvc* auditorSvc() const;
0243
0244   /** @brief Access the monitor service
0245    *
0246    *   @attention Note that this method will return a NULL pointer if no monitor service is
0247    *              configured to be present. You must take this possibility into account when
0248    *              using the pointer
0249    *   @return Pointer to the Monitor service
0250    *   @retval NULL No monitor service is present
0251    *   @retval non-NULL A monitor service is present and available to be used
0252    */
0253   inline IMonitorSvc* monitorSvc() const {
0254     // If not already located try to locate it without forcing a creation
0255     if ( !m_pMonitorSvc ) m_pMonitorSvc = service( m_monitorSvcName, false, true );
0256     return m_pMonitorSvc.get();
0257   }
0258
0259   /** Declare monitoring information
0260       @param name Monitoring information name known to the external system
0261       @param var  Monitoring Listener address (the item to monitor...)
0262       @param desc Textual description of the information being monitored
0263   */
0264   template <class T>
0265   void declareInfo( const std::string& name, const T& var, const std::string& desc ) const {
0266     IMonitorSvc* mS = monitorSvc();
0267     if ( mS ) mS->declareInfo( name, var, desc, this );
0268   }
0269
0270   /** Declare monitoring information (special case)
0271       @param name Monitoring information name known to the external system
0272       @param format Format information
0273       @param var  Monitoring Listener address
0274       @param size Monitoring Listener address size
0275       @param desc Textual description of the information being monitored
0276   */
0277   void declareInfo( const std::string& name, const std::string& format, const void* var, int size,
0278                     const std::string& desc ) const {
0279     IMonitorSvc* mS = monitorSvc();
0280     if ( mS ) mS->declareInfo( name, format, var, size, desc, this );
0281   }
0282
0283   // Standard destructor.
0284   ~AlgTool() override;
0285
0286 private:
0287   typedef std::list<std::pair<InterfaceID, void*>> InterfaceList;
0288
0289   std::string       m_type;             ///< AlgTool type (concrete class name)
0290   const std::string m_name;             ///< AlgTool full name
0291   const IInterface* m_parent = nullptr; ///< AlgTool parent
0292
0293   mutable SmartIF<ISvcLocator>      m_svcLocator;  ///< Pointer to Service Locator service
0294   mutable SmartIF<IDataProviderSvc> m_evtSvc;      ///< Event data service
0295   mutable SmartIF<IToolSvc>         m_ptoolSvc;    ///< Tool service
0296   mutable SmartIF<IMonitorSvc>      m_pMonitorSvc; ///< Online Monitoring Service
0297   mutable SmartIF<IAuditorSvc>      m_pAuditorSvc; ///< Auditor Service
0298
0299   InterfaceList m_interfaceList; ///< Interface list
0300
0301   // Properties
0302   // initialize output level from MessageSvc and initialize messaging (before enabling update handler)
0303   Gaudi::Property<int> m_outputLevel{
0304       this, "OutputLevel", setUpMessaging(),
0305       [this]( Gaudi::Details::PropertyBase& ) { this->updateMsgStreamOutputLevel( this->m_outputLevel ); },
0306       "output level" };
0307
0308   Gaudi::Property<std::string> m_monitorSvcName{ this, "MonitorService", "MonitorSvc",
0309                                                  "name to use for Monitor Service" };
0310
0311   Gaudi::Property<bool> m_auditInit{ this, "AuditTools", false, "[[deprecated]] unused" };
0312   Gaudi::Property<bool> m_auditorInitialize{ this, "AuditInitialize", false, "trigger auditor on initialize()" };
0313   Gaudi::Property<bool> m_auditorStart{ this, "AuditStart", false, "trigger auditor on start()" };
0314   Gaudi::Property<bool> m_auditorStop{ this, "AuditStop", false, "trigger auditor on stop()" };
0315   Gaudi::Property<bool> m_auditorFinalize{ this, "AuditFinalize", false, "trigger auditor on finalize()" };
0316   Gaudi::Property<bool> m_auditorReinitialize{ this, "AuditReinitialize", false, "trigger auditor on reinitialize()" };
0317   Gaudi::Property<bool> m_auditorRestart{ this, "AuditRestart", false, "trigger auditor on restart()" };
0318
0319   // tools used by tool
0320   mutable std::vector<IAlgTool*>             m_tools;
0321   mutable std::vector<BaseToolHandle*>       m_toolHandles;
0322   mutable std::vector<GaudiHandleArrayBase*> m_toolHandleArrays;
0323   mutable bool m_toolHandlesInit = false; /// flag indicating whether ToolHandle tools have been added to m_tools
0324
0325   /** implementation of legacy service method */
0326   [[deprecated]] StatusCode service_i( std::string_view algName, bool createIf, const InterfaceID& iid,
0327                                        void** ppSvc ) const;
0328   [[deprecated]] StatusCode service_i( std::string_view svcType, std::string_view svcName, const InterfaceID& iid,
0329                                        void** ppS ) const;
0330
0331   Gaudi::StateMachine::State m_state       = Gaudi::StateMachine::CONFIGURED; ///< state of the Tool
0332   Gaudi::StateMachine::State m_targetState = Gaudi::StateMachine::CONFIGURED; ///< state of the Tool
0333 };
0334
0335 #endif // GAUDIKERNEL_ALGTOOL_H