PluginFactory.hpp

Go to the documentation of this file.

// SPDX-License-Identifier: Apache-2.0
//
// Copyright 2026 Caleb Buahin
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

 
#ifndef OPENSWMM_ENGINE_PLUGIN_FACTORY_HPP
#define OPENSWMM_ENGINE_PLUGIN_FACTORY_HPP
 
#include <string>
#include <vector>
#include <unordered_map>
#include <functional>
 
// Forward declarations
namespace openswmm {
    class IPluginComponentInfo;
    class IInputPlugin;
    class IOutputPlugin;
    class IReportPlugin;
    class IStateIOPlugin;
    struct SimulationContext;
    struct SimulationSnapshot;
    struct PluginSpec;
    enum class PluginType;
}
 
namespace openswmm {

class PluginFactory {
public:
    PluginFactory();
    ~PluginFactory();
 
    // Non-copyable, movable
    PluginFactory(const PluginFactory&) = delete;
    PluginFactory& operator=(const PluginFactory&) = delete;
    PluginFactory(PluginFactory&&) noexcept = default;
    PluginFactory& operator=(PluginFactory&&) noexcept = default;
 
    // -----------------------------------------------------------------------
    // Discovery and resolution
    // -----------------------------------------------------------------------

    void discover(std::function<void(const std::string&)> warn_cb = {});

    IPluginComponentInfo* load_library(
        const std::string& path,
        std::function<void(const std::string&)> warn_cb = {}
    );

    IPluginComponentInfo* find_component(
        const std::string& id_or_path,
        std::function<void(const std::string&)> warn_cb = {}
    );

    struct ComponentEntry {
        std::string            id;
        std::string            version;
        bool                   has_input    = false;
        bool                   has_output   = false;
        bool                   has_report   = false;
        bool                   has_state_io = false;
        IPluginComponentInfo*  info = nullptr;

        bool                   is_builtin = false;
    };
    std::vector<ComponentEntry> discovered_components() const;
 
    // -----------------------------------------------------------------------
    // Loading (from specs or explicit paths)
    // -----------------------------------------------------------------------

    int load_plugins(
        const std::vector<PluginSpec>& specs,
        std::function<void(const std::string&)> warn_cb = {}
    );
 
    // -----------------------------------------------------------------------
    // Lifecycle dispatch (main thread — call in order)
    // -----------------------------------------------------------------------
 
    int initialize_all(SimulationContext& ctx);
    int validate_all(SimulationContext& ctx);
    int prepare_all(SimulationContext& ctx);
    int update_all(const SimulationSnapshot& snapshot);
    int finalize_all(SimulationContext& ctx);
    int write_summary_all(SimulationContext& ctx);
 
    // -----------------------------------------------------------------------
    // Introspection
    // -----------------------------------------------------------------------
 
    const std::vector<IInputPlugin*>&    input_plugins()    const noexcept { return input_plugins_; }
    const std::vector<IOutputPlugin*>&   output_plugins()   const noexcept { return output_plugins_; }
    const std::vector<IReportPlugin*>&   report_plugins()   const noexcept { return report_plugins_; }
    const std::vector<IStateIOPlugin*>&  state_io_plugins() const noexcept { return state_io_plugins_; }
 
    int plugin_count() const noexcept {
        return static_cast<int>(input_plugins_.size()
                              + output_plugins_.size()
                              + report_plugins_.size()
                              + state_io_plugins_.size());
    }
 
    bool empty() const noexcept { return plugin_count() == 0; }
 
    void unload_all();
 
    // -----------------------------------------------------------------------
    // Plugin injection (for built-in / programmatic plugins)
    // -----------------------------------------------------------------------
 
    void add_output_plugin(IOutputPlugin* plugin, std::vector<std::string> args = {});
    void add_report_plugin(IReportPlugin* plugin);
    void add_input_plugin(IInputPlugin* plugin);
    void add_state_io_plugin(IStateIOPlugin* plugin);
 
private:
    // -----------------------------------------------------------------------
    // Internal types
    // -----------------------------------------------------------------------
 
    struct LibEntry {
        void*                  handle = nullptr;
        IPluginComponentInfo*  info   = nullptr;
        std::string            path;
    };
 
    // -----------------------------------------------------------------------
    // Component registry
    // -----------------------------------------------------------------------

    std::unordered_map<std::string, std::size_t> registry_;
 
    // -----------------------------------------------------------------------
    // Plugin storage
    // -----------------------------------------------------------------------
 
    std::vector<LibEntry>         libs_;
    std::vector<IInputPlugin*>    input_plugins_;
    std::vector<IOutputPlugin*>   output_plugins_;
    std::vector<IReportPlugin*>   report_plugins_;
    std::vector<IStateIOPlugin*>  state_io_plugins_;
    std::vector<std::vector<std::string>> init_args_;
 
    // -----------------------------------------------------------------------
    // Helpers
    // -----------------------------------------------------------------------
 
    void scan_directory(const std::string& dir_path,
                        std::function<void(const std::string&)> warn_cb);

    void register_builtin_infos();

    void validate_filter_invariant(IPluginComponentInfo* info,
                                   const std::string& source_path,
                                   std::function<void(const std::string&)> warn_cb);
 
    static bool is_file_path(const std::string& str);
    static bool is_shared_library(const std::string& filename);
    static std::string get_library_directory();
 
    static void* platform_load(const std::string& path);
    static void  platform_unload(void* handle) noexcept;
    static void* platform_sym(void* handle, const char* sym) noexcept;
    static std::string platform_error() noexcept;
};
 
} /* namespace openswmm */
 
#endif /* OPENSWMM_ENGINE_PLUGIN_FACTORY_HPP */