class

`SushiRuntime::DynamicGraph`

Composes regions that stream in and out into one plan, rebuilt only where it changed.

Declared in: include/SushiRuntime/api/graph/dynamic_graph.hpp

See also

include/SushiRuntime/api/graph/README.md

Public types

using SushiRuntime::API::DynamicGraph::RegionKey = std::uint64_t

Caller-chosen identity of a region (e.g.

a packed cell coordinate).

Public member functions

DynamicGraph(DynamicGraph &&other)=default

Takes over another graph's regions and pending structure.

Parameters

other: Graph to move from; left with no regions.

DynamicGraph(const DynamicGraph &)=delete

DynamicGraph & operator=(DynamicGraph &&other)=default

Replaces this graph's contents with another's.

Parameters

other: Graph to move from; left with no regions.

Returns

*this, now owning other's regions.

DynamicGraph & operator=(const DynamicGraph &)=delete

Region & region(RegionKey key)

Returns the region for key, creating it if absent, and marks it for rebuild.

Returns

A reference to the region, valid until the region is dropped.

See also

include/SushiRuntime/api/graph/README.md

bool has_region(RegionKey key) const noexcept

Returns whether a live region with key exists.

Parameters

key: Region identity to test.

Returns

True if the region is present.

const Region * find_region(RegionKey key) const noexcept

Returns the region for key without marking it for a rebuild.

Parameters

key: Region identity to look up.

Returns

The live region, or nullptr when no region has that key.

void drop(RegionKey key)

Removes the region for key from the live set; an absent key does nothing.

See also

include/SushiRuntime/api/graph/README.md

std::size_t region_count() const noexcept

Reports how many regions the graph currently holds.

Returns

Number of live regions, dropped ones excluded.

void set_profiling_requested(bool requested)

Requests or withdraws per-node device timing for this graph.

See also

include/SushiRuntime/api/graph/README.md

bool profiling_requested() const noexcept

Reports whether this graph currently requests profiling.

Returns

The last value set by set_profiling_requested(), or the runtime's RuntimeSettings::profiling default.

std::size_t size() const noexcept

Reports how much work the graph currently holds.

Returns

Total tasks recorded across all live regions.

std::size_t compile_count() const noexcept

Number of times the plan has been (re)composed.

Holds at 1 across a multi-step run that mutates nothing, and rises by one per commit (a run that follows at least one mutation), regardless of how many regions exist.

Returns

The composition count since this graph was created.

Core::RunReport run()

Runs one step, blocking until it completes.

Returns

A RunReport summarising the step.

Exceptions

Core::SushiException: on any synchronous or device error.

Core::RunReport run(std::size_t steps)

Runs steps successive steps, blocking until done.

Parameters

steps: Number of steps to run.

Returns

A RunReport aggregating the whole run.

Exceptions

Core::SushiException: on any synchronous or device error.

Core::RunReport & run(Core::RunReport &reuse)

Runs one step into a report the caller owns, without allocating.

Parameters

reuse: The report to overwrite; its previous contents are lost.

Exceptions

Core::SushiException: on any synchronous or device error.

Core::RunReport & run(std::size_t steps, Core::RunReport &reuse)

Runs steps successive steps into a report the caller owns.

Parameters

steps: Number of steps to run.
reuse: The report to overwrite; its previous contents are lost.

Returns

A reference to reuse.

Exceptions

Core::SushiException: on any synchronous or device error.

template <class Rep, class Period>
Core::RunReport run_for(std::chrono::duration< Rep, Period > budget)

Runs steps until a wall-clock budget elapses.

Parameters

budget: Wall-clock limit; at least one step always runs.

Returns

A RunReport aggregating the steps that ran.

Exceptions

Core::SushiException: on any synchronous or device error.

template <class Predicate>
Core::RunReport run_until(Predicate done)

Runs steps until done returns true.

Parameters

done: Stop condition checked before each step.

Returns

A RunReport aggregating the steps that ran.

Exceptions

Core::SushiException: on any synchronous or device error.

Core::Result< Core::RunReport, Core::Error > try_run(std::size_t steps) noexcept

Non-throwing multi-step run.

Parameters

steps: Number of steps to run.

Returns

The RunReport on success, or an Error on failure.

Core::Result< Core::RunReport *, Core::Error > try_run(Core::RunReport &reuse) noexcept

Non-throwing single run into a report the caller owns.

Parameters

reuse: The report to overwrite; its previous contents are lost.

Returns

A pointer to reuse on success, or an Error on failure.

Core::Result< Core::RunReport *, Core::Error > try_run(std::size_t steps, Core::RunReport &reuse) noexcept

Non-throwing multi-step run into a report the caller owns.

Parameters

steps: Number of steps to run.
reuse: The report to overwrite; its previous contents are lost.

Returns

A pointer to reuse on success, or an Error on failure.

void cancel()

Requests cancellation of an in-progress run, from any thread.

Mirrors Graph::cancel(): the active step drains without launching new kernels and the driver stops before the next step.

RunHandle< DynamicGraph > run_async()

Starts one step on the worker pool and returns without waiting for it.

Precondition

The returned handle does not outlive this graph.

Exceptions

Core::SushiException: If nothing is runnable, a handle was freed, the engine cannot run asynchronously, or a run is in progress.

See also

include/SushiRuntime/api/graph/README.md