Manages plugin discovery, loading, and lifecycle for one engine instance. More...

#include <PluginFactory.hpp>

Collaboration diagram for openswmm::PluginFactory:

Classes
struct	ComponentEntry
	List all discovered component info entries. More...

struct	ComponentLibraryRecord

Public Member Functions
	PluginFactory ()
	Register builtin metadata and scan the engine library directory plus plugins/components. Does not construct plugin instances. Discovery can load dynamic-library code and run metadata entry points; filesystem/allocation/plugin exceptions propagate. Directory iteration order is not globally sorted for ordinary IO-plugin discovery.

	~PluginFactory ()
	Delete owned plugin instances before unloading per-instance IO libraries. Requires no outstanding update/callback/borrowed plugin use; global HydroCouple catalogue handles are retained separately until process exit or explicit test reset.

	PluginFactory (const PluginFactory &)=delete
	Disable copying owned plugin pointers and library references.

PluginFactory &	operator= (const PluginFactory &)=delete
	Disable copy assignment of plugin/library ownership.

	PluginFactory (PluginFactory &&) noexcept=default
	Move the registry, raw-pointer ownership lists and library entries.

PluginFactory &	operator= (PluginFactory &&) noexcept=default
	Move-assign registry and ownership containers using their default operations.

void	discover (std::function< void(const std::string &)> warn_cb={})
	Rescan the host library directory and its plugins/components subdirectories.

IPluginComponentInfo *	load_library (const std::string &path, std::function< void(const std::string &)> warn_cb={})
	Load/register an IO plugin or offer a non-IO library to the global component catalogue.

IPluginComponentInfo *	find_component (const std::string &id_or_path, std::function< void(const std::string &)> warn_cb={})
	Resolve an exact registered ID/version or load an apparent platform library path.

std::vector< ComponentEntry >	discovered_components () const
	Snapshot registered metadata/capabilities in retained library order.

int	load_plugins (const std::vector< PluginSpec > &specs, std::function< void(const std::string &)> warn_cb={}, const SimulationContext *io=nullptr)
	Resolve specs and create every advertised input/output/report/state-IO capability.

int	initialize_all (SimulationContext &ctx)
	Initialize output, report and state-IO instances in that order.

int	validate_all (SimulationContext &ctx)
	Validate INITIALIZED output/report/state-IO plugins in list order.

int	prepare_all (SimulationContext &ctx)
	Prepare VALIDATED output and report plugins.

int	update_all (const SimulationSnapshot &snapshot)
	Deliver a snapshot to PREPARED/UPDATING output and report plugins.

int	finalize_all (SimulationContext &ctx)
	Finalize every output/report/state-IO plugin without a state gate.

int	write_summary_all (SimulationContext &ctx)
	Ask every report plugin to write a summary without a state gate.

const std::vector< IInputPlugin * > &	input_plugins () const noexcept
	Borrow the retained capability list without transferring ownership.

const std::vector< IOutputPlugin * > &	output_plugins () const noexcept
	Borrow the retained capability list without transferring ownership.

const std::vector< IReportPlugin * > &	report_plugins () const noexcept
	Borrow the retained capability list without transferring ownership.

const std::vector< IStateIOPlugin * > &	state_io_plugins () const noexcept
	Borrow the retained capability list without transferring ownership.

int	plugin_count () const noexcept
	Count all injected/created capability instances.

bool	empty () const noexcept
	Test whether any capability instance is retained.

void	unload_all ()
	Delete all owned capability instances, clear registries/args and release IO library handles. Does not implicitly finalize plugins or wait for IOThread. Caller must drain callbacks and cease borrowed-pointer use first. Builtin metadata singletons survive; process-global component records/handles are not cleared.

void	add_output_plugin (IOutputPlugin plugin, std::vector< std::string > args={}, IPluginComponentInfo info=nullptr)
	Adopt a programmatically constructed output plugin without lifecycle calls.

void	add_report_plugin (IReportPlugin plugin, std::vector< std::string > args={}, IPluginComponentInfo info=nullptr)
	Adopt a report plugin without lifecycle calls or validation.

void	add_input_plugin (IInputPlugin *plugin)
	Adopt an input plugin without lifecycle calls or validation.

void	add_state_io_plugin (IStateIOPlugin *plugin)
	Adopt a state-IO plugin without lifecycle calls or validation.

Static Public Member Functions
static bool	hydrocouple_enabled () noexcept
	Report this build's optional HydroCouple component-loader support.

static std::string	component_abi_stamp ()
	Copy the engine's HydroCouple component ABI fingerprint.

static int	component_search_path_add (const std::string &dir)
	Scan an explicit directory into the process-global component catalogue.

static std::vector< ComponentLibraryRecord >	component_libraries ()
	Snapshot process-global loaded/refused component records under its mutex.

static void	component_catalog_reset_for_testing ()
	Close globally retained component handles and reset records/default-discovery state. Tests must ensure no component instances, metadata pointers or executing code remain borrowed. Mutex serializes catalogue mutation but cannot make live instance unloading safe. The next query rediscovers defaults/environment.

Detailed Description

Manages plugin discovery, loading, and lifecycle for one engine instance.

One PluginFactory per SWMMEngine instance (NOT a singleton). On construction, auto-discovers compatible plugin libraries in standard search directories.

Constructor & Destructor Documentation

◆ PluginFactory() [1/3]

openswmm::PluginFactory::PluginFactory ( )

Register builtin metadata and scan the engine library directory plus plugins/components. Does not construct plugin instances. Discovery can load dynamic-library code and run metadata entry points; filesystem/allocation/plugin exceptions propagate. Directory iteration order is not globally sorted for ordinary IO-plugin discovery.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ ~PluginFactory()

openswmm::PluginFactory::~PluginFactory ( )

Delete owned plugin instances before unloading per-instance IO libraries. Requires no outstanding update/callback/borrowed plugin use; global HydroCouple catalogue handles are retained separately until process exit or explicit test reset.

Here is the call graph for this function:

◆ PluginFactory() [2/3]

openswmm::PluginFactory::PluginFactory ( const PluginFactory & )

delete

Disable copying owned plugin pointers and library references.

Here is the call graph for this function:

◆ PluginFactory() [3/3]

openswmm::PluginFactory::PluginFactory ( PluginFactory && )

defaultnoexcept

Move the registry, raw-pointer ownership lists and library entries.

Source: The unnamed source must have no outstanding operations/borrowed factory references. Callers must not continue using moved-from plugin collections as live ownership.

Here is the call graph for this function:

Member Function Documentation

◆ add_input_plugin()

void openswmm::PluginFactory::add_input_plugin ( IInputPlugin * plugin )

Adopt an input plugin without lifecycle calls or validation.

Parameters

plugin Required nonnull uniquely owned instance, deleted on unload. Input lifecycle is managed separately from the all() output/report dispatchers.

◆ add_output_plugin()

void openswmm::PluginFactory::add_output_plugin	(	IOutputPlugin *	plugin,
		std::vector< std::string >	args = {},
		IPluginComponentInfo *	info = nullptr )

Adopt a programmatically constructed output plugin without lifecycle calls.

Parameters

plugin	Required nonnull, uniquely owned compatible instance; no null or duplicate checks occur. Factory deletes it on unload.
args	Initialization strings moved into the output's positional args slot. Caller must avoid concurrent dispatch; allocation failure can leave partially appended lists.

◆ add_report_plugin()

void openswmm::PluginFactory::add_report_plugin	(	IReportPlugin *	plugin,
		std::vector< std::string >	args = {},
		IPluginComponentInfo *	info = nullptr )

Adopt a report plugin without lifecycle calls or validation.

Parameters

plugin Required nonnull uniquely owned instance, deleted on unload. Do not insert a duplicate pointer or mutate lists concurrently with dispatch.

◆ add_state_io_plugin()

void openswmm::PluginFactory::add_state_io_plugin ( IStateIOPlugin * plugin )

Adopt a state-IO plugin without lifecycle calls or validation.

Parameters

plugin Required nonnull uniquely owned instance, deleted on unload. Do not insert duplicates or race active dispatch/collection access.

◆ component_abi_stamp()

std::string openswmm::PluginFactory::component_abi_stamp ( )

static

Copy the engine's HydroCouple component ABI fingerprint.

Returns: Build stamp, or empty when optional support is absent.

◆ component_catalog_reset_for_testing()

void openswmm::PluginFactory::component_catalog_reset_for_testing ( )

static

Close globally retained component handles and reset records/default-discovery state. Tests must ensure no component instances, metadata pointers or executing code remain borrowed. Mutex serializes catalogue mutation but cannot make live instance unloading safe. The next query rediscovers defaults/environment.

◆ component_libraries()

std::vector< PluginFactory::ComponentLibraryRecord > openswmm::PluginFactory::component_libraries ( )

static

Snapshot process-global loaded/refused component records under its mutex.

Returns: Owned records with borrowed opaque info pointers, valid until test reset or process exit. First supported call scans default library-relative directories and HYDROCOUPLE_COMPONENT_PATH; ordinary per-factory IO-plugin entries are excluded.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ component_search_path_add()

int openswmm::PluginFactory::component_search_path_add ( const std::string & dir )

static

Scan an explicit directory into the process-global component catalogue.

Parameters

dir	Existing directory; platform path encoding rules apply. Defaults are scanned first so explicit candidates cannot replace default IDs. The path is recorded for bookkeeping; later queries do not automatically rescan it.

Returns: Newly recorded loaded/refused components, or -1 without support/valid directory. Uses the catalogue mutex; sorted candidate paths make first-ID wins deterministic within a directory. May load library code; exceptions propagate.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ discover()

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

Rescan the host library directory and its plugins/components subdirectories.

Parameters

warn_cb Optional synchronous per-load warning sink; absent sinks drop those warnings. Callback exceptions propagate. Existing entries with the exact path spelling are skipped; no instances are created and missing components are not removed. Filesystem scans are shallow and unsorted for ordinary plugins.

Here is the caller graph for this function:

◆ discovered_components()

std::vector< PluginFactory::ComponentEntry > openswmm::PluginFactory::discovered_components ( ) const

Snapshot registered metadata/capabilities in retained library order.

Returns: Owned strings/flags with borrowed info pointers. Multiple entries can share an ID/version despite registry aliases; pointers expire on unload. Builtin is detected by synthetic path spelling, not by probing the library handle.

Here is the caller graph for this function:

◆ empty()

bool openswmm::PluginFactory::empty ( ) const

inlinenoexcept

Test whether any capability instance is retained.

Returns: plugin_count()==0; discovered metadata can still be present.

Here is the call graph for this function:

◆ finalize_all()

int openswmm::PluginFactory::finalize_all ( SimulationContext & ctx )

Finalize every output/report/state-IO plugin without a state gate.

Parameters

[in,out] ctx Borrowed mutable engine state. Input plugins are skipped.

Returns: Last nonzero result, or zero; continues after returned errors, propagates exceptions and retains earlier effects. Caller first drains outstanding IO updates.

◆ find_component()

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

Resolve an exact registered ID/version or load an apparent platform library path.

Parameters

id_or_path	Exact string; empty returns null. Slash/backslash or a recognized platform suffix routes to load_library(); otherwise lookup is case-sensitive.
warn_cb	Optional synchronous warning sink for load/lookup failure.

Returns: Borrowed metadata valid until unload/destruction, or null. An unversioned ID uses its first-loaded alias; no semantic-version comparison is performed.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ hydrocouple_enabled()

bool openswmm::PluginFactory::hydrocouple_enabled ( )

staticnoexcept

Report this build's optional HydroCouple component-loader support.

Returns: Compile-time support flag, not whether components were discovered.

Here is the caller graph for this function:

◆ initialize_all()

int openswmm::PluginFactory::initialize_all ( SimulationContext & ctx )

Initialize output, report and state-IO instances in that order.

Parameters

ctx	Unused context; input instances are not initialized by this dispatcher. Each instance receives its retained positional arguments and originating component metadata.

Returns: Last nonzero initialize result, or zero; calls continue after returned errors and have no state gate. Plugin exceptions propagate without rollback.

◆ input_plugins()

const std::vector< IInputPlugin * > & openswmm::PluginFactory::input_plugins ( ) const

inlinenoexcept

Borrow the retained capability list without transferring ownership.

Returns: input pointers owned by this factory; collection references/elements can be invalidated by load/injection/move/unload. Do not mutate/delete instances or race collection changes through borrowed access.

◆ load_library()

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

Load/register an IO plugin or offer a non-IO library to the global component catalogue.

Parameters

path	Platform path spelling, compared literally for per-instance duplicates. Native loader uses LoadLibraryA or dlopen(RTLD_NOW\|RTLD_LOCAL); WebAssembly cannot dynamically load. IO metadata entry points are invoked without a separate ABI stamp check; loaded plugins must match the engine toolchain/SDK.
warn_cb	Optional synchronous warning sink; absent means no warning output.

Returns: Borrowed IO metadata, valid until unload/destruction, or null for failure/ non-IO components. The latter can still have been adopted by the process-global catalogue. Registering the same id:version replaces that exact key's lookup; the unversioned id keeps its first-loaded alias. Failure is not an exception boundary, and allocation/plugin exceptions can leave partial registrations/loaded handles.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ load_plugins()

int openswmm::PluginFactory::load_plugins	(	const std::vector< PluginSpec > &	specs,
		std::function< void(const std::string &)>	warn_cb = {},
		const SimulationContext *	io = nullptr )

Resolve specs and create every advertised input/output/report/state-IO capability.

Parameters

specs	Borrowed ordered specs; path selects metadata and init_args are retained with each created capability instance. Explicit IO role selections suppress legacy output/report discovery for that role. Existing instances remain.
warn_cb	Optional synchronous resolution-warning sink.

Returns: Count of specs whose metadata resolved, even if factory methods returned no plugin instances. No lifecycle method is called here. Returned raw plugin objects become owned by this factory; allocation/plugin exceptions propagate.

Here is the call graph for this function:

◆ operator=() [1/2]

PluginFactory & openswmm::PluginFactory::operator= ( const PluginFactory & )

delete

Disable copy assignment of plugin/library ownership.

Here is the call graph for this function:

◆ operator=() [2/2]

PluginFactory & openswmm::PluginFactory::operator= ( PluginFactory && )

defaultnoexcept

Move-assign registry and ownership containers using their default operations.

Source and destination: The unnamed source supplies ownership; destination must first unload its existing plugins/libraries, because default vector assignment does not delete raw plugin pointers or release platform handles stored in discarded entries. No active IO or borrowed pointer use may overlap the move.

Returns: This factory.

Here is the call graph for this function:

◆ output_plugins()

const std::vector< IOutputPlugin * > & openswmm::PluginFactory::output_plugins ( ) const

inlinenoexcept

Borrow the retained capability list without transferring ownership.

Returns: output pointers owned by this factory; collection references/elements can be invalidated by load/injection/move/unload. Do not mutate/delete instances or race collection changes through borrowed access.

◆ plugin_count()

int openswmm::PluginFactory::plugin_count ( ) const

inlinenoexcept

Count all injected/created capability instances.

Returns: Sum of input/output/report/state-IO list lengths as int, not library/spec count.

Here is the caller graph for this function:

◆ prepare_all()

int openswmm::PluginFactory::prepare_all ( SimulationContext & ctx )

Prepare VALIDATED output and report plugins.

Parameters

[in,out] ctx Borrowed mutable state; input and state-IO plugins are not prepared by this dispatcher, regardless of their state.

Returns: Last nonzero result, or zero; continues after return-code errors. Exceptions propagate and earlier side effects are retained.

◆ report_plugins()

const std::vector< IReportPlugin * > & openswmm::PluginFactory::report_plugins ( ) const

inlinenoexcept

Borrow the retained capability list without transferring ownership.

Returns: report pointers owned by this factory; collection references/elements can be invalidated by load/injection/move/unload. Do not mutate/delete instances or race collection changes through borrowed access.

◆ state_io_plugins()

const std::vector< IStateIOPlugin * > & openswmm::PluginFactory::state_io_plugins ( ) const

inlinenoexcept

Borrow the retained capability list without transferring ownership.

Returns: state_io pointers owned by this factory; collection references/elements can be invalidated by load/injection/move/unload. Do not mutate/delete instances or race collection changes through borrowed access.

◆ unload_all()

void openswmm::PluginFactory::unload_all ( )

Delete all owned capability instances, clear registries/args and release IO library handles. Does not implicitly finalize plugins or wait for IOThread. Caller must drain callbacks and cease borrowed-pointer use first. Builtin metadata singletons survive; process-global component records/handles are not cleared.

Here is the caller graph for this function:

◆ update_all()

int openswmm::PluginFactory::update_all ( const SimulationSnapshot & snapshot )

Deliver a snapshot to PREPARED/UPDATING output and report plugins.

Parameters

snapshot Borrowed immutable packet valid only during each callback; plugins must copy data they retain. Called serially by IOThread in native builds. Input/state-IO plugins and other states are skipped.

Returns: Last nonzero update result, or zero; dispatch continues after returned errors. No exception boundary or collection mutex is supplied. Do not race unload/lifecycle/injection or read mutable context through an unsynchronized alias.

◆ validate_all()

int openswmm::PluginFactory::validate_all ( SimulationContext & ctx )

Validate INITIALIZED output/report/state-IO plugins in list order.

Parameters

[in,out] ctx Borrowed engine state passed to each eligible plugin; input plugins and all non-INITIALIZED instances are skipped.

Returns: Last nonzero result, or zero; later eligible plugins still run after returned errors. Exceptions propagate and earlier mutations are not rolled back.

◆ write_summary_all()

int openswmm::PluginFactory::write_summary_all ( SimulationContext & ctx )

Ask every report plugin to write a summary without a state gate.

Parameters

[in,out] ctx Borrowed engine state used by report implementations.

Returns: Last nonzero result, or zero; continues after returned errors. No other capability is called, and exceptions/IO side effects are not rolled back.

The documentation for this class was generated from the following files:

/home/runner/work/openswmm.engine/openswmm.engine/src/engine/plugins/PluginFactory.hpp
/home/runner/work/openswmm.engine/openswmm.engine/src/engine/plugins/PluginFactory.cpp

Classes

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ PluginFactory() [1/3]

◆ ~PluginFactory()

◆ PluginFactory() [2/3]

◆ PluginFactory() [3/3]

Member Function Documentation

◆ add_input_plugin()

◆ add_output_plugin()

◆ add_report_plugin()

◆ add_state_io_plugin()

◆ component_abi_stamp()

◆ component_catalog_reset_for_testing()

◆ component_libraries()

◆ component_search_path_add()

◆ discover()

◆ discovered_components()

◆ empty()

◆ finalize_all()

◆ find_component()

◆ hydrocouple_enabled()

◆ initialize_all()

◆ input_plugins()

◆ load_library()

◆ load_plugins()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ output_plugins()

◆ plugin_count()

◆ prepare_all()

◆ report_plugins()

◆ state_io_plugins()

◆ unload_all()

◆ update_all()

◆ validate_all()

◆ write_summary_all()