ToolHandle.h

Go to the documentation of this file.

/***********************************************************************************\
* (c) Copyright 1998-2025 CERN for the benefit of the LHCb and ATLAS collaborations *
*                                                                                   *
* This software is distributed under the terms of the Apache version 2 licence,     *
* copied verbatim in the file "LICENSE".                                            *
*                                                                                   *
* In applying this licence, CERN does not waive the privileges and immunities       *
* granted to it by virtue of its status as an Intergovernmental Organization        *
* or submit itself to any jurisdiction.                                             *
\***********************************************************************************/
#ifndef GAUDIKERNEL_TOOLHANDLE_H
#define GAUDIKERNEL_TOOLHANDLE_H
 
// Includes
#include <GaudiKernel/GaudiHandle.h>
#include <GaudiKernel/IAlgTool.h>
#include <GaudiKernel/IBinder.h>
#include <GaudiKernel/INamedInterface.h>
#include <GaudiKernel/IToolSvc.h>
#include <GaudiKernel/ServiceHandle.h>
#include <GaudiKernel/TaggedBool.h>
 
#include <cassert>
#include <concepts>
#include <ostream>
#include <string>
#include <tuple>
#include <type_traits>
#include <utility>
#include <vector>
 
// forward declarations
class IInterface;
class IToolSvc;
 
namespace Gaudi {
  class Algorithm;
}
class AlgTool;
class Service;
 
using DisableTool = Gaudi::tagged_bool<class DisableTool_tag>;
using EnableTool  = Gaudi::tagged_bool<class EnableTool_tag>;
 
class ToolHandleInfo {
 
protected:
  ToolHandleInfo( const IInterface* parent = nullptr, bool createIf = true )
      : m_parent( parent ), m_createIf( createIf ) {}
 
public:
  virtual ~ToolHandleInfo() = default;
 
  bool isPublic() const noexcept { return !m_parent; }
 
  bool createIf() const noexcept { return m_createIf; }
 
  const IInterface* parent() const noexcept { return m_parent; }
 
  //
  // Some helper functions
  //
 
  static std::string toolComponentType( const IInterface* parent ) { return parent ? "PrivateTool" : "PublicTool"; }
 
  static std::string toolParentName( const IInterface* parent ) {
    auto* pNamed = ( parent ? dynamic_cast<const INamedInterface*>( parent ) : nullptr );
    return ( !parent ? "ToolSvc" : ( pNamed ? pNamed->name() : "" ) );
  }
 
protected:
  const IInterface* m_parent = nullptr;
  bool              m_createIf{ true };
};
 
class BaseToolHandle : public ToolHandleInfo {
 
protected:
  BaseToolHandle( const IInterface* parent = nullptr, bool createIf = true ) : ToolHandleInfo( parent, createIf ) {}
 
  virtual StatusCode i_retrieve( IAlgTool*& ) const = 0;
 
public:
  StatusCode retrieve( IAlgTool*& tool ) const { return i_retrieve( tool ); }
 
  virtual StatusCode retrieve() const           = 0;
  virtual StatusCode retrieve( DisableTool sd ) = 0;
  virtual StatusCode retrieve( EnableTool sd )  = 0;
 
  const IAlgTool* get() const { return getAsIAlgTool(); }
 
  IAlgTool* get() { return getAsIAlgTool(); }
 
  virtual std::string typeAndName() const = 0;
 
  bool isEnabled() const {
    // the handle is considered enabled if the type/name is valid and the
    // enabled flag was set to true, or it was already retrieved
    return ( m_enabled && !typeAndName().empty() ) || get();
  }
 
  void enable() { m_enabled = true; }
 
  void disable() { m_enabled = false; }
 
  bool setEnabled( bool flag ) { return std::exchange( m_enabled, flag ); }
 
protected:
  virtual const IAlgTool* getAsIAlgTool() const = 0;
 
  virtual IAlgTool* getAsIAlgTool() = 0;
 
  bool m_enabled = true;
};
 
template <class T>
class ToolHandle : public BaseToolHandle, public GaudiHandle<T> {
 
  friend class Gaudi::Algorithm;
  friend class AlgTool;
  friend class Service;
 
  template <typename... Args, std::size_t... Is>
  ToolHandle( std::tuple<Args...>&& args, std::index_sequence<Is...> )
      : ToolHandle( std::get<Is>( std::move( args ) )... ) {}
 
public:
  ToolHandle( const IInterface* parent = nullptr, bool createIf = true )
      : BaseToolHandle( parent, createIf )
      , GaudiHandle<T>( "", toolComponentType( parent ), toolParentName( parent ) )
      , m_pToolSvc( "ToolSvc", GaudiHandleBase::parentName() ) {}
 
  template <typename CT = T, typename NCT = std::remove_const_t<T>>
    requires( std::is_const_v<CT> && !std::is_same_v<CT, NCT> )
  ToolHandle( const ToolHandle<NCT>& other )
      : BaseToolHandle( other.parent(), other.createIf() )
      , GaudiHandle<CT>( other )
      , m_pToolSvc( "ToolSvc", GaudiHandleBase::parentName() ) {}
 
public:
  //
  // Constructors etc.
  //
 
#if defined( TOOLHANDLE_DEPR_WARN )
// warn about using deprecated explicit ToolHandle construction
#  pragma message( "Untracked ToolHandle: Migrate explicit DataHandle constructor to declareTool Algorithm Property" )
 
  __attribute__( ( deprecated ) )
 
#endif
  ToolHandle( const std::string& toolTypeAndName, const IInterface* parent = nullptr, bool createIf = true )
      : BaseToolHandle( parent, createIf )
      , GaudiHandle<T>( toolTypeAndName, toolComponentType( parent ), toolParentName( parent ) )
      , m_pToolSvc( "ToolSvc", GaudiHandleBase::parentName() ) {
  }
 
  template <std::derived_from<IProperty> OWNER>
  ToolHandle( OWNER* owner, std::string propName, std::string toolType, std::string doc = "" ) : ToolHandle( owner ) {
    // convert name and type to a valid type/name string
    // - if type does not contain '/' use type/type
    // - otherwise type is already a type/name string
    if ( !toolType.empty() and toolType.find( '/' ) == std::string::npos ) { toolType += '/' + toolType; }
    owner->declareTool( *this, std::move( toolType ) ).ignore();
    auto p = owner->OWNER::PropertyHolderImpl::declareProperty( std::move( propName ), *this, std::move( doc ) );
    p->template setOwnerType<OWNER>();
  }
 
  template <typename... Args>
  ToolHandle( std::tuple<Args...>&& args ) : ToolHandle( std::move( args ), std::index_sequence_for<Args...>{} ) {}
 
public:
  StatusCode initialize( const std::string& toolTypeAndName, const IInterface* parent = nullptr,
                         bool createIf = true ) {
 
    GaudiHandleBase::setTypeAndName( toolTypeAndName );
    GaudiHandleBase::setComponentType( toolComponentType( parent ) );
    GaudiHandleBase::setParentName( toolParentName( parent ) );
 
    m_parent   = parent;
    m_createIf = createIf;
 
    return m_pToolSvc.initialize( "ToolSvc", GaudiHandleBase::parentName() );
  }
 
  StatusCode retrieve() const override { // not really const, because it updates m_pObject
    return GaudiHandle<T>::retrieve();
  }
 
  StatusCode retrieve( DisableTool sd ) override {
    if ( isEnabled() && sd == DisableTool{ false } ) {
      return GaudiHandle<T>::retrieve();
    } else {
      disable();
      return StatusCode::SUCCESS;
    }
  }
 
  StatusCode retrieve( EnableTool sd ) override {
    if ( isEnabled() && sd == EnableTool{ true } ) {
      return GaudiHandle<T>::retrieve();
    } else {
      disable();
      return StatusCode::SUCCESS;
    }
  }
 
  StatusCode release() const { // not really const, because it updates m_pObject
    return GaudiHandle<T>::release();
  }
 
  StatusCode retrieve( T*& algTool ) const override {
    IAlgTool* iface = nullptr;
    if ( i_retrieve( iface ).isFailure() ) { return StatusCode::FAILURE; }
 
    algTool = dynamic_cast<T*>( iface );
    if ( !algTool ) {
      throw GaudiException( "unable to dcast AlgTool " + typeAndName() + " to interface " +
                                System::typeinfoName( typeid( T ) ),
                            typeAndName() + " retrieve", StatusCode::FAILURE );
    }
    return StatusCode::SUCCESS;
  }
 
  StatusCode release( T* algTool ) const override { return m_pToolSvc->releaseTool( ::details::nonConst( algTool ) ); }
 
  std::string typeAndName() const override { return GaudiHandleBase::typeAndName(); }
 
  std::add_const_t<T>* get() const { return GaudiHandle<T>::get(); }
 
  T* get() { return GaudiHandle<T>::get(); }
 
  friend std::ostream& operator<<( std::ostream& os, const ToolHandle<T>& handle ) {
    return os << static_cast<const GaudiHandleInfo&>( handle );
  }
 
protected:
  const IAlgTool* getAsIAlgTool() const override {
    // const cast to support T being const
    return GaudiHandle<T>::get();
  }
 
  IAlgTool* getAsIAlgTool() override {
    // const cast to support T being const
    return ::details::nonConst( GaudiHandle<T>::get() );
  }
 
  StatusCode i_retrieve( IAlgTool*& algTool ) const override {
    return m_pToolSvc->retrieve( typeAndName(), IAlgTool::interfaceID(), algTool, ToolHandleInfo::parent(),
                                 ToolHandleInfo::createIf() );
  }
 
private:
  //
  // Private data members
  //
  mutable ServiceHandle<IToolSvc> m_pToolSvc;
};
 
// explicit specialization for IBinder<IFace>
template <typename IFace>
class ToolHandle<Gaudi::Interface::Bind::IBinder<IFace>> : public ToolHandle<IAlgTool> {
 
  void* m_ptr                                                                        = nullptr;
  Gaudi::Interface::Bind::Box<IFace> ( *m_bind )( void const*, const EventContext& ) = nullptr;
 
public:
  using ToolHandle<IAlgTool>::ToolHandle;
  using ToolHandle<IAlgTool>::retrieve;
  StatusCode retrieve() const override {
    // FIXME: why is `retrieve` const????
    auto self = const_cast<ToolHandle<Gaudi::Interface::Bind::IBinder<IFace>>*>( this );
 
    return ToolHandle<IAlgTool>::retrieve().andThen( [&] {
      const IAlgTool* tool = get();
      assert( tool != nullptr ); // retrieve was succesfull, so get() better return something valid!
      return const_cast<IAlgTool*>( tool )
          ->queryInterface( IFace::interfaceID(), &( self->m_ptr ) )
          .andThen( [&] {
            // TODO: what happens to the refCount?
            self->m_bind = []( const void* ptr, const EventContext& ) {
              return Gaudi::Interface::Bind::Box<IFace>( static_cast<IFace const*>( ptr ) );
            };
          } )
          .orElse( [&]() {
            return const_cast<IAlgTool*>( tool )
                ->queryInterface( Gaudi::Interface::Bind::IBinder<IFace>::interfaceID(), &( self->m_ptr ) )
                .andThen( [&] {
                  // TODO: what happens to the refCount?
                  self->m_bind = []( const void* ptr, const EventContext& ctx ) {
                    return static_cast<Gaudi::Interface::Bind::IBinder<IFace> const*>( ptr )->bind( ctx );
                  };
                } );
          } );
    } );
  }
 
  auto bind( const EventContext& ctx ) const {
    if ( !m_bind || !m_ptr ) {
      throw GaudiException{ "request bind on toolhandle which was not (successfully) 'retrieved'", __PRETTY_FUNCTION__,
                            StatusCode::FAILURE };
    }
    return ( *m_bind )( m_ptr, ctx );
  }
};
 
template <class T>
class PublicToolHandle : public ToolHandle<T> {
public:
  PublicToolHandle( bool createIf = true ) : ToolHandle<T>( nullptr, createIf ) {}
  PublicToolHandle( const char* toolTypeAndName, bool createIf = true )
      : PublicToolHandle{ std::string{ toolTypeAndName }, createIf } {}
  PublicToolHandle( const std::string& toolTypeAndName, bool createIf = true )
      : ToolHandle<T>( toolTypeAndName, nullptr, createIf ) {}
 
  template <typename CT = T, typename NCT = std::remove_const_t<T>>
    requires( std::is_const_v<CT> && !std::is_same_v<CT, NCT> )
  PublicToolHandle( const PublicToolHandle<NCT>& other )
      : ToolHandle<T>( static_cast<const ToolHandle<NCT>&>( other ) ) {}
 
  template <std::derived_from<IProperty> OWNER>
  inline PublicToolHandle( OWNER* owner, std::string propName, std::string toolType, std::string doc = "" )
      : PublicToolHandle() {
    // convert name and type to a valid type/name string
    // - if type does not contain '/' use type/type
    // - otherwise type is already a type/name string
    if ( !toolType.empty() and toolType.find( '/' ) == std::string::npos ) { toolType += '/' + toolType; }
    owner->declareTool( *this, std::move( toolType ) ).ignore();
    auto p = owner->OWNER::PropertyHolderImpl::declareProperty( std::move( propName ), *this, std::move( doc ) );
    p->template setOwnerType<OWNER>();
  }
};
 
//-------------------------------------------------------------------------//
 
template <class T>
class ToolHandleArray : public ToolHandleInfo, public GaudiHandleArray<ToolHandle<T>> {
public:
  //
  // Constructors
  //
  ToolHandleArray( const std::vector<std::string>& myTypesAndNames, const IInterface* parent = nullptr,
                   bool createIf = true )
      : ToolHandleInfo( parent, createIf )
      , GaudiHandleArray<ToolHandle<T>>( myTypesAndNames, ToolHandleInfo::toolComponentType( parent ),
                                         ToolHandleInfo::toolParentName( parent ) ) {}
 
  ToolHandleArray( const IInterface* parent = nullptr, bool createIf = true )
      : ToolHandleInfo( parent, createIf )
      , GaudiHandleArray<ToolHandle<T>>( ToolHandleInfo::toolComponentType( parent ),
                                         ToolHandleInfo::toolParentName( parent ) ) {}
 
  bool push_back( const std::string& toolTypeAndName ) override {
    ToolHandle<T> handle( toolTypeAndName, ToolHandleInfo::parent(), ToolHandleInfo::createIf() );
    GaudiHandleArray<ToolHandle<T>>::push_back( handle );
    return true;
  }
 
  bool push_back( const ToolHandle<T>& myHandle ) override { return push_back( myHandle.typeAndName() ); }
 
  template <std::derived_from<IProperty> OWNER>
  inline ToolHandleArray( OWNER* owner, std::string name, const std::vector<std::string>& typesAndNames = {},
                          std::string doc = "" )
      : ToolHandleArray( owner ) {
    owner->addToolsArray( *this );
    this->setTypesAndNames( typesAndNames );
    auto p = owner->OWNER::PropertyHolderImpl::declareProperty( std::move( name ), *this, std::move( doc ) );
    p->template setOwnerType<OWNER>();
  }
 
  friend std::ostream& operator<<( std::ostream& os, const ToolHandleArray<T>& handle ) {
    return os << static_cast<const GaudiHandleInfo&>( handle );
  }
};
 
template <class T>
class PublicToolHandleArray : public ToolHandleArray<T> {
public:
  PublicToolHandleArray( bool createIf = true ) : ToolHandleArray<T>( nullptr, createIf ) {}
  PublicToolHandleArray( const std::vector<std::string>& typesAndNames, bool createIf = true )
      : ToolHandleArray<T>( typesAndNames, nullptr, createIf ) {}
 
  template <std::derived_from<IProperty> OWNER>
  PublicToolHandleArray( OWNER* owner, std::string name, const std::vector<std::string>& typesAndNames = {},
                         std::string doc = "" )
      : PublicToolHandleArray() {
    owner->addToolsArray( *this );
    this->setTypesAndNames( typesAndNames );
    auto p = owner->OWNER::PropertyHolderImpl::declareProperty( std::move( name ), *this, std::move( doc ) );
    p->template setOwnerType<OWNER>();
  }
};
 
#endif // ! GAUDIKERNEL_TOOLHANDLE_H