ServiceProviderWrappers.h

Go to the documentation of this file.

/**
 * @file    ServiceProviderWrappers.h
 * @brief   Skeleton for a art service interface to service providers
 * @author  Gianluca Petrillo (petrillo@fnal.gov)
 * @date    April 19, 2016
 * 
 * This is a pure template library.
 * The callers will need to link to:
 * 
 * * `${ART_FRAMEWORK_SERVICES_REGISTRY}`
 * 
 * It provides:
 * 
 * * SimpleServiceProviderWrapper: wrap a service with a single implementation
 * * ServiceProviderImplementationWrapper: wrap a concrete implementation of a
 *   service provider interface supporting multiple implementations
 * 
 */

#ifndef COREUTILS_SERVICEPROVIDERWRAPPERS_H
#define COREUTILS_SERVICEPROVIDERWRAPPERS_H 1


// GArSoft libraries
#include "CoreUtils/ServiceUtil.h" // gar::providerFrom() (for includers)

// framework and support libraries
#include "art/Framework/Services/Registry/ServiceTable.h"
#include "art/Framework/Services/Registry/ServiceDeclarationMacros.h"
#include "art/Framework/Services/Registry/ServiceDefinitionMacros.h"

// C/C++ standard libraries
#include <memory> // std::unique_ptr<>


// forward declarations
namespace art { class ActivityRegistry; }
namespace fhicl { class ParameterSet; }


namespace gar {
   
   /** **********************************************************************
    * @brief Service returning a provider
    * @tparam PROVIDER type of service provider to be returned
    * 
    * This class provides the simplest possible art service to wrap a GArSoft
    * service provider.
    * The service is not reacting to any framework events.
    * 
    * The configuration is passed directly to the provider.
    * 
    * The simplest way to create an art service with this template is:
    *     
    *     #include "CoreUtils/ServiceProviderWrappers.h"
    *     #include "path/to/MyProvider.h"
    *     
    *     #include "art/Framework/Services/Registry/ServiceDeclarationMacros.h"
    *     #include "art/Framework/Services/Registry/ServiceDefinitionMacros.h"
    *     
    *     namespace myprov {
    *       
    *       using MyService = gar::SimpleServiceProviderWrapper<MyProvider>;
    *           
    *     }
    *     
    *     DECLARE_ART_SERVICE(myprov::MyService, LEGACY)
    *     
    * An implementation file is necessary too, that will look like:
    *     
    *     #include "path/to/MyService.h"
    *     
    *     DEFINE_ART_SERVICE(myprov::MyService)
    *     
    * If callback registration is needed, a class can derive from this template
    * and still gain a bit of boilerplate facility. That is:
    * - a `provider_type` definition (required by `gar::providerFrom()`)
    * - a `provider()` method to access the provider (required by
    *   `gar::providerFrom()`)
    * - a `Parameters` definition (used by art to print accepted configuration)
    * - a constructor supporting FHiCL configuration validation
    * - transparent life management of the provider instance
    * 
    * Requirements on the service provider:
    * - a data type `Config` being the configuration object. This is the object
    *   wrapped by `fhicl::Table` when performing FHiCL validation.
    * - a constructor with as argument a constant reference to a Config object.
    *   The provider should be configured by that constructor.
    * 
    */
   template <class PROVIDER>
   class SimpleServiceProviderWrapper {
      
         public:
      using provider_type = PROVIDER; ///< type of the service provider
      
      /// Type of configuration parameter (for art description)
      using Parameters = ::art::ServiceTable<typename provider_type::Config>;
      
      
      /// Constructor (using a configuration table)
      SimpleServiceProviderWrapper
         (Parameters const& config, ::art::ActivityRegistry&)
         : prov(std::make_unique<provider_type>(config()))
         {}
         
      
      /// Returns a constant pointer to the service provider
      provider_type const* provider() const { return prov.get(); }
      
      
         private:
      
      std::unique_ptr<provider_type> prov; ///< service provider
      
   }; // SimpleServiceProviderWrapper<>
   
   
   
   /** **********************************************************************
    * @brief Service returning a provider interface
    * @tparam PROVIDER type of service provider interface to be returned
    * @see ServiceProviderImplementationWrapper
    * 
    * This class provides a art service to wrap a GArSoft service provider
    * interface.
    * 
    * The behaviour of the implementations is not constrained by this interface.
    * It only adds support for `gar::providerFrom()` function.
    * 
    * Implementations must override `do_provider()` to return a pointer which
    * `provider()` will forward to the caller.
    * 
    */
   template <class PROVIDER>
   class ServiceProviderInterfaceWrapper {
      
         public:
      using provider_type = PROVIDER; ///< type of the service provider
      
      /// Virtual destructor
      virtual ~ServiceProviderInterfaceWrapper() = default;
      
      
      /// Returns a constant pointer to the service provider interface
      provider_type const* provider() const { return do_provider(); }
      
      
         protected:
      
      /// Implementation of the provider() function, to be overridden
      virtual provider_type const* do_provider() const = 0;
      
   }; // ServiceProviderInterfaceWrapper<>
   
   

   /** *************************************************************************
    * @brief Service implementation returning a provider
    * @tparam INTERFACE type of art service being implemented
    * @tparam PROVIDER type of service provider to be returned
    * @see ServiceProviderInterfaceWrapper
    * 
    * This class is suitable for a simple art service implementing an interface.
    * This is the case of a service that can have multiple implementations,
    * for example an experiment-specific access to a database.
    * In this case, the art service is described by an interface, and many
    * services can inherit and implement it.
    * 
    * In the factorization model recommended in GArSoft, this hierarchy of art
    * service implementations derived by a common interface is mirrored in a
    * matching hierarchy of service provider implementation derived by a common
    * service provider interface.
    * In this model, services are basically trivial classes that return a
    * pointer to the provider through a prescribed interface. The only relevant
    * exception is that services may also register framework callbacks.
    * 
    * Given the nature of the service returning a provider, its structure is
    * repetitive. This class implements most of that repetitive frame.
    * The resulting service is not reacting to any framework events.
    * 
    * The configuration of the service is passed directly to the provider.
    * 
    * Given that we want to have a service that implements the service
    * `MyServiceInterface` and returns a provider implementation "A" called
    * `MyProviderA`, the simplest way to create it with this template is:
    *     
    *     #include "CoreUtils/ServiceProviderWrappers.h"
    *     #include "path/to/MyProviderA.h"
    *     #include "path/to/MyServiceInterface.h"
    *     
    *     #include "art/Framework/Services/Registry/ServiceDeclarationMacros.h"
    *     #include "art/Framework/Services/Registry/ServiceDefinitionMacros.h"
    *     
    *     namespace myprov {
    *       
    *       using MyServiceA = gar::ServiceProviderImplementationWrapper
    *         <MyProviderA, MyServiceInterface>;
    *           
    *     }
    *     
    *     DECLARE_ART_SERVICE_INTERFACE_IMPL
    *       (myprov::MyServiceA, myprov::MyService, LEGACY)
    *     
    *     
    * The class `MyServiceInterface` is expected to have been defined via
    * `ServiceProviderInterfaceWrapper`.
    * An implementation file is necessary too, that will look like:
    *     
    *     #include "path/to/MyServiceA.h"
    *     
    *     DEFINE_ART_SERVICE_INTERFACE_IMPL
    *       (myprov::MyServiceA, myprov::MyService)
    *     
    * If callback registration is needed, a class can derive from this template
    * and still gain a bit of boilerplate facility. That is:
    * 
    * * a `provider_type` definition (required by `gar::providerFrom()`)
    * * a `provider()` method to access the provider (required by
    *   `gar::providerFrom()`)
    * - a `Parameters` definition (used by art to print accepted configuration)
    * - a constructor supporting FHiCL configuration validation
    * - transparent life management of the provider instance
    * * a `concrete_provider_type` definition (that is PROVIDER)
    * * a `service_interface_type` definition (that is INTERFACE)
    * 
    * Requirements on the service provider (PROVIDER):
    * - a data type `Config` being the configuration object. This is the object
    *   wrapped by `fhicl::Table` when performing FHiCL validation.
    * - a constructor with as argument a constant reference to a Config object.
    *   The provider should be configured by that constructor.
    * 
    * Requirements on the service interface (INTERFACE):
    * - a data type `provider_type` representing the abstract interface of the
    *   service provider
    * - a virtual method `do_provider()` where the retrieval of the provider
    *   is expected to happen; this method is overridden
    * 
    */
   template <typename PROVIDER, typename INTERFACE>
   class ServiceProviderImplementationWrapper: public INTERFACE {
      
         public:
      /// type of service provider implementation
      using concrete_provider_type = PROVIDER;
      
      /// art service interface class
      using service_interface_type = INTERFACE;
      
      /// type of service provider interface
      using provider_type = typename service_interface_type::provider_type;
      
      /// Type of configuration parameter (for art description)
      using Parameters
        = ::art::ServiceTable<typename concrete_provider_type::Config>;
      
      
      /// Constructor (using a configuration table)
      ServiceProviderImplementationWrapper
         (Parameters const& config, ::art::ActivityRegistry&)
         : prov(std::make_unique<concrete_provider_type>(config()))
         {}
      
      
         private:
      std::unique_ptr<concrete_provider_type> prov; ///< service provider
      
      /// Returns a constant pointer to the service provider
      virtual provider_type const* do_provider() const override
         { return prov.get(); }
      
   }; // ServiceProviderImplementationWrapper
   
   
} // namespace gar


#endif // COREUTILS_SERVICEPROVIDERWRAPPERS_H