openswmm::IStateIOPlugin Class Reference

Interface for state / hot-start IO plugins. More...

#include <IStateIOPlugin.hpp>

Inheritance diagram for openswmm::IStateIOPlugin:

Collaboration diagram for openswmm::IStateIOPlugin:

Public Member Functions
virtual	~IStateIOPlugin ()=default
virtual PluginState	state () const noexcept=0
	Query the current plugin state.
virtual int	initialize (const std::vector< std::string > &init_args, const IPluginComponentInfo *info)=0
	Initialize from [PLUGINS] arguments.
virtual int	validate (const SimulationContext &ctx)=0
	Validate configuration against the loaded model.
virtual bool	can_read (const std::string &path) const
	Cheap format sniff used to dispatch a path to the right plugin.
virtual int	read_state (const std::string &path, SimulationContext &ctx)=0
	Read state from a file and apply it to the simulation context.
virtual int	write_state (const std::string &path, const SimulationContext &ctx)=0
	Write the current simulation state to a file.
virtual std::vector< std::string >	warnings () const
	Non-fatal warnings accumulated during the last call.
virtual int	finalize (const SimulationContext &ctx)=0
	Finalize and release resources.
virtual const char *	last_error_message () const noexcept
	Get the last error message.

Detailed Description

Interface for state / hot-start IO plugins.

Constructor & Destructor Documentation

~IStateIOPlugin()

virtual openswmm::IStateIOPlugin::~IStateIOPlugin ( )

virtualdefault

Member Function Documentation

can_read()

virtual bool openswmm::IStateIOPlugin::can_read ( const std::string &  path ) const

inlinevirtual

Cheap format sniff used to dispatch a path to the right plugin.

Implementations should peek at file extension and/or a small fixed-size header (magic number) and return true if this plugin can read the file. Must NOT perform a full parse — the engine calls this on every registered state plugin in registration order to pick the first match.

Parameters

path	Path to a candidate state file.

Returns

true if this plugin recognizes the file format.

Reimplemented in openswmm::DefaultStateIOPlugin.

finalize()

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

pure virtual

Finalize and release resources.

Parameters

ctx	Simulation context.

Returns

0 on success.

Postcondition

state() == PluginState::FINALIZED on success.

Implemented in openswmm::DefaultStateIOPlugin.

initialize()

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

pure virtual

Initialize from [PLUGINS] arguments.

Parameters

init_args	Tokenized arguments from the [PLUGINS] line.
info	Back-pointer to IPluginComponentInfo.

Returns

0 on success.

Postcondition

state() == PluginState::INITIALIZED on success.

Implemented in openswmm::DefaultStateIOPlugin.

last_error_message()

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

inlinevirtualnoexcept

Get the last error message.

Reimplemented in openswmm::DefaultStateIOPlugin.

read_state()

virtual int openswmm::IStateIOPlugin::read_state ( const std::string &  path, SimulationContext &  ctx  )

pure virtual

Read state from a file and apply it to the simulation context.

Called BEFORE simulation start (engine in INITIALIZED state). Restores node depths/heads/volumes, link flows/depths/volumes, subcatchment runoff, and any solver-internal state (infiltration, groundwater, snowpack) exposed via SimulationContext accessors.

Missing objects (present in the file but not in the model, or vice versa) are reported via warnings() and do NOT cause a non-zero return — the caller decides how strict to be.

Parameters

path	Path to the state file.
ctx	Simulation context to populate.

Returns

0 on success, non-zero error code on failure.

Implemented in openswmm::DefaultStateIOPlugin.

state()

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

pure virtualnoexcept

Query the current plugin state.

Implemented in openswmm::DefaultStateIOPlugin.

validate()

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

pure virtual

Validate configuration against the loaded model.

Parameters

ctx	Simulation context (after input parsing).

Returns

0 on success.

Postcondition

state() == PluginState::VALIDATED on success.

Implemented in openswmm::DefaultStateIOPlugin.

warnings()

virtual std::vector< std::string > openswmm::IStateIOPlugin::warnings ( ) const

inlinevirtual

Non-fatal warnings accumulated during the last call.

Typical contents: "node 'J3' present in hot-start file but not in model — skipped". Cleared at the start of each read_state()/write_state() call.

Returns

Vector of warning messages (empty by default).

Reimplemented in openswmm::DefaultStateIOPlugin.

write_state()

virtual int openswmm::IStateIOPlugin::write_state ( const std::string &  path, const SimulationContext &  ctx  )

pure virtual

Write the current simulation state to a file.

Safe to call repeatedly during a run for scheduled checkpoints and once at the end for the final snapshot. Implementations should NOT hold the file open between calls — each call opens, writes, fsyncs, and closes.

Parameters

path	Destination path.
ctx	Simulation context to serialize.

Returns

0 on success, non-zero error code on failure.

Implemented in openswmm::DefaultStateIOPlugin.

---

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

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