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;
 
    // -----------------------------------------------------------------------
    // D2 (program plan §B.2.2) — HydroCouple component libraries
    // -----------------------------------------------------------------------
    //
    // A library that exports no `openswmm_plugin_info` is offered to this
    // catalogue before it is unloaded: if it carries the HydroCouple component
    // ABI (`hydrocouple_component_abi_v1`, HydroCouple's
    // `hydrocouplecomponentabi.h`) its stamp is compared against the engine's
    // own, and only on agreement is `hydrocouple_component_info_v1` called.
    //
    // PROCESS-GLOBAL, unlike the rest of this class. The plan's C API for it
    // takes no engine handle (§B.2.5 `swmm_component_library_count(void)`),
    // the same as the built-in `swmm_process_component_known_*` catalogue: a
    // component library is a fact about the installation, not about one
    // model. Every engine's `load_library` feeds the same catalogue, which
    // de-duplicates by path.
    //
    // Libraries stay loaded for the life of the process. The component-info
    // object is a function-local static INSIDE the library, and component
    // instances are host-owned objects whose code lives there too, so
    // unloading while anything could still refer to either is undefined
    // behaviour. Never unloading is the simple correct answer for a discovery
    // catalogue; only `component_catalog_reset_for_testing` closes handles.
    //
    // Without OPENSWMM_WITH_HYDROCOUPLE this compiles and answers "nothing
    // discovered"; the header exposes no HydroCouple type either way.

    struct ComponentLibraryRecord {
        std::string path; 
        std::string id;   
        std::string caption;
        std::string version;
        std::string kind;       
        std::string stamp;      
        std::string load_error; 
        void* info = nullptr;   
    };

    static bool hydrocouple_enabled() noexcept;

    static std::string component_abi_stamp();

    static int component_search_path_add(const std::string& dir);

    static std::vector<ComponentLibraryRecord> component_libraries();

    static void component_catalog_reset_for_testing();
 
    // -----------------------------------------------------------------------
    // Loading (from specs or explicit paths)
    // -----------------------------------------------------------------------

    int load_plugins(const std::vector<PluginSpec>& specs,
                     std::function<void(const std::string&)> warn_cb = {},
                     const SimulationContext* io = nullptr);
 
    // -----------------------------------------------------------------------
    // 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 = {},
                           IPluginComponentInfo* info = nullptr);
    void add_report_plugin(IReportPlugin* plugin, std::vector<std::string> args = {},
                           IPluginComponentInfo* info = nullptr);
    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_;
    std::unordered_map<void*, std::vector<std::string>> instance_args_;
    std::unordered_map<void*, IPluginComponentInfo*> instance_info_;
 
    // -----------------------------------------------------------------------
    // 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;
 
    // D2: the component catalogue's internals. Private statics because they
    // use platform_* above; the catalogue state itself is file-local in
    // PluginFactory.cpp. Callers must hold the catalogue mutex.
    static bool catalog_adopt_locked(const std::string& path, void* handle);
    static int catalog_scan_locked(const std::string& dir);
    static void catalog_defaults_locked();
};
 
} /* namespace openswmm */
 
#endif /* OPENSWMM_ENGINE_PLUGIN_FACTORY_HPP */