openswmm::twoD::EngineSourceResultStream Class Reference

#include <EngineSourceResultStream.hpp>

Collaboration diagram for openswmm::twoD::EngineSourceResultStream:

Classes
struct	Cursor
struct	Frame
struct	PreparedRestore

Public Types
enum class	Kind : uint32_t {   Initial ,   SourceInterval ,   EngineStep ,   CouplingBarrier ,   PrescriptionUpdate ,   Checkpoint }

Public Member Functions
	EngineSourceResultStream ()=default
	Construct an unattached recorder with empty path/cursor and zero accepted clocks.
	EngineSourceResultStream (const EngineSourceResultStream &)=delete
EngineSourceResultStream &	operator= (const EngineSourceResultStream &)=delete
const Cursor &	cursor () const
	Borrow the recorder's committed prefix identity, byte/frame counts and rolling fingerprint.
const Frame &	latest () const
	Borrow the recorder's most recently committed frame.
const std::string &	path () const
	Borrow the recorder's attached companion filesystem path.
bool	detailed () const
	Test whether fine source intervals are included on their independent time axis.
bool	hasPendingCapture () const
	Read whether an engine-level capture remains pending after its physical anchor was obtained.
const std::string &	lastError () const
	Borrow the recorder's last stored capture error text.
std::size_t	largestFrameBytes () const
	Read the largest committed encoded frame payload size seen by this recorder.

Static Public Member Functions
static std::string	visit (const std::string &, const Cursor &, const std::function< void(const Frame &)> &)
	Visits a verified saved prefix one frame at a time, without retaining it.

Friends
class	openswmm::SWMMEngine
class	ExplicitInertialSolver

Detailed Description

Internal, same-platform full-history companion. Unlike qualification tables, retention is independent of duration. Caller owns it through engine close. A failed capture can follow accepted physics/prescriptions; inspect status and settle recording before advancing. It does not roll physics back. Not a public result format, security hash, or power-loss transaction.

Member Enumeration Documentation

Kind

enum class openswmm::twoD::EngineSourceResultStream::Kind : uint32_t

strong

Enumerator
Initial
SourceInterval
EngineStep
CouplingBarrier
PrescriptionUpdate
Checkpoint

Constructor & Destructor Documentation

EngineSourceResultStream() [1/2]

openswmm::twoD::EngineSourceResultStream::EngineSourceResultStream ( )

default

Construct an unattached recorder with empty path/cursor and zero accepted clocks.

Note

No file is opened or engine registered. The owning engine initializes it at its initial boundary and retains the recorder through engine close; copying is intentionally disabled.

Here is the caller graph for this function:

EngineSourceResultStream() [2/2]

openswmm::twoD::EngineSourceResultStream::EngineSourceResultStream ( const EngineSourceResultStream & )

delete

Here is the call graph for this function:

Member Function Documentation

cursor()

const Cursor & openswmm::twoD::EngineSourceResultStream::cursor ( ) const

inline

Borrow the recorder's committed prefix identity, byte/frame counts and rolling fingerprint.

Returns

Const recorder-owned reference; invalidated by recorder replacement/destruction and possibly subsequent capture/adoption. No copy, file verification or synchronization occurs. Keep the recorder stable while reading. lastError text is cleared by successful engine capture/ adoption; a successful fine source capture alone does not clear a previously stored error.

Here is the caller graph for this function:

detailed()

bool openswmm::twoD::EngineSourceResultStream::detailed ( ) const

inline

Test whether fine source intervals are included on their independent time axis.

Returns

Stored profile flag, fixed by initialization. Does not validate pending capture or file prefix state; false includes the default unattached recorder.

Here is the caller graph for this function:

hasPendingCapture()

bool openswmm::twoD::EngineSourceResultStream::hasPendingCapture ( ) const

inline

Read whether an engine-level capture remains pending after its physical anchor was obtained.

Returns

Stored pending_capture_ flag. A failed early engine-anchor check or fine source-interval capture need not set it, so false alone does not prove successful/healthy recording; inspect returned status and lastError(). Successful engine capture or restore adoption clears it.

largestFrameBytes()

std::size_t openswmm::twoD::EngineSourceResultStream::largestFrameBytes ( ) const

inline

Read the largest committed encoded frame payload size seen by this recorder.

Returns

Largest encoded frame payload seen by this recorder, in bytes, initially zero. It is not cumulative file size and excludes framing/header bytes and external physical/output images. No scan, copy or allocation occurs.

lastError()

const std::string & openswmm::twoD::EngineSourceResultStream::lastError ( ) const

inline

Borrow the recorder's last stored capture error text.

Returns

Const recorder-owned reference; invalidated by recorder replacement/destruction and possibly subsequent capture/adoption. No copy, file verification or synchronization occurs. Keep the recorder stable while reading. lastError text is cleared by successful engine capture/ adoption; a successful fine source capture alone does not clear a previously stored error.

Note

Successful engine capture/adopt clears this text. A successful fine source-interval capture does not clear an earlier stored error. Use the immediate operation's returned status together with hasPendingCapture() rather than treating empty text alone as recorder health.

latest()

const Frame & openswmm::twoD::EngineSourceResultStream::latest ( ) const

inline

Borrow the recorder's most recently committed frame.

Returns

Const recorder-owned reference; invalidated by recorder replacement/destruction and possibly subsequent capture/adoption. No copy, file verification or synchronization occurs. Keep the recorder stable while reading. lastError text is cleared by successful engine capture/ adoption; a successful fine source capture alone does not clear a previously stored error.

operator=()

EngineSourceResultStream & openswmm::twoD::EngineSourceResultStream::operator= ( const EngineSourceResultStream & )

delete

Here is the call graph for this function:

path()

const std::string & openswmm::twoD::EngineSourceResultStream::path ( ) const

inline

Borrow the recorder's attached companion filesystem path.

Returns

Const recorder-owned reference; invalidated by recorder replacement/destruction and possibly subsequent capture/adoption. No copy, file verification or synchronization occurs. Keep the recorder stable while reading. lastError text is cleared by successful engine capture/ adoption; a successful fine source capture alone does not clear a previously stored error.

Here is the caller graph for this function:

visit()

std::string openswmm::twoD::EngineSourceResultStream::visit ( const std::string & path, const Cursor & cursor, const std::function< void(const Frame &)> & visitor )

static

Visits a verified saved prefix one frame at a time, without retaining it.

Visit and verify a committed saved prefix without retaining complete history.

Arguments in order Stable saved companion path, expected committed Cursor, and an

optional synchronous read-only frame callback. Callback references live only during the visit and must not be retained; an empty callback still verifies the full prefix. The file must not be replaced/modified during scanning.

Returns

Empty after full identity/frame-chain/schema/clock/cursor verification; caught standard exception text on file, validation or callback failure. Earlier callback effects remain even if a later frame/final-cursor check fails. Extra file bytes beyond cursor.bytes are ignored.

Note

Reads/retains one bounded frame at a time, not complete result history. No file mutation, engine restoration, synchronization or cryptographic authenticity guarantee is provided.

Parameters

[in]	path	Stable non-symlink regular source companion file, at least cursor.bytes long.
[in]	cursor	Exact saved identity, byte/frame count and rolling fingerprint.
[in]	visitor	Optional synchronous callback for each verified decoded frame; references expire at callback return. Callback effects survive later verification failure and must not mutate the file.

Returns

Empty after complete prefix verification, or file/schema/clock/cursor/callback standard exception text. Empty callback still scans; extra bytes beyond the cursor are ignored.

Note

No file mutation, hydraulic restoration, synchronization or cryptographic authenticity check. Caller serializes source access; nonstandard callback exceptions can propagate.

Here is the call graph for this function:

Friends And Related Symbol Documentation

ExplicitInertialSolver

friend class ExplicitInertialSolver

friend

openswmm::SWMMEngine

friend class openswmm::SWMMEngine

friend

---

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

• /home/runner/work/openswmm.engine/openswmm.engine/src/engine/2d/subsurface/EngineSourceResultStream.hpp
• /home/runner/work/openswmm.engine/openswmm.engine/src/engine/2d/subsurface/EngineSourceResultStream.cpp