openswmm::IOThread Class Reference

Producer-consumer IO thread for writing simulation snapshots. More...

#include <IOThread.hpp>

Collaboration diagram for openswmm::IOThread:

Public Member Functions
	IOThread (PluginFactory &factory, std::size_t capacity=DEFAULT_QUEUE_CAPACITY)
	Construct (does NOT start the thread).
	~IOThread ()
	Stop/drain and join the native worker before releasing queue storage. Can block for plugin writes; destruction must not run from the worker itself.
	IOThread (const IOThread &)=delete
	Disable copying a live thread, queue and borrowed factory association.
IOThread &	operator= (const IOThread &)=delete
	Disable assignment of thread/queue ownership.
void	start ()
	Start the IO worker thread.
void	post (SimulationSnapshot snap)
	Post a snapshot to the write queue.
void	stop ()
	Signal the IO thread to finish and join it.
int	flush () const
bool	running () const noexcept
	True if the thread is running.
int	tasks_completed () const noexcept
	Number of tasks processed so far.
int	last_error () const noexcept
	Last error code from a plugin update (0 = no error).

Static Public Attributes
static constexpr std::size_t	DEFAULT_QUEUE_CAPACITY = 8
	Default maximum queue depth.

Detailed Description

Producer-consumer IO thread for writing simulation snapshots.

One IOThread per SWMMEngine instance. Shared with PluginFactory.

Constructor & Destructor Documentation

IOThread() [1/2]

openswmm::IOThread::IOThread ( PluginFactory & factory, std::size_t capacity = DEFAULT_QUEUE_CAPACITY )

explicit

Construct (does NOT start the thread).

Parameters

factory	Borrowed factory required to outlive this object and active worker. Plugins must accept snapshot delivery on the native IO thread (or caller thread for WebAssembly), and callbacks must not throw across the worker boundary.
capacity	Positive queued-task budget; zero causes native post() to wait until stop. Capacity excludes the one currently executing task. No validation/clamp occurs.

Here is the call graph for this function:

Here is the caller graph for this function:

~IOThread()

openswmm::IOThread::~IOThread

(

)

Stop/drain and join the native worker before releasing queue storage. Can block for plugin writes; destruction must not run from the worker itself.

Here is the call graph for this function:

IOThread() [2/2]

openswmm::IOThread::IOThread ( const IOThread & )

delete

Disable copying a live thread, queue and borrowed factory association.

Here is the call graph for this function:

Member Function Documentation

flush()

int openswmm::IOThread::flush

(

)

const

Wait for queued and currently executing writes. Call from the producer.

Returns

Sticky last nonzero plugin update code, or zero before any error. Native waits until queue empty and no write active; WebAssembly returns immediately. Call from the producer with a started worker for queued work; never from a plugin callback on that worker, which would wait for itself. Does not prevent other producers enqueueing more work after the idle observation.

Here is the call graph for this function:

last_error()

int openswmm::IOThread::last_error ( ) const

inlinenoexcept

Last error code from a plugin update (0 = no error).

Returns

Last nonzero update_all() return code, retained after later successes and across restart; zero means no error recorded yet, not proof all work completed.

Here is the caller graph for this function:

operator=()

IOThread & openswmm::IOThread::operator= ( const IOThread & )

delete

Disable assignment of thread/queue ownership.

Here is the call graph for this function:

post()

void openswmm::IOThread::post

(

SimulationSnapshot

snap

)

Post a snapshot to the write queue.

Native producers block at queue capacity; WebAssembly writes synchronously.

Parameters

snap

Snapshot taken by value and moved into queue ownership. Its owned vectors isolate ordinary simulation data, but any retained context pointer must satisfy plugin lifetime/access contracts. Native producers wait for space, or discard the request if stop is observed. WebAssembly calls update_all() directly without capacity waiting and requires serialized callers. Errors returned by plugins become sticky last_error(); no exception recovery is installed.

running()

bool openswmm::IOThread::running ( ) const

inlinenoexcept

True if the thread is running.

Returns

Relaxed atomic running flag; may still be false just after native start(), and is not a completion barrier for queue/plugin state.

start()

void openswmm::IOThread::start

(

)

Start the IO worker thread.

Precondition

Thread must not already be running.

Call once before posting, with lifecycle externally serialized. Native thread sets running asynchronously; repeated immediate start calls can race that flag and must not occur. After stop/join, restarting retains sequence/counters/ sticky error. WebAssembly only changes flags and uses synchronous writes. Native thread creation errors propagate.

stop()

void openswmm::IOThread::stop

(

)

Signal the IO thread to finish and join it.

Waits for all queued tasks to be processed, then joins the thread. Safe to call even if start() was never called.

Discards newly posted work after the stop flag, wakes blocked native producers, drains already queued tasks and joins the worker. Requires lifecycle serialization and a nonworker caller. If never started, an existing queue is not drained; intended usage starts before posting. WebAssembly simply clears running.

Here is the caller graph for this function:

tasks_completed()

int openswmm::IOThread::tasks_completed ( ) const

inlinenoexcept

Number of tasks processed so far.

Returns

Relaxed atomic count of attempted plugin-delivery tasks, including ones with nonzero return codes. Retained across restarts; caller avoids int overflow.

Member Data Documentation

DEFAULT_QUEUE_CAPACITY

std::size_t openswmm::IOThread::DEFAULT_QUEUE_CAPACITY = 8

staticconstexpr

Default maximum queue depth.

---

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

• /home/runner/work/openswmm.engine/openswmm.engine/src/engine/output/IOThread.hpp
• /home/runner/work/openswmm.engine/openswmm.engine/src/engine/output/IOThread.cpp