File Module.h

Copyright

This code is licensed under the 3-clause BSD license.

Copyright ETH Zurich, Laboratory for Physical Chemistry, Reiher Group.

See LICENSE.txt for details.

namespace Scine

namespace Core

class Module

#include <Module.h>

Abstract base class for a module, which flexibly provides consumers with common interface derived classes.

Modules supply consumers with instances of types satisfying a particular common interface concept. Any library that wishes to provide classes satisfying interfaces defined in Core must implement a single derived class of this interface.

Implementation notes:

• The has / get interface of a module is double-blind so that it can be used polymorphically within the ModuleManager. Its interface does not require knowledge of the Interface class nor the type of the model that satisfies it. This is for ease of implementation for derived classes.

• Get returns a type-erased wrapper around a shared_ptr to the base class of the interface that the desired model satisfies.

A class deriving from Module that will be part of a compilation unit intended to become a runtime dynamically-loaded library must offer an entry point for ModuleManager at global scope. A Module-derived class header file should look roughly like this:

* #include <Core/Module.h>
* #include <boost/hana/define_struct.hpp>
* #include <boost/dll/alias.hpp>
* #include <memory>
*
* namespace XYZ {
*
* class FooModule : public Core::Module {
* public:
*   // Use hana to define member variables that contain the model string
*   // name for interfaces for which you have at least one model
*   BOOST_HANA_DEFINE_STRUCT(FooModule, (std::vector<std::string>, sampleInterfaceName), ...);
*
*   // In your module constructor, populate your previously defined vec<str>
*   // members with the interfaces' model identifiers that you provide
*   FooModule(...) {
*     sampleInterfaceName = {"sampleModelName"};
*   }
*
*   // Implement name() and get(...)
*   // Use DerivedModule.h to implement has(...), announceInterfaces(),
*   //   announceModels(...)
*
*   // Add a factory
*   static std::shared_ptr<Core::Module> make() {
*     return std::make_shared<FooModule>(...);
*   }
* };
* } // namespace XYZ
*
* // At global scope, declare an entry point called "moduleFactory"
* BOOST_DLL_ALIAS(XYZ::FooModule::make, moduleFactory)
* 

Mandatory virtual interface

Announces the module’s name

virtual std::string name() const = 0

virtual boost::any get(const std::string&, const std::string&) const = 0

Creates a type-erased wrapper around a shared_ptr to a model of a interface.

Return

A type-erased interface model. Use try_cast to extract a pointer to the desired interface interface.

Exceptions

• X: If the derived class does not supply models of the interface.

virtual bool has(const std::string&, const std::string&) const = 0

Checks if this module supplies a particular model of an interface.

Note

Derived classes that make use of BOOST_HANA_DEFINE_STRUCT can implement this function using DerivedModule.h:

* bool FooModule::has(const std::string& interface, const std::string& model) const noexcept final {
*   return Core::DerivedModule::has(interface, model, *this);
* }
* 

virtual std::vector<std::string> announceInterfaces() const = 0

Announces all interfaces of which the module provides at least one model.

Note

Derived classes that make use of BOOST_HANA_DEFINE_STRUCT can implement this function using DerivedModule.h:

* bool FooModule::announceInterfaces() const noexcept final {
*   return Core::DerivedModule::announceInterfaces(*this);
* }
* 

virtual std::vector<std::string> announceModels(const std::string &interface) const = 0

Announces all models of a particular interface that the module provides

Note

If the class supplies no models of a particular interface, this list is empty.

Derived classes that make use of BOOST_HANA_DEFINE_STRUCT can implement this function using DerivedModule.h:

* bool FooModule::announceModels(const std::string& interface) const noexcept final {
*   return Core::DerivedModule::announceModels(interface, *this);
* }
* 

Public Functions

virtual ~Module()