ProviderList.h

Go to the documentation of this file.

/**
 * @file   ProviderList.h
 * @brief  Container for service providers used in a test
 * @date   April 22nd, 2016
 * @author Gianluca Petrillo (petrillo@fnal.gov)
 * @see    ProviderTesterHelpers.h
 * 
 * This is a header-only library.
 * It depends only on standard C++ and on GArSoft pure headers with that same
 * feature, and therefore does not require additional linkage.
 * 
 * This library provides:
 * 
 * - ProviderList, an object managing service providers
 * 
 */

#ifndef TESTUTILS_PROVIDERLIST_H
#define TESTUTILS_PROVIDERLIST_H 1

// GArSoft libraries
#include "TestUtils/ProviderTestHelpers.h"

// C/C++ standard libraries
#include <unordered_map>
#include <memory> // std::unique_ptr()
#include <utility> // std::forward()
#include <typeinfo>



namespace testing {
   
   namespace details {
      
      /// A base class with a virtual table
      struct MovableClassWrapperBase {
         virtual ~MovableClassWrapperBase() = default;
         
      }; // struct MovableClassWrapperBase
      
      /**
       * @brief A class containing an owned object
       * @tparam T type of the contained object
       * 
       * Differently from boost::any, `T` does not have to be copiable nor
       * movable. The price is that the object is dynamically allocated.
       * 
       * Given that we don't require T to be movable and we don't require it to
       * be polymorphic, we need some way to move T and have T recognized as
       * such when put in a mixed container. Hence this wrapper.
       * The price is quite high: two chained dynamic allocations per object
       * (one in the wrapper to provide mobility, the other in the container
       * not to lose polymorphism).
       * 
       */
      template <typename T>
      class MovableClassWrapper: public details::MovableClassWrapperBase {
         using datum_t = T; ///< contained type
         using this_t = MovableClassWrapper<T>; ///< this type
         using pointer_t = std::shared_ptr<datum_t>; ///< pointer storing datum
         

         template<typename U>
         friend class MovableClassWrapper;
            
            public: 
         struct share_t {}; /// type to specify a share constructor
         
         static constexpr share_t share = {};
         
         /// Default constructor: no datum present (move one in later on)
         MovableClassWrapper(): ptr(std::make_unique<datum_t>()) {}
         
         template <typename U>
         MovableClassWrapper(std::unique_ptr<U>&& from): ptr(std::move(from)) {}
         
         //@{
         /// Constructor and assignment from a unique pointer: steal the content
         MovableClassWrapper(pointer_t&& from): ptr(std::move(from)) {}
         MovableClassWrapper& operator= (pointer_t&& from)
            { ptr = std::move(from); return *this; }
         //@}
         
         /// Share constructor (kind of copy)
         template<typename U>
         MovableClassWrapper(MovableClassWrapper<U> const& from, share_t):
            ptr(from.ptr) {}
         
         
         /// Returns a reference to the datum with the correct type
         datum_t& ref() { return *ptr; }
         
         /// Returns a constant reference to the datum with the correct type
         datum_t const& ref() const { return *ptr; }
         
         /// Returns a pointer to the datum with the correct type
         datum_t* get() { return ptr.get(); }
         
         /// Returns a constant pointer to the datum with the correct type
         datum_t const* get() const { return ptr.get(); }
         
         //@{
         /// Returns whether there is a valid pointer
         bool valid() const { return bool(ptr); }
         
         operator bool() const { return valid(); }
         //@}
         
            private:
         pointer_t ptr;
         
      }; // namespace testing
      
   } // namespace details
   
   
   
   /** *************************************************************************
    * @brief Container of service providers accessed by type and optional label
    * 
    * This container is expected to contain elements that are service providers
    * of different types. Each provider is accessed by its class type and
    * an optional instance label to discriminate between providers of the same
    * type.
    * 
    * The list owns the providers. A provider is created with `setup()`
    * (or `setup_instance()` if a instance label is needed). This method
    * relies on a class `testing::ProvideSetupClass` to create and
    * correctly set up the provider. For example, to set up the provider
    * `LArPropertiesStandard`:
    *     
    *     provList.setup<LArPropertiesStandard>(pset);
    *     
    * assuming that `LArPropertiesStandard` provider has a constructor with
    * as only argument `pset` (supposedly, a `fhicl::ParameterSet`).
    * If a custom setup is needed, the methods `custom_setup_instance()` and
    * `custom_setup()`  take as argument a setup function, which can do
    * whatever it takes to perform the set up.
    * 
    * After a provider is set up, a reference to it can be obtained by `get()`:
    *     
    *     auto& larp = provList.get<LArPropertiesStandard>();
    *     
    * If no such class is available, an exception will be thrown.
    * The presence of a provider can be checked beforehand with `has()`.
    * 
    * @note The presence of multiple providers of the same type, supported via
    * instance names, is not useful in the current art/GArSoft.
    * 
    * 
    * How can a provider support the `setup()` construction method?
    * --------------------------------------------------------------
    * 
    * A provider can specify its own setup by specialising the class
    * `testing::ProvideSetupClass`. A default implementation is provided,
    * that constructs the provider with a parameter set.
    * 
    */
   class ProviderList {
      // Sparse implementation notes:
      // - we use MovableClassWrapperBase in place of boost::any because our
      //   providers are recommended to be not copiable
      
      /// type of smart pointer we use to store elements
      template <typename T>
      using smart_pointer_t = std::unique_ptr<T>;
      
      /// Type of objects contained in the list
      using pointer_t = smart_pointer_t<details::MovableClassWrapperBase>;
      
      /// Type of list element with explicit element type memory
      template <typename T>
      using concrete_type_t = details::MovableClassWrapper<std::decay_t<T>>;
      /// Type of smart pointer to typed list element
      template <typename T>
      using concrete_pointer_t = smart_pointer_t<concrete_type_t<T>>;
         
         public:
      /// base exception class for ProviderList
      struct exception: public std::runtime_error
        { using std::runtime_error::runtime_error; };
      /// Exception thrown on a request about an unregistered type
      struct provider_not_available: public exception
        { using exception::exception; };
      /// Exception thrown on when object is not available any more
      struct provider_deleted: public exception
        { using exception::exception; };
      /// Exception thrown on a invalid type request
      struct provider_wrong: public exception
        { using exception::exception; };
      
      
      /**
       * @brief Construct and register an object of type T
       * @tparam T type of the object to be constructed (caller specifies it)
       * @tparam SetupProc type of functor performing the actual setup
       * @tparam Args type of constructor arguments (compiler fills them in)
       * @param label name of this instance of object type T (can be empty)
       * @param provSetup functor performing the setup
       * @param args arguments to provSetup for the construction of T
       * 
       * An object is instantiated and associates it with the specified instance
       * label. It can then be accessed with a `get<T>(label)` call.
       * 
       * The functor `provSetup` is expected to return a unique pointer to the
       * newly created provider, `std::unique_ptr<T>`.
       */
      template <typename T, typename SetupProc, typename... Args>
      bool custom_setup_instance
         (std::string label, SetupProc&& provSetup, Args&&... args)
         { 
            auto k = key<T>(label); // key
            auto it = data.find(k);
            if (it != data.end()) return false;
            
            pointer_t ptr = std::make_unique<concrete_type_t<T>>
              (provSetup(std::forward<Args>(args)...));
            data.emplace_hint(it, std::move(k), std::move(ptr));
            return true;
         } // custom_setup_instance()
      
      /// Construct and register an object of type T with specified arguments
      template <typename T, typename SetupProc, typename... Args>
      bool custom_setup(SetupProc&& provSetup, Args&&... args)
         {
            return custom_setup_instance<T, SetupProc, Args...>(
               "",
               std::forward<SetupProc>(provSetup),
               std::forward<Args>(args)...
               );
         } // custom_setup()
      
      template <typename T, typename... Args>
      bool setup_instance
         (std::string label, Args&&... args)
         {
            auto k = key<T>(label); // key
            auto it = data.find(k);
            if (it != data.end()) return false;
            
            pointer_t ptr = std::make_unique<concrete_type_t<T>>
              (setupProvider<T>(std::forward<Args>(args)...));
            data.emplace_hint(it, std::move(k), std::move(ptr));
            return true;
         //   return custom_setup_instance<T>
         //     (label, setupProvider<T, Args...>, std::forward<Args>(args)...);
         } // setup_instance()
      
      /// Construct and register an object of type T with specified arguments
      template <typename T, typename... Args>
      bool setup(Args&&... args)
         { return setup_instance<T>("", std::forward<Args>(args)...); }
      
      
      /**
       * @brief Registers and gets ownership of the specified object
       * @tparam T type of object being acquired
       * @param obj_ptr pointer to the object to be acquired
       * @param label name of the object instance
       * @return whether the object was acquired or not
       * 
       * The ProviderList takes ownership of the specified provider.
       * If an object of type T is already registered, the pointer is left
       * untouched and `false` is returned.
       */
      template <typename T>
      bool acquire(std::unique_ptr<T>&& obj_ptr, std::string label = "")
         {
            auto k = key<T>(label); // key
            auto it = data.find(k);
            if (it != data.end()) return false;
            
            pointer_t ptr
              = std::make_unique<concrete_type_t<T>>(std::move(obj_ptr));
            data.emplace_hint(it, std::move(k), std::move(ptr));
            return true;
         } // acquire()
      
      
      /**
       * @brief Drops the object with the specified type and label
       * @tparam T type of object being acquired
       * @param label name of the object instance
       * @return whether the object was present or not
       * 
       * If present, the object is destroyed
       */
      template <typename T>
      bool erase(std::string label = "")
         {
            auto k = key<T>(label); // key
            auto target_it = data.find(k);
            if (target_it == data.end()) return false;
            
            // erase this and all the aliases pointing to it
            auto const* target_ptr = target_it->second.get();
            for (auto it = data.begin(); it != data.end(); ++it) 
               if (it->second.get() == target_ptr) data.erase(it);
            return true;
         } // erase()
      
      
      /// Sets the Alias type as an alias of the Prov provider (with labels)
      template <typename Prov, typename Alias>
      bool set_alias(std::string alias_label = "", std::string prov_label = "")
         {
            // find the alias location
            auto alias_k = key<Alias>(alias_label); // key
            auto alias_it = data.find(alias_k);
            if (alias_it != data.end()) return false;
            
            // find the original provider location
            auto prov_elem = get_elem<Prov>(prov_label);
            
            // register the shared object to the alias
            data.emplace_hint(alias_it, std::move(alias_k),
              std::make_unique<concrete_type_t<Alias>>
                (prov_elem, typename concrete_type_t<Alias>::share_t())
              );
            return true;
         } // set_alias()
      
      
      /// @{
      /**
       * @brief Retrieve the object of type T stored with the specified label
       * @tparam T type of the object to be retrieved
       * @param label optional label used when the object was inserted
       * @return the specified object as a reference to type T
       * @throw provider_not_available no type T class was stored with label
       * @throw provider_deleted the object that was stored is not present
       * @throw provider_wrong the object is not compatible with the type T
       */
      template <typename T>
      T const& get(std::string label = "") const
         { return get_elem<T>(label).ref(); }
      
      template <typename T>
      T& get(std::string label = "")
         { return get_elem<T>(label).ref(); }
      /// @}
      
      /// @{
      /**
       * @brief Retrieve the object of type T stored with the specified label
       * @tparam T type of the object to be retrieved
       * @param label optional label used when the object was inserted
       * @return the specified object as a pointer to type T
       * @throw provider_not_available no type T class was stored with label
       * @throw provider_deleted the object that was stored is not present
       * @throw provider_wrong the object is not compatible with the type T
       */
      template <typename T>
      T const* getPointer(std::string label = "") const
         { return get_elem<T>(label).get(); }
      
      template <typename T>
      T* getPointer(std::string label = "")
         { return get_elem<T>(label).get(); }
      /// @}
      
      /// Returns whether we have a slot for this object
      template <typename T>
      bool known(std::string label = "") const
         { return find<T>(label) != data.end(); }
      
      /// Returns whether the specified object is available
      template <typename T>
      bool valid(std::string label = "") const
         {
            auto it = find<T>(label);
            return (it != data.end()) && bool(it->second);
         }
      
         private:
      using key_type = size_t; ///< type used for key in the internal registry
      
      std::unordered_map<key_type, pointer_t> data; ///< all our singletons
      
      /// Convert a type into a (ugly) type name
      template <typename T>
      static std::string type_name() { return typeid(T).name(); }
      
      /// Convert a pointer to object into a (ugly) type name
      template <typename T>
      static std::string type_name(T const* ptr) { return typeid(*ptr).name(); }
      
      /// @{
      /// Returns an iterator pointing to the requested key, or data.end()
      template <typename T>
      auto find(std::string label = "") const
        { return data.find(key<T>(label)); }

      template <typename T>
      auto find(std::string label = "") { return data.find(key<T>(label)); }
      /// @}

      template <typename T>
      concrete_type_t<T> const& get_elem(std::string label = "") const
         {
            auto it = find<T>(label);
            if (it == data.end())
               throw provider_not_available("Not available: " + type_name<T>());
            if (!(it->second))
               throw provider_deleted("Deleted: " + type_name<T>());
            auto* ptr = dynamic_cast<details::MovableClassWrapper<T>*>
              (it->second.get());
            if (!ptr) {
               throw provider_wrong("Wrong: " + type_name(it->second.get())
                 + " [requested: " + type_name<T>() + "]");
            }
            return *ptr;
         } // get_elem()
      
      template <typename T>
      concrete_type_t<T>& get_elem(std::string label = "")
         {
            auto it = find<T>(label);
            if (it == data.end())
               throw provider_not_available("Not available: " + type_name<T>());
            if (!(it->second))
               throw provider_deleted("Deleted: " + type_name<T>());
            auto* ptr = dynamic_cast<details::MovableClassWrapper<T>*>
              (it->second.get());
            if (!ptr) {
               throw provider_wrong("Wrong: " + type_name(it->second.get())
                 + " [requested: " + type_name<T>() + "]");
            }
            return *ptr;
         } // get_elem()
      
      /// Extracts and returns the key out of a type and label
      template <typename T>
      static key_type key(std::string label = "")
         {
            return typeid(std::decay_t<T>).hash_code()
               ^ std::hash<std::string>()(label);
         }
      
   }; // class ProviderList
   
   
} // namespace testing



#endif // TESTUTILS_PROVIDERLIST_H