AnaToolHandle.icc

#include <AsgTools/MessageCheck.h>
#include <assert.h>
#include <cstdlib>

#ifndef ROOTCORE
#include "GaudiKernel/IJobOptionsSvc.h"
#endif


namespace asg
{
  namespace detail
  {
#ifdef ROOTCORE
    StatusCode makeToolRootCore (const std::string& type,
				 const std::string& name,
				 AsgTool*& tool);
#else
    StatusCode copyPropertiesInCatalogue( const std::string& fromTool, const std::string& toTool );
    StatusCode hasPropertiesInCatalogue( const std::string& toolName );
    StatusCode addPropertyToCatalogue( const std::string& toolName, const std::string& property, const std::string& val);
    StatusCode removePropertyFromCatalogue( const std::string& toolName, const std::string& property);
    StatusCode toolExists( const std::string& fullName, interfaceType_t*& tool );
    // StatusCode factoryExists( const std::string& type );
#endif



    /// \brief do a checked cast from one ToolHandle interface to
    /// another
    /// \par Guarantee
    ///   basic
    /// \par Failures
    ///   interface not supported for tool
    template<typename T1,typename T2> StatusCode
    toolHandleCast (ToolHandle<T1>& to, ToolHandle<T2>& from)
    {
      using namespace msgUserCode;

#ifdef ROOTCORE
      to = ToolHandle<T1> (dynamic_cast<T1*>(&*from));
      if (!from.empty() && &*to == nullptr)
      {
	ANA_MSG_ERROR ("failed to cast from type " << typeid(T2).name() << " to  " << typeid(T1).name());
	return StatusCode::FAILURE;
      }
#else
      to = ToolHandle<T1> (from.typeAndName(), from.parent());
      if (!from.empty())
        ANA_CHECK (to.retrieve());
#endif
      return StatusCode::SUCCESS;
    }





    /// \brief the information needed to share a tool

    class AnaToolShare
    {
      //
      // public interface
      //

      /// \brief standard constructor
      /// \par Guarantee
      ///   strong
      /// \par Failures
      ///   out of memory II
    public:
      AnaToolShare (const ToolHandle<interfaceType_t>& val_th,
		    AnaToolCleanup val_cleanup);


      /// \brief the tool we contain
      /// \par Guarantee
      ///   no-fail
      /// \post result != nullptr
    public:
      ToolHandle<interfaceType_t>& th ();



      //
      // private interface
      //

      /// \brief the value of \ref tool
    private:
      ToolHandle<interfaceType_t> m_th;

      /// \brief resources to release shen we are releasing the tool
    private:
      AnaToolCleanup m_cleanup;
    };





    /// \brief a service for sharing tools of a given type

    class AnaToolShareList
    {
      //
      // public interface
      //

      /// \brief the singleton we are using
      /// \par Guarantee
      ///   no-fail
    public:
      static AnaToolShareList& singleton () noexcept;


      /// \brief get the share for the given name, or nullptr if no
      /// share has been defined
      /// \par Guarantee
      ///   strong
      /// \par Failures
      ///   out of memory I
    public:
      std::shared_ptr<AnaToolShare>
      getShare (const std::string& name) const;


      /// \brief set the share for the given name
      /// \return the share to use, this is either the share passed in
      /// or the already set share
      /// \par Guarantee
      ///   strong
      /// \par Failures
      ///   out of memory II
    private:
      std::shared_ptr<AnaToolShare>
      setShare (const std::string& name,
		std::unique_ptr<AnaToolShare> val_share);


      /// \brief make or get a share for the given name
      /// \return the share to use, either freshly created or
      /// retrieved from the store
      /// \par Guarantee
      ///   strong
      /// \par Failures
      ///   tool creation failures\n
      ///   out of memory II
    public:
      StatusCode
      makeShare (const std::string& name,
		 const AnaToolConfig& config,
		 std::shared_ptr<AnaToolShare>& result);



      //
      // private interface
      //

      /// \brief the shares we manage
    private:
      std::map<std::string,std::weak_ptr<AnaToolShare> > m_shared;
    };



#ifndef ROOTCORE
    /// \brief manage a single property in the job options service

    struct PropertyValueManager
    {
      PropertyValueManager (const std::string& val_toolName,
			    const std::string& val_name)
	: m_toolName (val_toolName), m_name (val_name)
      {
      }

      ~PropertyValueManager ()
      {
	if (m_cleanup)
	  detail::removePropertyFromCatalogue (m_toolName, m_name).ignore();
      }

      std::string m_toolName;
      std::string m_name;
      bool m_cleanup = false;
    };



    /// \brief a \ref AnaToolProperty containing a regular value for
    /// Athena

    class AnaToolPropertyValueAthena : public AnaToolProperty
    {
    public:
      template<typename Type>
      AnaToolPropertyValueAthena (const Type& val_value)
	: m_value (Gaudi::Utils::toString (val_value))
      {
      }

    public:
      virtual StatusCode
      applyPropertyAthena (const std::string& toolName,
			   const std::string& name,
			   AnaToolCleanup& cleanup)
	const override;

    private:
      std::string m_value;
    };
#endif





#ifdef ROOTCORE
    /// \brief a \ref AnaToolProperty containing a regular value in
    /// RootCore

    template<typename Type>
    class AnaToolPropertyValueRootCore : public AnaToolProperty
    {
    public:
      AnaToolPropertyValueRootCore (const Type& val_value)
	: m_value (val_value)
      {}

    public:
      virtual StatusCode
      applyPropertyRootCore (AsgTool& tool, const std::string& name,
			     AnaToolCleanup& /*cleanup*/)
	const override
      {
	using namespace msgToolHandle;
	ANA_CHECK (tool.setProperty (name, m_value));
	return StatusCode::SUCCESS;
      }

    private:
      Type m_value;
    };
#endif





    /// \brief a \ref AnaToolProperty containing an \ref AnaToolConfig
    /// for configuring a private sub-tool

    template<typename Type>
    class AnaToolPropertyPrivateTool : public AnaToolProperty
    {
    public:
      AnaToolPropertyPrivateTool (const AnaToolConfig& val_config)
	: m_config (val_config)
      {}

#ifdef ROOTCORE
    public:
      virtual StatusCode
      applyPropertyRootCore (AsgTool& tool, const std::string& name,
			     AnaToolCleanup& cleanup)
	const override
      {
	using namespace msgToolHandle;
	ToolHandle<Type> th;
	AnaToolCleanup mycleanup;
	ANA_CHECK (m_config.makeTool (name, &tool, th, mycleanup));
	cleanup.addCleanup (std::move (mycleanup));
	ANA_CHECK (tool.setProperty (name, th));
	return StatusCode::SUCCESS;
      }
#endif

#ifndef ROOTCORE
    private:
      virtual StatusCode
      applyPropertyAthena (const std::string& toolName,
			   const std::string& name,
			   AnaToolCleanup& cleanup)
	const override
      {
	using namespace msgToolHandle;
	ANA_CHECK (m_config.applyPropertiesAthena (toolName + "." + name, cleanup));

	// this is so we clear out properties from catalogue when tool
	// is destroyed.  DISABLED: as we no longer release tools in Athena
	// std::shared_ptr<PropertyValueManager> manager
	//   (new PropertyValueManager (th.name(), name));
	// cleanup.addCleanup (manager);

	// for athena we hand our property to the joboptions svc
        ANA_CHECK (detail::addPropertyToCatalogue (toolName, name, m_config.type() + "/" + name));
	// manager->m_cleanup = true;
	return StatusCode::SUCCESS;
      }
#endif

    private:
      AnaToolConfig m_config;
    };





#ifndef ROOTCORE
    /// \brief a \ref AnaToolProperty copying a tool configuration
    /// from the job options service to a new place

    class AnaToolPropertyCopyTool : public AnaToolProperty
    {
    public:
      AnaToolPropertyCopyTool (const std::string& val_type,
                               const std::string& val_name);

    private:
      virtual StatusCode
      applyPropertyAthena (const std::string& toolName,
			   const std::string& name,
			   AnaToolCleanup& cleanup)
	const override;

      /// \brief the type of the tool to create
    private:
      std::string m_type;

      /// \brief the name of the source tool
    private:
      std::string m_name;
    };
#endif





    /// \brief a \ref AnaToolProperty containing an \ref AnaToolConfig
    /// for configuring a public sub-tool

    template<typename Type>
    class AnaToolPropertyPublicTool : public AnaToolProperty
    {
    public:
      AnaToolPropertyPublicTool (const std::string& val_name,
				 const AnaToolConfig& val_config)
	: m_name (val_name), m_config (val_config)
      {}

#ifdef ROOTCORE
    public:
      virtual StatusCode
      applyPropertyRootCore (AsgTool& tool, const std::string& name,
			     AnaToolCleanup& cleanup)
	const override
      {
	using namespace msgToolHandle;
	std::shared_ptr<AnaToolShare> share;
	ANA_CHECK (AnaToolShareList::singleton().makeShare
		     (m_name, m_config, share));
	cleanup.addCleanup (share);
	ToolHandle<Type> myth;
	ANA_CHECK (toolHandleCast (myth, share->th()));
	ANA_CHECK (tool.setProperty (name, myth));
	return StatusCode::SUCCESS;
      }
#endif

#ifndef ROOTCORE
    private:
      virtual StatusCode
      applyPropertyAthena (const std::string& toolName,
			   const std::string& name,
			   AnaToolCleanup& cleanup)
	const override
      {
	using namespace msgToolHandle;
	std::shared_ptr<AnaToolShare> share;
	ANA_CHECK (AnaToolShareList::singleton().makeShare
		     (m_name, m_config, share));
	cleanup.addCleanup (share);

	ToolHandle<Type> th;
	ANA_CHECK (toolHandleCast (th, share->th()));

	// this is so we clear out properties from catalogue when tool
	// is destroyed.  DISABLED: we no longer clear out tools after
	// we are done with them
	// std::shared_ptr<PropertyValueManager> manager
	//   (new PropertyValueManager (th.name(), name));
	// cleanup.addCleanup (manager);

	// for athena we hand our property to the joboptions svc
	ANA_CHECK (detail::addPropertyToCatalogue (toolName, name, th.typeAndName()));
        // manager->m_cleanup = true;
	return StatusCode::SUCCESS;
      }
#endif

    private:
      std::string m_name;
      AnaToolConfig m_config;
    };





#ifdef ROOTCORE
    template<typename Type> void AnaToolConfig ::
    registerNew ()
    {
      m_factory = [] (AsgTool*& tool, const std::string& name) -> StatusCode {
	tool = new Type (name); return StatusCode::SUCCESS;};
    }
#endif



#ifdef ROOTCORE
    template<typename Type> StatusCode AnaToolConfig ::
    setProperty (const std::string& val_name, const Type& val_value)
    {
      std::shared_ptr<detail::AnaToolProperty> anaProperty
	(new detail::AnaToolPropertyValueRootCore<Type> (val_value));
      addProperty (val_name, anaProperty);
      return StatusCode::SUCCESS;
    }
#else
    template<typename Type> StatusCode AnaToolConfig ::
    setProperty (const std::string& val_name, const Type& val_value)
    {
      using namespace msgToolHandle;
      std::shared_ptr<detail::AnaToolProperty> anaProperty
	(new detail::AnaToolPropertyValueAthena (val_value));
      addProperty (val_name, anaProperty);
      return StatusCode::SUCCESS;
    }
#endif



    template<typename Type> StatusCode AnaToolConfig ::
    setProperty (const std::string& val_name,
		 const AnaToolHandle<Type>& val_value)
    {
      using namespace msgToolHandle;

      // once initialized the AnaToolHandle is not that different from
      // a regular ToolHandle and we just use it as such
      if (val_value.isInitialized())
	return setProperty (val_name, val_value.getHandle());

      switch (val_value.mode())
      {
      case AnaToolHandleMode::EMPTY:
	return setProperty (val_name, ToolHandle<Type> ());
      case AnaToolHandleMode::CREATE_PRIVATE:
	{
	  std::shared_ptr<AnaToolPropertyPrivateTool<Type> > anaProperty
	    (new AnaToolPropertyPrivateTool<Type> (val_value.config()));
	  addProperty (val_name, anaProperty);
	}
	return StatusCode::SUCCESS;
      case AnaToolHandleMode::CREATE_SHARED:
      case AnaToolHandleMode::RETRIEVE_SHARED:
	{
	  std::shared_ptr<AnaToolPropertyPublicTool<Type> > anaProperty
	    (new AnaToolPropertyPublicTool<Type> (val_value.name(), val_value.config()));
	  addProperty (val_name, anaProperty);
	}
	return StatusCode::SUCCESS;
      case AnaToolHandleMode::USER:
	return setProperty (val_name, val_value.getHandle());
      }
      return StatusCode::FAILURE; //compiler dummy
    }



#ifndef ROOTCORE
    template<typename Type> StatusCode AnaToolConfig ::
    setProperty (const std::string& val_name,
		 const ToolHandle<Type>& val_value)
    {
      using namespace msgToolHandle;

      //strip the parent name
      if (val_value.empty())
        return setProperty (val_name, std::string ());
      else if (val_value.isPublic())
      {
        return setProperty (val_name,
                            val_value.type() + "/" + val_value.name());
      } else
      {
        std::shared_ptr<AnaToolPropertyCopyTool> shared
          (new AnaToolPropertyCopyTool
           (val_value.type(), val_value.parentName() + "." + val_value.name()));
        addProperty (val_name, shared);
        return StatusCode::SUCCESS;
      }
    }



    template<typename Type> StatusCode AnaToolConfig ::
    setProperty (const std::string& val_name,
		 const ToolHandleArray<Type>& val_value)
    {
      using namespace msgToolHandle;

      std::vector<std::string> tools;
      // loop over toolhandles in array, strip off any parent naming
      // and set property with the result
      for (auto& toolHandle : val_value)
      {
	if (toolHandle.empty())
	{
	  ANA_MSG_ERROR ("trying to initialize ToolHandleArray property " << val_name << " with empty handle");
	  return StatusCode::FAILURE;
	}

	//strip the parent name
	std::string tool_name = toolHandle.name();
	tools.push_back (toolHandle.type() + "/" + tool_name);
      }

      return setProperty (val_name, tools);
    }
#endif




    template<typename ToolType> StatusCode AnaToolConfig ::
    makeTool (const std::string& name,
              parentType_t *parent,
	      ToolHandle<ToolType>& th,
	      AnaToolCleanup& cleanup) const
    {
      using namespace msgUserCode;
      ToolHandle<interfaceType_t> baseTH;
      AnaToolCleanup baseCleanup;
      ANA_CHECK (makeBaseTool (name, parent, baseTH, baseCleanup));
      ANA_CHECK (toolHandleCast (th, baseTH));
      cleanup.swap (baseCleanup);
#ifndef ROOTCORE
      baseTH->release ();
#endif
      return StatusCode::SUCCESS;
    }
  }



  template <typename T>
  std::ostream& operator << (std::ostream& str, const AnaToolHandle<T>& obj)
  {
    return str << obj.getHandle();
  }



  template<class T> void AnaToolHandle<T> ::
  testInvariant () const
  {
#define CHECK_INVARIANT(x)			\
    if (!(x)) { std::cerr << __FILE__ << ":" << __LINE__ << ": invariant violated: " << #x << std::endl; std::abort(); }

    // General requirements
    CHECK_INVARIANT (&*this != nullptr);
    CHECK_INVARIANT (m_handleUser != nullptr);
    // CHECK_INVARIANT (m_parentPtr == nullptr || m_parentPtr->name() == m_parentName);
    // #ifndef ROOTCORE
    // CHECK_INVARIANT (m_parentPtr == m_handleUser->parent());
    // #endif

#undef CHECK_INVARIANT
  }



  template<class T> AnaToolHandle<T> ::
  AnaToolHandle (const std::string& val_name, parentType_t *val_parent)
    : m_parentPtr (val_parent),
      m_handleUser (new ToolHandle<T> (val_name, val_parent)),
      m_allowEmpty (val_name.empty())
  {
    setTypeAndName (val_name);

#ifndef NDEBUG
    this->testInvariant ();
#endif
  }



  template<class T> AnaToolHandle<T> ::
  AnaToolHandle (AnaToolHandle<T>&& that)
    : AnaToolHandle ()
  {
    swap (that);
  }



  template<class T> AnaToolHandle<T> ::
  AnaToolHandle (const AnaToolHandle<T>& that)
    : m_config (that.m_config),
      m_name (that.m_name),
      m_parentPtr (that.m_parentPtr),
      m_handleUser (new ToolHandle<T> (*that.m_handleUser)),
      m_originalTypeAndName (that.m_originalTypeAndName),
      m_isInitialized (that.m_isInitialized.load()),
      m_allowEmpty (that.m_allowEmpty)
  {
    if (m_isInitialized.load())
    {
      m_toolPtr = that.m_toolPtr;
      m_mode = that.m_mode;
      m_cleanup = that.m_cleanup;
    }

#ifndef ROOTCORE
    if (!m_handleUser->empty())
      (*m_handleUser)->release();
#endif

#ifndef NDEBUG
    that.testInvariant ();
    testInvariant ();
#endif
  }



  template<class T> AnaToolHandle<T>& AnaToolHandle<T> ::
  operator = (const AnaToolHandle<T>& that)
  {
    // no invariant used
    AnaToolHandle<T> (that).swap (*this);
    return *this;
  }



  template<class T> void AnaToolHandle<T> ::
  swap (AnaToolHandle<T>& that) noexcept
  {
#ifndef NDEBUG
    testInvariant ();
    that.testInvariant ();
#endif

    m_cleanup.swap (that.m_cleanup);
    m_config.swap (that.m_config);
    m_name.swap (that.m_name);
    std::swap (m_parentPtr, that.m_parentPtr);
    {
      ToolHandle<T> tmp = *m_handleUser;
#ifndef ROOTCORE
      if (!tmp.empty())
        tmp->release();
#endif
      *m_handleUser = *that.m_handleUser;
      *that.m_handleUser = tmp;
    }
    m_originalTypeAndName.swap (that.m_originalTypeAndName);
    {
      const auto tmp = m_isInitialized.load();
      m_isInitialized = that.m_isInitialized.load();
      that.m_isInitialized = tmp;
    }
    std::swap (m_toolPtr, that.m_toolPtr);
    std::swap (m_mode, that.m_mode);
    std::swap (m_allowEmpty, that.m_allowEmpty);

#ifndef NDEBUG
    testInvariant ();
    that.testInvariant ();
#endif
  }



  template<class T> AnaToolHandle<T>& AnaToolHandle<T> ::
  operator = (AnaToolHandle<T>&& that)
  {
    // no invariant used
    swap (that);
    return *this;
  }



  template<class T> AnaToolHandle<T> ::
  ~AnaToolHandle () noexcept
  {
    using namespace msgToolHandle;
#ifndef NDEBUG
    this->testInvariant ();
#endif
  }


  template<class T> bool
  AnaToolHandle<T> ::
  empty () const
  {
#ifndef NDEBUG
     this->testInvariant ();
#endif
    switch (getMode())
    {
    case detail::AnaToolHandleMode::EMPTY:
      return true;
    case detail::AnaToolHandleMode::CREATE_PRIVATE:
    case detail::AnaToolHandleMode::CREATE_SHARED:
    case detail::AnaToolHandleMode::RETRIEVE_SHARED:
      return false;
    case detail::AnaToolHandleMode::USER:
      return m_handleUser->empty();
    }
    return false; //compiler dummy
  }



  template<class T> inline bool AnaToolHandle<T> ::
  isPublic () const noexcept
  {
#ifndef NDEBUG
     this->testInvariant ();
#endif
     return m_parentPtr == nullptr;
  }



   template<class T> inline const std::string& AnaToolHandle<T> ::
   type () const noexcept
   {
#ifndef NDEBUG
     this->testInvariant ();
#endif
     return m_config.type();
   }



   template<class T> inline const std::string&
   AnaToolHandle<T> ::
   name () const noexcept
   {
#ifndef NDEBUG
     this->testInvariant ();
#endif
     return m_name;
   }



  template <class T> template <class T2>
  StatusCode AnaToolHandle<T> ::
  setProperty (const std::string& property, const T2& value)
  {
    using namespace msgToolHandle;

#ifndef NDEBUG
    this->testInvariant ();
    if (isInitialized())
    {
      ANA_MSG_FATAL ("AnaToolHandle has already been initialized: " << *this);
      std::abort();
    }
#endif

    return m_config.setProperty (property, value);
  }



  template<class T> StatusCode
  AnaToolHandle<T> ::
  initialize ()
  {
    using namespace msgToolHandle;

    // ensure we don't initialize twice concurrently
    std::lock_guard<std::recursive_mutex> lock (m_initializeMutex);

#ifndef NDEBUG
    this->testInvariant ();
    if (isInitialized())
    {
      ANA_MSG_FATAL ("AnaToolHandle has already been initialized: " << *this);
      std::abort();
    }
#endif

    std::shared_ptr<detail::AnaToolShare> sharedTool;
    const detail::AnaToolHandleMode mode = getMode (sharedTool);

    ToolHandle<T> th;
    detail::AnaToolCleanup cleanup;

    switch (mode)
    {
    case detail::AnaToolHandleMode::EMPTY:
      break;
    case detail::AnaToolHandleMode::CREATE_PRIVATE:
      ANA_CHECK (m_config.makeTool (m_name, m_parentPtr, th, cleanup));
      break;
    case detail::AnaToolHandleMode::CREATE_SHARED:
      ANA_CHECK (detail::AnaToolShareList::singleton().makeShare (m_name, m_config, sharedTool));
      // no break
    case detail::AnaToolHandleMode::RETRIEVE_SHARED:
      assert (sharedTool != nullptr);
      ANA_CHECK (detail::toolHandleCast (th, sharedTool->th()));
#ifndef ROOTCORE
      if (!th.empty())
        th->release ();
#endif
      cleanup.addCleanup (sharedTool);
      break;
    case detail::AnaToolHandleMode::USER:
      th = *m_handleUser;
      if (th.empty() && !m_allowEmpty)
      {
	ANA_MSG_ERROR ("user configured an empty handle for a non-empty AnaToolHandle: " << *this);
	return StatusCode::FAILURE;
      }
      break;
    }

    T *toolPtr = nullptr;
    ANA_CHECK (makeToolRetrieve (toolPtr, th));

    *m_handleUser = th;
#ifndef ROOTCORE
    if (!th.empty())
      th->release ();
#endif
    m_mode = mode;
    m_cleanup.swap (cleanup);
    m_toolPtr = toolPtr;
    m_isInitialized = true;

#ifndef NDEBUG
    this->testInvariant ();
#endif
    return StatusCode::SUCCESS;
  }



  template<class T> StatusCode
  AnaToolHandle<T> ::
  retrieve ()
  {
    // no invariant used
    return initialize ();
  }


  template<class T> bool
  AnaToolHandle<T> ::
  isConfigurable () const
  {
    using namespace msgToolHandle;
#ifndef NDEBUG
    this->testInvariant ();
#endif
    switch (getMode())
    {
    case detail::AnaToolHandleMode::EMPTY:
    case detail::AnaToolHandleMode::CREATE_PRIVATE:
    case detail::AnaToolHandleMode::CREATE_SHARED:
      return true;
    case detail::AnaToolHandleMode::RETRIEVE_SHARED:
    case detail::AnaToolHandleMode::USER:
      return false;
    }
    return true; //compiler dummy
  }



  template<class T>
#ifndef NDEBUG
  inline
#endif
  bool AnaToolHandle<T> ::
  isInitialized () const noexcept
  {
#ifndef NDEBUG
    this->testInvariant ();
#endif
    return m_isInitialized;
  }



  template<class T> inline T *
  AnaToolHandle<T> ::
  operator -> ()
  {
    // no invariant used
    return get ();
  }



  template<class T> inline const T *
  AnaToolHandle<T> ::
  operator -> () const
  {
    // no invariant used
    return get ();
  }



  template<class T> inline T&
  AnaToolHandle<T> ::
  operator * ()
  {
    // no invariant used
    return *get ();
  }



  template<class T> inline const T&
  AnaToolHandle<T> ::
  operator * () const
  {
    // no invariant used
    return *get ();
  }



  template<class T> inline T*
  AnaToolHandle<T> ::
  get ()
  {
    using namespace msgToolHandle;

#ifndef NDEBUG
    this->testInvariant ();
#endif

    if (m_isInitialized.load())
      return m_toolPtr;

    std::lock_guard<std::recursive_mutex> lock (m_initializeMutex);
    if (!m_isInitialized)
      ANA_CHECK_THROW (initialize());
    assert (m_isInitialized);
    return m_toolPtr;
  }



  template<class T> inline const T*
  AnaToolHandle<T> ::
  get () const
  {
    return const_cast<AnaToolHandle<T>*>(this)->get();
  }



  template <class T> template<typename T2> void
  AnaToolHandle<T> ::
  declarePropertyFor (T2 *tool, const std::string& name,
		      const std::string& description)
  {
    using namespace msgToolHandle;
#ifndef NDEBUG
    this->testInvariant ();
    if (isInitialized())
    {
      ANA_MSG_FATAL ("can't declare tool handle " << *this << " as property " << name << " after tool has been instantiated");
      std::abort ();
    }
#endif

    if (m_parentPtr != nullptr && m_parentPtr != tool)
    {
      ANA_MSG_FATAL ("can't declare tool handle " << *this << " as property for tool " << tool->name() << " as it has a different parent tool " << m_parentPtr->name());
      std::abort ();