#include <tracecontroller.h>

Inheritance diagram for openswmmvis::trace::TraceController:

Collaboration diagram for openswmmvis::trace::TraceController:

Signals
void	progress (int percent, const QString &stage)
	Publish queued native analysis progress.

void	busyChanged (bool busy)
	Announce worker dispatch/completion.

void	prepared (std::shared_ptr< openswmmvis::trace::Dataset > dataset)
	Publish available hydraulic averages after associating their package with run history.

void	resultReady (std::shared_ptr< openswmmvis::trace::Result > result)
	Publish a computed/restored result after refreshing open layers with matching ID.

void	failed (const QString &message)
	Explain rejected dispatch or uncancelled worker failure.

void	finished (const QString &runId, bool cancelled)
	Announce completed worker result delivery.

Public Member Functions
	TraceController (SWMMVisProjectWindow *p)
	Create a GUI-thread controller owned by a project and wire run-history/result delivery.

	~TraceController () override
	Request cancellation and wait for analysis work before releasing controller state.

bool	busy () const
	Inspect whether the current analysis future is running.

void	run (const QString &runId, const QStringList &nodes, int direction, const QString &destination, const Snapshot &snapshot, const QString &replaceId={})
	Request saved/cached or newly computed estimates for unique seed names.

void	recalculate (const QString &runId, const QStringList &extraNodes={}, int extraDirection=0, const Snapshot &snapshot={})

void	cancel ()
	Set the current shared cancellation flag without blocking the GUI.

bool	hasOpenLayer (const QString &resultId) const

SWMMResultsLayer *	outputForRun (const QString &runId)
	Resolve an open output host or create a saved-analysis output layer for the run.

TraceSublayer *	attachResult (std::shared_ptr< Result > result, bool travel)
	Show an existing matching estimate sublayer or attach a new one to its run host.

void	reconcileOutputRuns ()
	Move analysis sublayers to historical run hosts when a path starts representing a newer run.

bool	beforeOverwrite (const QString &outputPath, QString *error)
	Drain matching active analysis and retain prior raw output/report/model metadata when configured.

QString	defaultPackagePath (const QString &runId) const
	Resolve the package location for a registered run.

Static Public Member Functions
static TraceController *	forProject (SWMMVisProjectWindow *p, bool create=true)
	Find the direct project-owned trace controller, optionally creating it.

Constructor & Destructor Documentation

◆ TraceController()

openswmmvis::trace::TraceController::TraceController ( SWMMVisProjectWindow * p )

explicit

Create a GUI-thread controller owned by a project and wire run-history/result delivery.

Parameters

[in] p Non-null project owner with initialized stats registry.

Native trace/GDAL handles stay on workers; only owning value snapshots/results reach the GUI.

Here is the call graph for this function:

◆ ~TraceController()

openswmmvis::trace::TraceController::~TraceController ( )

override

Request cancellation and wait for analysis work before releasing controller state.

Can block while hashing/native calls drain; no engine/worker handles survive destruction.

Here is the call graph for this function:

Member Function Documentation

◆ attachResult()

TraceSublayer * openswmmvis::trace::TraceController::attachResult	(	std::shared_ptr< Result >	result,
		bool	travel
	)

Show an existing matching estimate sublayer or attach a new one to its run host.

Parameters

[in]	result	Non-null shared result with non-null dataset and registered run ID.
[in]	travel	True selects travel-time visualization, false trace fractions.

Returns: Borrowed output-owned trace sublayer, or null if no host resolves.

Existing matching ID/mode is made visible; new sublayers retain shared result ownership and mark the project changed.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ beforeOverwrite()

bool openswmmvis::trace::TraceController::beforeOverwrite	(	const QString &	outputPath,
		QString *	error
	)

Drain matching active analysis and retain prior raw output/report/model metadata when configured.

Parameters

[in]	outputPath	Original output path about to be replaced; active job match uses exact string equality.
[out]	error	Optional fingerprint/copy/publication diagnostic, unchanged on success.

Returns: True when overwrite can proceed under the retention preference, false on mismatched fingerprints or retention IO failure.

Can block waiting for worker cancellation, hashing, and file copies. Retained copies made before a later report/snapshot failure remain; it does not perform the output overwrite itself.

Here is the call graph for this function:

◆ busy()

bool openswmmvis::trace::TraceController::busy ( ) const

inline

Inspect whether the current analysis future is running.

Returns: Watcher running state, requiring GUI-thread access.

Here is the caller graph for this function:

◆ busyChanged

void openswmmvis::trace::TraceController::busyChanged ( bool busy )

signal

Announce worker dispatch/completion.

Parameters

[in] busy True before dispatch, false before completion attachment.

Here is the caller graph for this function:

◆ cancel()

void openswmmvis::trace::TraceController::cancel ( )

Set the current shared cancellation flag without blocking the GUI.

Native callbacks, hashing, and package row loops observe it cooperatively; already completed results/files can remain.

Here is the caller graph for this function:

◆ defaultPackagePath()

QString openswmmvis::trace::TraceController::defaultPackagePath ( const QString & runId ) const

Resolve the package location for a registered run.

Parameters

[in] runId Run identifier.

Returns: Existing registered package or analysis/runId/outputStem.analysis.gpkg beside the model/output directory; empty without project. No directories are created.

◆ failed

void openswmmvis::trace::TraceController::failed ( const QString & message )

signal

Explain rejected dispatch or uncancelled worker failure.

Parameters

[in] message Owning diagnostic text; cancellation completion suppresses failed().

Here is the caller graph for this function:

◆ finished

void openswmmvis::trace::TraceController::finished	(	const QString &	runId,
		bool	cancelled
	)

signal

Announce completed worker result delivery.

Parameters

[in]	runId	Exact source run ID.
[in]	cancelled	Whether cooperative cancellation was requested, even when partial work was retained.

Here is the caller graph for this function:

◆ forProject()

TraceController * openswmmvis::trace::TraceController::forProject	(	SWMMVisProjectWindow *	p,
		bool	create = `true`
	)

static

Find the direct project-owned trace controller, optionally creating it.

Parameters

[in]	p	Borrowed project owner; null returns null.
[in]	create	True constructs when absent, false performs lookup only.

Returns: Borrowed project-owned controller, or null for absent owner/controller.

◆ hasOpenLayer()

bool openswmmvis::trace::TraceController::hasOpenLayer ( const QString & resultId ) const

True when an analysis layer showing resultId is open in this project.

Parameters

[in] resultId Exact saved analysis ID.

Returns: True for any open trace sublayer with that ID, false without a project/canvas or match.

Here is the caller graph for this function:

◆ outputForRun()

SWMMResultsLayer * openswmmvis::trace::TraceController::outputForRun ( const QString & runId )

Resolve an open output host or create a saved-analysis output layer for the run.

Parameters

[in] runId Exact registered run ID.

Returns: Borrowed project/canvas-owned output layer, or null for no project/unknown run.

New historical hosts carry traceStoredRunId and are added to the canvas without requiring a readable raw output handle.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ prepared

void openswmmvis::trace::TraceController::prepared ( std::shared_ptr< openswmmvis::trace::Dataset > dataset )

signal

Publish available hydraulic averages after associating their package with run history.

Parameters

[in] dataset Shared owning dataset with SI values and captured topology; no native handles.

Here is the caller graph for this function:

◆ progress

void openswmmvis::trace::TraceController::progress	(	int	percent,
		const QString &	stage
	)

signal

Publish queued native analysis progress.

Parameters

[in]	percent	Integer native fractional progress times 100, emitted when it changes.
[in]	stage	Native stage label copied to owning text.

Here is the caller graph for this function:

◆ recalculate()

void openswmmvis::trace::TraceController::recalculate	(	const QString &	runId,
		const QStringList &	extraNodes = `{}`,
		int	extraDirection = `0`,
		const Snapshot &	snapshot = `{}`
	)

Discard the run's saved averages and estimates, rescan its current output, and recompute every saved estimate (same ids, so open layers refresh in place) plus extraNodes in extraDirection.

Parameters

[in]	runId	Exact analyzable run ID.
[in]	extraNodes	Additional seed names deduplicated by exact text.
[in]	extraDirection	Direction for additional requests, zero downstream or one upstream.
[in]	snapshot	Owning fallback model snapshot when no captured snapshot exists.

Removes the current package/companions before dispatch, preserving saved IDs/styles as requests. A subsequent failure may leave the old package unavailable; no package rollback occurs. Historical runs require retained raw output for recalculation.

◆ reconcileOutputRuns()

void openswmmvis::trace::TraceController::reconcileOutputRuns ( )

Move analysis sublayers to historical run hosts when a path starts representing a newer run.

GUI-thread operation guarded against recursion; removes old scene items before transferring sublayer ownership.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ resultReady

void openswmmvis::trace::TraceController::resultReady ( std::shared_ptr< openswmmvis::trace::Result > result )

signal

Publish a computed/restored result after refreshing open layers with matching ID.

Parameters

[in] result Shared owning estimate; saved indicates package persistence success, which may be false after later IO failure.

Here is the caller graph for this function:

◆ run()

void openswmmvis::trace::TraceController::run	(	const QString &	runId,
		const QStringList &	nodes,
		int	direction,
		const QString &	destination,
		const Snapshot &	snapshot,
		const QString &	replaceId = `{}`
	)

Request saved/cached or newly computed estimates for unique seed names.

Parameters

[in]	runId	Exact registered analyzable run ID.
[in]	nodes	Seed node IDs, deduplicated by exact text in input order.
[in]	direction	Native trace direction, zero downstream or one upstream.
[in]	destination	Package path, empty to use defaultPackagePath(); an existing registered package fixes the destination.
[in]	snapshot	Owning fallback model snapshot used only when the run lacks its captured snapshot and no package exists.
[in]	replaceId	Optional saved analysis ID to preserve; requires exactly one unique requested seed.

Dispatch errors emit failed(). Computation uses worker-local handles; completed estimates survive a later save failure in resultReady() with saved=false.

Here is the caller graph for this function:

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

/home/runner/work/openswmm.gui/openswmm.gui/include/output/tracecontroller.h
/home/runner/work/openswmm.gui/openswmm.gui/src/output/tracecontroller.cpp

Signals

Public Member Functions

Static Public Member Functions

Constructor & Destructor Documentation

◆ TraceController()

◆ ~TraceController()

Member Function Documentation

◆ attachResult()

◆ beforeOverwrite()

◆ busy()

◆ busyChanged

◆ cancel()

◆ defaultPackagePath()

◆ failed

◆ finished

◆ forProject()

◆ hasOpenLayer()

◆ outputForRun()

◆ prepared

◆ progress

◆ recalculate()

◆ reconcileOutputRuns()

◆ resultReady

◆ run()