ipfixprobe - introduce pluginFactory

Author: SiskaPavel

include/ipfixprobe/pluginFactory/pluginFactory.hpp

@@ -0,0 +1,151 @@
+/**
+ * @file
+ * @author Pavel Siska <[email protected]>
+ *
+ * @brief This file contains the definition of the `PluginFactory` class. The class is responsible
+ * for registering plugins and creating instances of those plugins via generator functions. It
+ * provides support for various types of object creation, including unique pointers, shared
+ * pointers and in-place construction.
+ *
+ * @copyright Copyright (c) 2025 CESNET, z.s.p.o.
+ */
+
+#pragma once
+
+#include "pluginGenerator.hpp"
+#include "pluginManifest.hpp"
+
+#include <map>
+#include <memory>
+#include <stdexcept>
+#include <string_view>
+#include <type_traits>
+
+namespace ipxp {
+
+/**
+ * @brief Templated class `PluginFactory` is responsible for managing and creating plugin instances.
+ *
+ * The `PluginFactory` class provides a singleton-based interface for registering plugins
+ * and generating their instances. It supports creating unique and shared pointers, as well as
+ * objects constructed at pre-allocated memory. Each plugin is identified by a `PluginManifest`.
+ *
+ * @tparam Base The base class type that all plugins must inherit from.
+ * @tparam Args The types of arguments that will be passed to the plugin constructors.
+ */
+template<typename Base, typename... Args>
+class PluginFactory {
+public:
+	/**
+	 * @brief Retrieves the singleton instance of `PluginFactory`.
+	 *
+	 * @return A reference to the singleton `PluginFactory` instance.
+	 */
+	static PluginFactory& getInstance()
+	{
+		static PluginFactory instance;
+		return instance;
+	}
+
+	/**
+	 * @brief Registers a plugin with the factory.
+	 *
+	 * This function registers a plugin by associating its manifest with its generator functions.
+	 * The function enforces that the `Derived` type must inherit from the `Base` class.
+	 *
+	 * @tparam Derived The plugin type (class) that inherits from the `Base` class.
+	 * @param manifest The manifest containing metadata about the plugin.
+	 *
+	 * @throw std::logic_error If `Derived` is not derived from `Base`.
+	 */
+	template<typename Derived>
+	void registerPlugin(const PluginManifest& manifest)
+	{
+		static_assert(std::is_base_of<Base, Derived>::value, "Derived must be a subclass of Base");
+
+		m_registeredPlugins[manifest] = createGenerators<Base, Derived, Args...>();
+	}
+
+	/**
+	 * @brief Retrieves a list of all registered plugins.
+	 *
+	 * @return A vector of `PluginManifest` objects representing the registered plugins.
+	 */
+	[[nodiscard]] std::vector<PluginManifest> getRegisteredPlugins()
+	{
+		std::vector<PluginManifest> registeredPlugins;
+		registeredPlugins.reserve(m_registeredPlugins.size());
+
+		for (const auto& [pluginManifest, _] : m_registeredPlugins) {
+			registeredPlugins.push_back(pluginManifest);
+		}
+		return registeredPlugins;
+	}
+
+	/**
+	 * @brief Creates a unique pointer to a plugin instance.
+	 *
+	 * @param key The key identifying the plugin (from the manifest).
+	 * @param args The arguments passed to the plugin constructor.
+	 * @return A unique pointer to the plugin instance.
+	 * @throws std::runtime_error If the plugin identified by the key is not registered.
+	 * @throws Any exception from the plugin constructor.
+	 */
+	[[nodiscard]] std::unique_ptr<Base> createUnique(std::string_view key, Args... args) const
+	{
+		const auto& generators = getGenerators(key);
+		return generators.uniqueGenerator(std::forward<Args>(args)...);
+	}
+
+	/**
+	 * @brief Creates a shared pointer to a plugin instance.
+	 *
+	 * @param key The key identifying the plugin (from the manifest).
+	 * @param args The arguments passed to the plugin constructor.
+	 * @return A shared pointer to the plugin instance.
+	 * @throws std::runtime_error If the plugin identified by the key is not registered.
+	 * @throws Any exception from the plugin constructor.
+	 */
+	[[nodiscard]] std::shared_ptr<Base> createShared(std::string_view key, Args... args) const
+	{
+		const auto& generators = getGenerators(key);
+		return generators.sharedGenerator(std::forward<Args>(args)...);
+	}
+
+	/**
+	 * @brief Constructs a plugin instance at a pre-allocated memory location.
+	 *
+	 * @param key The key identifying the plugin (from the manifest).
+	 * @param ptr The pre-allocated memory where the instance will be constructed.
+	 * @param args The arguments passed to the plugin constructor.
+	 * @return A pointer to the constructed plugin instance.
+	 * @throws std::runtime_error If the plugin identified by the key is not registered.
+	 * @throws Any exception from the plugin constructor.
+	 */
+	[[nodiscard]] Base* constructAt(std::string_view key, void* ptr, Args... args) const
+	{
+		const auto& generators = getGenerators(key);
+		return generators.constructAtGenerator(ptr, std::forward<Args>(args)...);
+	}
+
+private:
+	PluginFactory() = default;
+
+	using Generators = BaseGenerators<Base, Args...>;
+
+	Generators getGenerators(std::string_view key) const
+	{
+		const auto iter = m_registeredPlugins.find(key);
+		if (iter == m_registeredPlugins.end()) {
+			throw std::runtime_error(
+				"PluginFactory::getGenerators() has failed. Plugin: '" + std::string(key)
+				+ "' is not registered.");
+		}
+
+		return iter->second;
+	}
+
+	std::map<PluginManifest, Generators> m_registeredPlugins;
+};
+
+} // namespace ipxp

include/ipfixprobe/pluginFactory/pluginGenerator.hpp

@@ -0,0 +1,75 @@
+/**
+ * @file
+ * @author Pavel Siska <[email protected]>
+ *
+ * @brief This file contains the definition of the `BaseGenerators` struct and the
+ * `createGenerators` function. The `BaseGenerators` struct provides generator functions for
+ * creating instances of derived classes from a base class. This includes support for unique
+ * pointers, shared pointers and constructing at pre-allocated memory.
+ *
+ * @copyright Copyright (c) 2025 CESNET, z.s.p.o.
+ */
+
+#pragma once
+
+#include <functional>
+#include <memory>
+#include <type_traits>
+
+namespace ipxp {
+
+/**
+ * @brief Templated struct `BaseGenerators` provides generator functions for creating instances of
+ * derived classes from a base class.
+ *
+ * @tparam Base The base class type.
+ * @tparam Args The types of arguments for the generator functions (constructor of the derived
+ * class).
+ */
+template<typename Base, typename... Args>
+struct BaseGenerators {
+	std::function<std::unique_ptr<Base>(Args...)>
+		uniqueGenerator; ///< Generator for unique pointer.
+	std::function<std::shared_ptr<Base>(Args...)>
+		sharedGenerator; ///< Generator for shared pointer.
+	std::function<Base*(void*, Args...)>
+		constructAtGenerator; ///< Generator for constructing at pre-allocated memory.
+};
+
+/**
+ * @brief Creates a set of generator functions for constructing instances of a derived class.
+ *
+ * This function generates a `BaseGenerators` instance containing three callable functions
+ * that create instances of the specified derived type. The generators provide:
+ *  - A factory function returning `std::unique_ptr<Derived>`.
+ *  - A factory function returning `std::shared_ptr<Derived>`.
+ *  - A function for in-place construction using `std::construct_at`.
+ *
+ * The function ensures at compile-time that `Derived` is a subclass of `Base`. If `Derived`
+ * is not nothrow-constructible with `Args...`, the generator functions will not be marked
+ * as `noexcept`, meaning they can throw exceptions if the constructor of `Derived` fails.
+ *
+ * @tparam Base The base class type.
+ * @tparam Derived The derived class type (must inherit from `Base`).
+ * @tparam Args The types of arguments used to construct `Derived`.
+ * @return A `BaseGenerators` instance containing generator functions for creating `Derived`
+ * objects.
+ */
+template<typename Base, typename Derived, typename... Args>
+static BaseGenerators<Base, Args...> createGenerators() noexcept
+{
+	static_assert(std::is_base_of_v<Base, Derived>, "Derived must be a subclass of Base");
+
+	return {
+		[](Args... args) noexcept(std::is_nothrow_constructible_v<Derived, Args...>) {
+			return std::make_unique<Derived>(std::forward<Args>(args)...);
+		},
+		[](Args... args) noexcept(std::is_nothrow_constructible_v<Derived, Args...>) {
+			return std::make_shared<Derived>(std::forward<Args>(args)...);
+		},
+		[](void* ptr, Args... args) noexcept(std::is_nothrow_constructible_v<Derived, Args...>) {
+			return std::construct_at(static_cast<Derived*>(ptr), std::forward<Args>(args)...);
+		}};
+}
+
+} // namespace ipxp

include/ipfixprobe/pluginFactory/pluginManifest.hpp

@@ -0,0 +1,63 @@
+/**
+ * @file
+ * @author Pavel Siska <[email protected]>
+ * @brief Definition of the PluginManifest struct and related utilities.
+ *
+ * This file contains the definition of the PluginManifest struct, which represents
+ * metadata and functionalities associated with a plugin. It also defines a custom comparator for
+ * PluginManifest instances.
+ *
+ * @copyright Copyright (c) 2025 CESNET, z.s.p.o.
+ */
+
+#pragma once
+
+#include <functional>
+#include <string>
+
+namespace ipxp {
+
+/**
+ * @brief Struct representing the metadata and functionalities associated with a plugin.
+ *
+ * The PluginManifest struct encapsulates important details about a plugin, such as its
+ * name, description, version, and the required API version. This metadata is used to
+ * identify and manage plugins within the system.
+ */
+struct PluginManifest {
+	std::string name; ///< Name of the plugin.
+	std::string description; ///< Description of the plugin.
+	std::string pluginVersion; ///< Version of the plugin.
+	std::string apiVersion; ///< Required API version.
+	std::function<void()> usage; ///< Function pointer to the plugin's usage.
+};
+
+/**
+ * @brief Custom less-than comparator for PluginManifest instances.
+ *
+ * This operator allows for sorting PluginManifest instances based on their name.
+ *
+ * @param lhs Left-hand side PluginManifest instance.
+ * @param rhs Right-hand side PluginManifest instance.
+ * @return True if the name of lhs is lexicographically less than the name of rhs, false otherwise.
+ */
+inline bool operator<(const PluginManifest& lhs, const PluginManifest& rhs)
+{
+	return lhs.name < rhs.name;
+}
+
+/**
+ * @brief Custom equality operator for PluginManifest instances.
+ *
+ * This operator allows for comparison between two PluginManifest instances based on their name.
+ *
+ * @param lhs Left-hand side PluginManifest instance.
+ * @param rhs Right-hand side PluginManifest instance.
+ * @return True if the names of both instances are equal, false otherwise.
+ */
+inline bool operator==(const PluginManifest& lhs, const PluginManifest& rhs)
+{
+	return lhs.name == rhs.name;
+}
+
+} // namespace ipxp

include/ipfixprobe/pluginFactory/pluginRegistrar.hpp

@@ -0,0 +1,99 @@
+/**
+ * @file
+ * @author Pavel Siska <[email protected]>
+ *
+ * @brief This file contains the definition of the `PluginRegistrar` struct.
+ * The struct is responsible for automatically registering a plugin with the `Factory`.
+ * It ensures that the `Derived` type is properly registered with the factory under
+ * the provided manifest.
+ *
+ * The `PluginRegistrar` template can be used to simplify the process of
+ * plugin registration. By specifying the `Derived` type and the corresponding
+ * `Factory`, this struct allows for easy integration of plugins into the
+ * factory system at runtime.
+ *
+ * @copyright Copyright (c) 2025 CESNET, z.s.p.o.
+ */
+
+#pragma once
+
+#include "pluginFactory.hpp"
+#include "pluginManifest.hpp"
+
+#include <stdexcept>
+#include <type_traits>
+
+namespace ipxp {
+
+/**
+ * @brief Templated struct `PluginRegistrar` is responsible for automatically registering
+ * a plugin with the specified `Factory` during construction.
+ *
+ * This struct registers a plugin with the factory at runtime. It allows for the specification of a
+ * `Derived` type, which must be registered under the provided `PluginManifest`. This facilitates
+ * the registration process, ensuring that the `Derived` class is integrated into the plugin system
+ * seamlessly.
+ *
+ * @tparam Derived The derived class type being registered.
+ * @tparam Factory The factory type responsible for managing plugins.
+ *
+ * @code
+ * //// basePlugin.hpp
+ *
+ * // Example of a base plugin class definition
+ * class BasePlugin {
+ * public:
+ *     virtual void doSomething() = 0; // Pure virtual function
+ * };
+ *
+ * // forward declaration of the factory type
+ * template<typename Base, typename... Args>
+ * class PluginFactory;
+ *
+ * // define the factory type
+ * // std::string is the type of the constructor parameter
+ * using BasePluginFactory = PluginFactory<BasePlugin, const std::string>;
+ *
+ * //// plugin.hpp
+ * #include "basePlugin.hpp"
+ *
+ * class DerivedPlugin : public BasePlugin {
+ * public:
+ *     // Constructor requiring a string parameter
+ *     DerivedPlugin(const std::string& params) {
+ *         // Initialize plugin with provided parameters
+ *     }
+ *
+ *     void doSomething() override {
+ *         // Implementation of the plugin's functionality
+ *     }
+ * };
+ *
+ * //// plugin.cpp
+ *
+ * #include "plugin.hpp"
+ * #include "pluginFactoryRegistration.hpp"
+ *
+ * // Registering the plugin with the factory
+ * // This ensures that the required constructor exists
+ * static const PluginRegistrar<DerivedPlugin, BasePluginFactory>
+ *     derivedRegistrator(pluginManifest);
+ * @endcode
+ */
+template<typename Derived, typename Factory>
+struct PluginRegistrar {
+	/**
+	 * @brief Constructor that automatically registers the `Derived` class with the factory.
+	 *
+	 * This constructor registers the `Derived` class plugin with the specified factory,
+	 * using the provided manifest.
+	 *
+	 * @param manifest The manifest containing metadata about the plugin.
+	 */
+	explicit PluginRegistrar(const PluginManifest& manifest)
+	{
+		Factory::getInstance().template registerPlugin<Derived>(manifest);
+	}
+};
+
+} // namespace ipxp