openswmm::IReportPlugin Class Reference

Interface for report-writing plugins. More...

#include <IReportPlugin.hpp>

Inheritance diagram for openswmm::IReportPlugin:

Collaboration diagram for openswmm::IReportPlugin:

Public Member Functions
virtual	~IReportPlugin ()=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 class 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	prepare (const SimulationContext &ctx)=0
	Allocate/open model-dependent output resources before asynchronous updates.
virtual int	update (const SimulationSnapshot &snapshot)
	Consume one output-time snapshot on the serialized I/O worker.
virtual int	write_summary (const SimulationContext &ctx)=0
	Write final accumulated/model summary after asynchronous updates finish.
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 report-writing plugins.

Constructor & Destructor Documentation

~IReportPlugin()

virtual openswmm::IReportPlugin::~IReportPlugin ( )

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::IReportPlugin::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::DefaultReportPlugin, and openswmm::gpkg::GeoPackageReportPlugin.

initialize()

virtual int openswmm::IReportPlugin::initialize ( const std::vector< std::string > & init_args, const class 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.

Here is the call graph for this function:

Here is the caller graph for this function:

last_error_message()

virtual const char * openswmm::IReportPlugin::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::DefaultReportPlugin, and openswmm::gpkg::GeoPackageReportPlugin.

prepare()

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

pure virtual

Allocate/open model-dependent output resources before asynchronous updates.

Parameters

ctx	Borrowed compatible initialized model in native context units; copy required immutable metadata. Does not transfer model ownership.

Returns

Zero after successful headers/resource setup and PREPARED transition, otherwise implementation error. Factory calls only VALIDATED instances. Resource creation may leave partial files/handles on failure; implementation must clean up through its documented finalize/destructor path. Owning simulation thread only.

Implemented in openswmm::DefaultReportPlugin, and openswmm::gpkg::GeoPackageReportPlugin.

Here is the call graph for this function:

Here is the caller graph for this function:

state()

virtual PluginState openswmm::IReportPlugin::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::DefaultReportPlugin, and openswmm::gpkg::GeoPackageReportPlugin.

update()

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

inlinevirtual

Consume one output-time snapshot on the serialized I/O worker.

Parameters

snapshot

Borrowed read-only row, valid only during callback. Numeric vectors are snapshot-owned, while ID/unit/species pointers borrow host metadata which must remain immutable/alive until I/O drains. One-dimensional hydraulic reports use project display units; 2D/snow fields retain documented SI units. Copy any retained data and handle optional empty vectors/null metadata. Never access live context.

Returns

Zero on accepted processing, otherwise implementation error. Factory invokes PREPARED/UPDATING instances and aggregates codes; implementation owns state/error transition and partial-write handling. Main simulation may advance concurrently. Base report update is an unconditional no-op returning zero. Exceptions are not caught by factory; worker handles its own failure policy.

Reimplemented in openswmm::DefaultReportPlugin, and openswmm::gpkg::GeoPackageReportPlugin.

Here is the call graph for this function:

Here is the caller graph for this function:

validate()

virtual int openswmm::IReportPlugin::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::DefaultReportPlugin, and openswmm::gpkg::GeoPackageReportPlugin.

Here is the call graph for this function:

Here is the caller graph for this function:

write_summary()

virtual int openswmm::IReportPlugin::write_summary ( const SimulationContext & ctx )

pure virtual

Write final accumulated/model summary after asynchronous updates finish.

Parameters

ctx	Borrowed final native-unit statistics/context for this call. Snapshot fields use separately documented display/SI units; do not mix without conversion.

Returns

Zero on success, otherwise implementation error. Engine report phase follows end/finalize; implementations must support this ordering and reopen/use appropriate resources if finalize closed them. Factory invokes all reports without state gate. Base interface does not validate report lifecycle, perform conversions or roll back partial files. Owning simulation thread only; no outstanding update calls.

Implemented in openswmm::DefaultReportPlugin, and openswmm::gpkg::GeoPackageReportPlugin.

---

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

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