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
	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 bool	can_read (const std::string &path) const
	Offer cheap format recognition for ordered state-reader dispatch.
virtual int	read_state (const std::string &path, SimulationContext &ctx)=0
	Decode supported persisted runtime state into an initialized compatible model.
virtual int	write_state (const std::string &path, const SimulationContext &ctx)=0
	Save supported runtime state at a caller-qualified accepted boundary.
virtual std::vector< std::string >	warnings () const
	Copy nonfatal diagnostics from the implementation's last state I/O operation.
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 state / hot-start IO plugins.

Constructor & Destructor Documentation

~IStateIOPlugin()

virtual openswmm::IStateIOPlugin::~IStateIOPlugin ( )

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

can_read()

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

inlinevirtual

Offer cheap format recognition for ordered state-reader dispatch.

Parameters

path	Borrowed candidate path; implementation may inspect extension or a small header, without full decode or mutation of live model state.

Returns

True if this instance recognizes format, false otherwise (base always false). Recognition does not certify file readability, identity or valid contents. First claiming reader wins in host dispatch; keep probe inexpensive and serialize with plugin resource mutation. No owned handle/path is returned.

Reimplemented in openswmm::DefaultStateIOPlugin.

Here is the call graph for this function:

Here is the caller graph for this function:

finalize()

virtual int openswmm::IStateIOPlugin::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::DefaultStateIOPlugin.

initialize()

virtual int openswmm::IStateIOPlugin::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::DefaultStateIOPlugin.

Here is the call graph for this function:

Here is the caller graph for this function:

last_error_message()

virtual const char * openswmm::IStateIOPlugin::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::DefaultStateIOPlugin.

read_state()

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

pure virtual

Decode supported persisted runtime state into an initialized compatible model.

Parameters

	path	Borrowed source path/location; validity, identity and schema are implementation-qualified independently of can_read's cheap recognition.
[in,out]	ctx	Host-owned initialized model/solver state accessor set; native units/layout/lifecycle must match selected format. Host invokes before new run.

Returns

Zero on accepted restoration, otherwise implementation error/diagnostic. Nonfatal omissions may be copied from warnings(), but native/coupled archives can require exact identity. Interface supplies no model transaction; implementations must document candidate validation and partial-state behavior on error. Do not retain mutable model pointers or race solver/IO/model edits.

Implemented in openswmm::DefaultStateIOPlugin.

state()

virtual PluginState openswmm::IStateIOPlugin::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::DefaultStateIOPlugin.

validate()

virtual int openswmm::IStateIOPlugin::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::DefaultStateIOPlugin.

Here is the call graph for this function:

Here is the caller graph for this function:

warnings()

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

inlinevirtual

Copy nonfatal diagnostics from the implementation's last state I/O operation.

Returns

Independent message vector; base returns empty. Implementations document which operation clears messages, typically each read/write. Empty does not certify complete restore, exact model identity or absence of a fatal error. Serialize query with state I/O and copy diagnostics before invoking the next operation.

Reimplemented in openswmm::DefaultStateIOPlugin.

write_state()

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

pure virtual

Save supported runtime state at a caller-qualified accepted boundary.

Parameters

path	Borrowed destination path/location, potentially replaced by this call.
ctx	Read-only compatible host state/accessors in native units. Caller serializes all solver/source/thermal owners and plugin access for a coherent snapshot.

Returns

Zero on accepted save, otherwise implementation I/O/format code. Implementers should complete/close per-call resources and describe staging, companion files and flush/durability policy; this interface promises neither fsync nor global atomicity. Safe repetition and supported checkpoint/hot-start fidelity are format-specific; partial files may remain after 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