openswmm::IOutputPlugin Class Reference

Interface for output-writing plugins. More...

#include <IOutputPlugin.hpp>

Inheritance diagram for openswmm::IOutputPlugin:

Collaboration diagram for openswmm::IOutputPlugin:

Public Member Functions
virtual	~IOutputPlugin ()=default
virtual PluginState	state () const noexcept=0
	Query the current plugin state.
virtual int	initialize (const std::vector< std::string > &init_args, const class IPluginComponentInfo *info)=0
	Initialize the plugin from command-line-style arguments.
virtual int	validate (const SimulationContext &ctx)=0
	Validate plugin configuration against the simulation model.
virtual int	prepare (const SimulationContext &ctx)=0
	Open output file(s) and write headers.
virtual int	update (const SimulationSnapshot &snapshot)=0
	Write one output snapshot. Called from the IO thread.
virtual int	finalize (const SimulationContext &ctx)=0
	Flush and close output file(s). Called from main thread.
virtual const char *	last_error_message () const noexcept
	Get the last error message from this plugin instance.

Detailed Description

Interface for output-writing plugins.

Constructor & Destructor Documentation

~IOutputPlugin()

virtual openswmm::IOutputPlugin::~IOutputPlugin ( )

virtualdefault

Member Function Documentation

finalize()

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

pure virtual

Flush and close output file(s). Called from main thread.

Called after the simulation loop ends and the IO thread has been joined. All update() calls have completed at this point. Flush any write buffers and close file handles.

Parameters

ctx	Read-only simulation context (for final state / metadata).

Returns

0 on success; non-zero on error.

Postcondition

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

Implemented in openswmm::DefaultOutputPlugin.

initialize()

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

pure virtual

Initialize the plugin from command-line-style arguments.

Called once after the plugin library is loaded. Parse any configuration from init_args (e.g., output file path, format options). This is the place to open no files — that happens in prepare(). Use validate() to check config correctness.

Parameters

init_args	Tokenized arguments from the [PLUGINS] section line. e.g., {"file=results.h5", "compress=9"}
info	Back-pointer to the IPluginComponentInfo (for metadata).

Returns

0 on success; non-zero on error.

Postcondition

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

state() == PluginState::ERROR on failure.

Here is the caller graph for this function:

last_error_message()

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

inlinevirtualnoexcept

Get the last error message from this plugin instance.

Returns

Null-terminated error string, or empty string if no error.

Reimplemented in openswmm::DefaultOutputPlugin.

prepare()

virtual int openswmm::IOutputPlugin::prepare ( const SimulationContext &  ctx )

pure virtual

Open output file(s) and write headers.

Called after validate() succeeds, just before the simulation loop begins. Open file handles, allocate write buffers, and write any file headers.

Parameters

ctx	Read-only simulation context.

Returns

0 on success; non-zero on error.

Postcondition

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

Implemented in openswmm::DefaultOutputPlugin.

state()

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

pure virtualnoexcept

Query the current plugin state.

Returns

Current PluginState (thread-safe read).

Implemented in openswmm::DefaultOutputPlugin.

update()

virtual int openswmm::IOutputPlugin::update ( const SimulationSnapshot &  snapshot )

pure virtual

Write one output snapshot. Called from the IO thread.

Called at each output time step with a read-only snapshot of the simulation state. This method runs on the IO thread — it must NOT access the live SimulationContext.

Parameters

snapshot

Read-only simulation state at this output time step.

Returns

0 on success; non-zero on error (transitions to ERROR state).

Note

This may be called concurrently with the main simulation thread advancing the next timestep. Use only snapshot data.

Implemented in openswmm::DefaultOutputPlugin.

validate()

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

pure virtual

Validate plugin configuration against the simulation model.

Called after the input file is fully parsed and the model is loaded. Check that configured output paths are writable, that requested object IDs exist, etc.

Parameters

ctx	Read-only view of the simulation context (for model metadata).

Returns

0 on success; non-zero on error.

Postcondition

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

Implemented in openswmm::DefaultOutputPlugin.

---

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

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