GaudiHandle.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.                                             *
\***********************************************************************************/
#pragma once
 
#include <Gaudi/Property.h>
#include <GaudiKernel/GaudiException.h>
#include <GaudiKernel/IInterface.h>
#include <GaudiKernel/System.h>
#include <algorithm>
#include <iostream>
#include <string>
#include <type_traits>
#include <vector>
 
namespace details {
  template <class T>
  std::remove_const_t<T>* nonConst( T* p ) {
    return const_cast<std::remove_const_t<T>*>( p );
  }
} // namespace details
 
class GAUDI_API GaudiHandleInfo {
protected:
  GaudiHandleInfo( std::string myComponentType, std::string myParentName )
      : m_componentType( std::move( myComponentType ) ), m_parentName( std::move( myParentName ) ) {}
 
public:
  // Don't use =default here.  Otherwise, in c++20 mode, clang will
  // instantiate the handle virtual functions early, breaking the case
  // where handles are used with a forward-declared class.
  virtual ~GaudiHandleInfo() {}
  //
  // Public member functions
  //
  const std::string& componentType() const { return m_componentType; }

  const std::string& propertyName() const { return m_propertyName; }

  void setPropertyName( std::string propName ) { m_propertyName = std::move( propName ); }

  const std::string& parentName() const { return m_parentName; }

  virtual std::string pythonPropertyClassName() const = 0;

  virtual std::string pythonRepr() const = 0;
 
  // Easy printing out of Handles and HandleArrays
  // It prints <propertyName> = <HandleType>( <HandleType(s)AndName(s)> )
  friend std::ostream& operator<<( std::ostream& os, const GaudiHandleInfo& handle );
 
protected:
  void setComponentType( std::string componentType ) { m_componentType = std::move( componentType ); }

  void setParentName( std::string parent ) { m_parentName = std::move( parent ); }
 
private:
  //
  // Data members
  //
  std::string m_componentType; // e.g.: "PublicTool","PrivateTool","Service"
  std::string m_propertyName;  // name as used in declareProperty(name,gaudiHandle)
  std::string m_parentName;    // name of the parent having this handle as a member
};

class GAUDI_API GaudiHandleBase : public GaudiHandleInfo {
  //
  // Ctors etc
  //
protected:
  GaudiHandleBase( std::string myTypeAndName, std::string myComponentType, std::string myParentName )
      : GaudiHandleInfo( std::move( myComponentType ), std::move( myParentName ) ) {
    setTypeAndName( std::move( myTypeAndName ) );
  }
 
public:
  //
  // Public member functions
  //
  const std::string& typeAndName() const { return m_typeAndName; }

  std::string type() const;

  std::string name() const;

  bool empty() const { return m_typeAndName.empty(); }

  void setTypeAndName( std::string myTypeAndName );

  void setName( std::string_view myName );

  std::string pythonPropertyClassName() const override;

  std::string messageName() const;

  std::string pythonRepr() const override;
 
  using PropertyType = GaudiHandleProperty;
 
private:
  //
  // Data member
  //
  std::string m_typeAndName; // the full type and name: "type/name"
};

template <class T>
class GAUDI_API GaudiHandle : public GaudiHandleBase {
  //
  // Constructors etc.
  //
protected:
  GaudiHandle( std::string myTypeAndName, std::string myComponentType, std::string myParentName )
      : GaudiHandleBase( std::move( myTypeAndName ), std::move( myComponentType ), std::move( myParentName ) ) {}
 
public:
  template <typename CT = T, typename NCT = std::remove_const_t<T>>
  GaudiHandle( const GaudiHandle<NCT>& other )
    requires( std::is_const_v<CT> && !std::is_same_v<CT, NCT> )
      : GaudiHandleBase( other ), m_pObject( other.get() ) {
    if ( m_pObject ) ::details::nonConst( m_pObject.load() )->addRef();
  }

  GaudiHandle( const GaudiHandle& other ) : GaudiHandleBase( other ), m_pObject( other.m_pObject.load() ) {
    if ( m_pObject ) ::details::nonConst( m_pObject.load() )->addRef();
  }

  template <typename CT = T, typename NCT = std::remove_const_t<T>>
    requires( std::is_const_v<CT> && !std::is_same_v<CT, NCT> )
  GaudiHandle& operator=( const GaudiHandle<NCT>& other ) {
    GaudiHandleBase::operator=( other );
    // release any current tool
    release().ignore();
    m_pObject = other.get();
    // update ref-counting
    if ( m_pObject ) ::details::nonConst( m_pObject.load() )->addRef();
    return *this;
  }

  GaudiHandle& operator=( const GaudiHandle& other ) {
    GaudiHandleBase::operator=( other );
    // release any current tool
    release().ignore();
    m_pObject = other.m_pObject.load();
    // update ref-counting
    if ( m_pObject ) ::details::nonConst( m_pObject.load() )->addRef();
    return *this;
  }

  StatusCode retrieve() const {
    // not really const, because it updates m_pObject
    // Do the lookup into a temporary pointer.
    T* p = nullptr;
    if ( retrieve( p ).isFailure() ) { return StatusCode::FAILURE; }
 
    // If m_pObject is null, then copy p to m_pObject.
    // Otherwise, release p.
    T* old = nullptr;
    if ( m_pObject.compare_exchange_strong( old, p ) ) { return StatusCode::SUCCESS; }
    return release( p );
  }

  StatusCode release() const {
    // not really const, because it updates m_pObject
    StatusCode sc = StatusCode::SUCCESS;
    if ( m_pObject ) {
      sc        = release( m_pObject );
      m_pObject = nullptr;
    }
    return sc;
  }

  bool isValid() const {
    // not really const, because it may update m_pObject
    return m_pObject || retrieve().isSuccess();
  }

  operator bool() const {
    // not really const, because it may update m_pObject
    return isValid();
  }

  T* get() { return m_pObject; }

  std::add_const_t<T>* get() const { return m_pObject; }

  bool isSet() const { return get(); }
 
  T& operator*() {
    assertObject();
    return *m_pObject;
  }
 
  T* operator->() {
    assertObject();
    return m_pObject;
  }
 
  std::add_const_t<T>& operator*() const {
    // not really const, because it may update m_pObject
    assertObject();
    return *m_pObject;
  }
 
  std::add_const_t<T>* operator->() const {
    // not really const, because it may update m_pObject
    assertObject();
    return m_pObject;
  }

  std::string getDefaultType() { return System::typeinfoName( typeid( T ) ); }
 
  std::string getDefaultName() {
    const auto defName = GaudiHandleBase::type();
    return ( defName.empty() ? getDefaultType() : defName );
  }
 
protected:
  virtual StatusCode retrieve( T*& ) const = 0; // not really const, because it updates m_pObject

  virtual StatusCode release( T* comp ) const { // not really const, because it updates m_pObject
    // const cast to support T being a const type
    ::details::nonConst( comp )->release();
    return StatusCode::SUCCESS;
  }
 
private:
  void assertObject() const { // not really const, because it may update m_pObject
    if ( !isValid() ) {
      throw GaudiException( "Failed to retrieve " + componentType() + ": " + typeAndName(),
                            componentType() + " retrieve", StatusCode::FAILURE );
    }
  }
 
private:
  //
  // Data members
  //
  mutable std::atomic<T*> m_pObject = nullptr;
};

 
class GAUDI_API GaudiHandleArrayBase : public GaudiHandleInfo {
protected:
  GaudiHandleArrayBase( std::string myComponentType, std::string myParentName )
      : GaudiHandleInfo( std::move( myComponentType ), std::move( myParentName ) ) {}
 
public:
  using PropertyType = GaudiHandleArrayProperty;
  typedef std::vector<GaudiHandleBase*>       BaseHandleArray;
  typedef std::vector<const GaudiHandleBase*> ConstBaseHandleArray;

  bool setTypesAndNames( const std::vector<std::string>& myTypesAndNamesList );

  const std::vector<std::string> typesAndNames() const;

  const std::vector<std::string> types() const;

  const std::vector<std::string> names() const;

  const std::vector<std::string> getBaseInfos( auto ( GaudiHandleBase::*pMemFunc )() const ) const;

  std::string pythonPropertyClassName() const override;

  std::string pythonRepr() const override;

  virtual bool push_back( const std::string& myHandleTypeAndName ) = 0;

  virtual void clear() = 0;

  virtual bool empty() const = 0;

  virtual ConstBaseHandleArray getBaseArray() const = 0;

  virtual BaseHandleArray getBaseArray() = 0;

  virtual StatusCode retrieve() = 0;

  virtual StatusCode release() = 0;

  virtual bool retrieved() const = 0;
};

template <class T>
class GAUDI_API GaudiHandleArray : public GaudiHandleArrayBase {
public:
  //
  // public nested types
  //
  typedef std::vector<T>                                HandleVector;
  typedef typename HandleVector::value_type             value_type;
  typedef typename HandleVector::size_type              size_type;
  typedef typename HandleVector::reference              reference;
  typedef typename HandleVector::const_reference        const_reference;
  typedef typename HandleVector::iterator               iterator;
  typedef typename HandleVector::const_iterator         const_iterator;
  typedef typename HandleVector::reverse_iterator       reverse_iterator;
  typedef typename HandleVector::const_reverse_iterator const_reverse_iterator;
 
protected:
  //
  // Constructors
  //
  GaudiHandleArray( const std::vector<std::string>& myTypesAndNamesList, std::string myComponentType,
                    std::string myParentName )
      : GaudiHandleArrayBase( std::move( myComponentType ), std::move( myParentName ) ) {
    setTypesAndNames( myTypesAndNamesList );
  }

  GaudiHandleArray( const std::string& myComponentType, const std::string& myParentName )
      : GaudiHandleArrayBase( myComponentType, myParentName ) {}
 
public:
  GaudiHandleArray& operator=( const std::vector<std::string>& myTypesAndNamesList ) {
    setTypesAndNames( myTypesAndNamesList );
    return *this;
  }
 
  GaudiHandleArrayBase::BaseHandleArray getBaseArray() override {
    GaudiHandleArrayBase::BaseHandleArray baseArray;
    for ( auto& h : m_handleArray ) baseArray.push_back( &h );
    return baseArray;
  }
 
  GaudiHandleArrayBase::ConstBaseHandleArray getBaseArray() const override {
    GaudiHandleArrayBase::ConstBaseHandleArray baseArray;
    for ( auto& h : m_handleArray ) baseArray.push_back( &h );
    return baseArray;
  }
 
  //
  // Simulate (part of) an std::vector
  //
  iterator begin() { return m_handleArray.begin(); }
 
  iterator end() { return m_handleArray.end(); }
 
  const_iterator begin() const { return m_handleArray.begin(); }
 
  const_iterator end() const { return m_handleArray.end(); }
 
  const_iterator rbegin() const { return m_handleArray.rbegin(); }
 
  const_iterator rend() const { return m_handleArray.rend(); }
 
  size_type size() const { return m_handleArray.size(); }
 
  void clear() override { m_handleArray.clear(); }
 
  bool empty() const override { return m_handleArray.empty(); }
 
  T& operator[]( int index ) { return m_handleArray[index]; }
 
  const T& operator[]( int index ) const { return m_handleArray[index]; }

  T* operator[]( std::string_view name ) {
    auto it = std::find_if( begin(), end(), [&]( const_reference r ) { return r.name() == name; } );
    return it != end() ? &*it : nullptr;
  }

  const T* operator[]( std::string_view name ) const {
    auto it = std::find_if( begin(), end(), [&]( const_reference r ) { return r.name() == name; } );
    return it != end() ? &*it : nullptr;
  }

  using GaudiHandleArrayBase::push_back; // avoid compiler warning
  virtual bool push_back( const T& myHandle ) {
    m_handleArray.push_back( myHandle );
    return true;
  }

  StatusCode retrieve() override {
    StatusCode sc = StatusCode::SUCCESS;
    for ( auto& i : *this ) {
      // stop at first failure
      if ( i.retrieve().isFailure() ) {
        sc = StatusCode::FAILURE;
        break;
      }
    }
    if ( sc ) { m_retrieved = true; }
    return sc;
  }

  StatusCode release() override {
    StatusCode sc = StatusCode::SUCCESS;
    for ( auto& i : *this ) {
      // continue trying to release other tools even if we fail...
      if ( i.release().isFailure() ) sc = StatusCode::FAILURE;
    }
    return sc;
  }

  virtual bool retrieved() const override { return m_retrieved; }
 
private:
  //
  // Private data members
  //
  HandleVector m_handleArray;
  bool         m_retrieved{ false };
};