openswmm::IInputPlugin Class Reference

Interface for input file reader/writer plugins. More...

#include <IInputPlugin.hpp>

Inheritance diagram for openswmm::IInputPlugin:

Collaboration diagram for openswmm::IInputPlugin:

Public Member Functions
virtual	~IInputPlugin ()=default
	Destroy this polymorphic instance after its callbacks and resource lifecycle finish. Default base destructor performs no finalize, file flush, I/O-thread join or model cleanup. Host deletes instances while their library remains loaded; implementations release owned resources safely. Never delete shared component metadata here.
virtual PluginState	state () const noexcept=0
	Read this implementation's current plugin lifecycle state.
virtual int	initialize (const std::vector< std::string > &init_args, const IPluginComponentInfo *info)=0
	Parse instance configuration before model validation/preparation.
virtual int	validate (const SimulationContext &ctx)=0
	Qualify instance configuration against the loaded compatible model.
virtual int	read (const std::string &path, SimulationContext &ctx)=0
	Populate authored model data from the plugin's supported input format.
virtual int	write (const std::string &path, const SimulationContext &ctx)=0
	Serialize authored model data in this input plugin's format.
virtual std::vector< std::string >	skipped_sections () const
	Copy unsupported section/element identifiers recorded by the last model read.
virtual int	finalize (const SimulationContext &ctx)=0
	Finish this instance after producer/update work has stopped.
virtual const char *	last_error_message () const noexcept
	Borrow the latest implementation error text without clearing it.

Detailed Description

Interface for input file reader/writer plugins.

Constructor & Destructor Documentation

~IInputPlugin()

virtual openswmm::IInputPlugin::~IInputPlugin ( )

virtualdefault

Destroy this polymorphic instance after its callbacks and resource lifecycle finish. Default base destructor performs no finalize, file flush, I/O-thread join or model cleanup. Host deletes instances while their library remains loaded; implementations release owned resources safely. Never delete shared component metadata here.

Member Function Documentation

finalize()

virtual int openswmm::IInputPlugin::finalize ( const SimulationContext & ctx )

pure virtual

Finish this instance after producer/update work has stopped.

Parameters

ctx	Borrowed compatible final model/native-unit metadata for this call; read without mutation or retention of live pointers.

Returns

Zero on successful resource cleanup, otherwise implementation-specific error. Implementation owns flush/close/state transitions and repeat-call policy. Factory calls every instance without a state gate, including partly initialized ones, so cleanup must handle partial resources. Base destructor does not call this. Output/report callbacks must be drained/joined before this owning-thread call.

Implemented in openswmm::DefaultInputPlugin, openswmm::gpkg::GeoPackageInputPlugin, and openswmm::h5io::Hdf5InputPlugin.

Here is the caller graph for this function:

initialize()

virtual int openswmm::IInputPlugin::initialize ( const std::vector< std::string > & init_args, const IPluginComponentInfo * info )

pure virtual

Parse instance configuration before model validation/preparation.

Parameters

init_args	Borrowed tokens for this call; copy retained values. Factory output instances receive associated argument rows; report/state instances currently receive an empty vector through initialize_all. Input hosts configure separately.
info	Nullable borrowed component metadata. Library/host owns it; never free it. Factory currently chooses first loaded metadata with matching capability, so this pointer need not uniquely identify the instance. Retain only while the component library is loaded and host guarantees its lifetime.

Returns

Zero on success, otherwise implementation error code/diagnostic. Successful implementation sets INITIALIZED; factory aggregates codes without rollback or setting ERROR. Define/reject repeat initialization consistently. Avoid retaining live model references; defer model-dependent resources to later lifecycle calls.

Implemented in openswmm::DefaultInputPlugin, openswmm::gpkg::GeoPackageInputPlugin, and openswmm::h5io::Hdf5InputPlugin.

Here is the call graph for this function:

Here is the caller graph for this function:

last_error_message()

virtual const char * openswmm::IInputPlugin::last_error_message ( ) const

inlinevirtualnoexcept

Borrow the latest implementation error text without clearing it.

Returns

Null-terminated member/static bytes; default is a nonnull empty literal. Never free. Copy before the next potentially mutating plugin call or destruction; implementations define diagnostic invalidation and should return nonnull strings. No base synchronization; serialize access to mutable diagnostic storage. Must not throw.

Reimplemented in openswmm::DefaultInputPlugin, openswmm::gpkg::GeoPackageInputPlugin, and openswmm::h5io::Hdf5InputPlugin.

Here is the caller graph for this function:

read()

virtual int openswmm::IInputPlugin::read ( const std::string & path, SimulationContext & ctx )

pure virtual

Populate authored model data from the plugin's supported input format.

Parameters

	path	Borrowed filesystem/location string, interpreted by implementation; copy if retained. Host supplies valid syntax/access for the chosen format.
[in,out]	ctx	Owning host's model store to populate, including aligned arrays, names/options/tables and supported plugin_specs. Native authored/context unit conventions apply. Host resolves cross references and validates after return.

Returns

Zero on parsed success, otherwise format/I/O error with last diagnostic. Interface supplies no rollback; failed reads may partly populate context. Input plugin is injected before engine open, because unread PLUGINS cannot discover it. Owning simulation thread, serialized against all other model access.

Implemented in openswmm::DefaultInputPlugin, openswmm::gpkg::GeoPackageInputPlugin, and openswmm::h5io::Hdf5InputPlugin.

Here is the call graph for this function:

Here is the caller graph for this function:

skipped_sections()

virtual std::vector< std::string > openswmm::IInputPlugin::skipped_sections ( ) const

inlinevirtual

Copy unsupported section/element identifiers recorded by the last model read.

Returns

Owned independent strings; default empty. Format may use INP tags or its own keys. Empty alone does not establish full model fidelity or read success. Implementation defines reset timing; serialize query with read/configuration.

Reimplemented in openswmm::DefaultInputPlugin, openswmm::gpkg::GeoPackageInputPlugin, and openswmm::h5io::Hdf5InputPlugin.

Here is the call graph for this function:

Here is the caller graph for this function:

state()

virtual PluginState openswmm::IInputPlugin::state ( ) const

pure virtualnoexcept

Read this implementation's current plugin lifecycle state.

Returns

Implementation-maintained enum; factory uses it to gate validation, preparation and output updates, but does not automatically perform transitions. No ownership transfer. Base interface supplies no synchronization; serialize with mutation, or implement a safe concurrent query if a host needs one. Must not throw.

Implemented in openswmm::DefaultInputPlugin, openswmm::gpkg::GeoPackageInputPlugin, and openswmm::h5io::Hdf5InputPlugin.

validate()

virtual int openswmm::IInputPlugin::validate ( const SimulationContext & ctx )

pure virtual

Qualify instance configuration against the loaded compatible model.

Parameters

ctx	Borrowed read-only initialized model for this call; arrays use their native context units, not snapshot display units. Do not retain mutable/live-array views across execution or assume the host transfers ownership.

Returns

Zero when accepted, otherwise implementation-specific error code. Set VALIDATED on success and maintain failure diagnostics/state explicitly. Factory calls only INITIALIZED instances; neither base nor factory provides validation, transactional rollback or default path/identity compatibility checks.

Implemented in openswmm::DefaultInputPlugin, openswmm::gpkg::GeoPackageInputPlugin, and openswmm::h5io::Hdf5InputPlugin.

Here is the call graph for this function:

Here is the caller graph for this function:

write()

virtual int openswmm::IInputPlugin::write ( const std::string & path, const SimulationContext & ctx )

pure virtual

Serialize authored model data in this input plugin's format.

Parameters

path	Borrowed destination path/location; can be created/truncated/replaced according to implementation policy. No base atomic-write/durability guarantee.
ctx	Borrowed compatible read-only model in native authored/context units; not an output-time snapshot or ownership transfer.

Returns

Zero on success, otherwise implementation I/O/format code/diagnostic. May leave partial output on failure; does not imply a complete runtime checkpoint. Serialize call with model mutation and plugin configuration/resource access.

Implemented in openswmm::DefaultInputPlugin, openswmm::gpkg::GeoPackageInputPlugin, and openswmm::h5io::Hdf5InputPlugin.

Here is the call graph for this function:

Here is the caller graph for this function:

---

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

• /home/runner/work/openswmm.engine/openswmm.engine/include/openswmm/plugin_sdk/IInputPlugin.hpp