class

`SushiRuntime::API::State`

template <typename T>

Owns two equally sized buffers whose roles the runtime swaps after each step.

Declared in: include/SushiRuntime/api/data/state.hpp

Template parameters

T: Element type; must be trivially copyable for device use.

Public types

using SushiRuntime::API::State< T >::value_type = T

Element type, exposed so generic code can recover it.

Public member functions

State()=default

Constructs an empty state that owns no memory.

State(std::shared_ptr< Execution::RuntimeContext > ctx, std::size_t count, DeviceIndex device_index=DeviceIndex{0}, Residency residency=Residency::Shared)

Allocates both buffers of count elements on one device.

See also

include/SushiRuntime/api/data/README.md

T * current() const noexcept

Exposes the field a step kernel reads from.

Returns

Pointer to the first element of the current field.

T * next() const noexcept

Exposes the field a step kernel writes into.

Returns

Pointer to the first element of the next field.

std::size_t size() const noexcept

Reports the capacity of the pair.

Returns

Number of elements in each field; both are the same size.

bool empty() const noexcept

Tells whether this State still owns memory.

Returns

True if it owns no allocation, e.g. after being moved from.

void * read_key() const noexcept

Identifies the region a task reading this State depends on.

Returns

The current field's base address, as used by the tracker.

void * write_key() const noexcept

Identifies the region a task writing this State depends on.

Returns

The next field's base address, as used by the tracker.

Core::LivenessObserver liveness() const noexcept

Returns a weak observer of the current field's allocation, which stands for the State.

See also

include/SushiRuntime/api/data/README.md

T & operator[](std::size_t i) const

Returns element i of the current field for host code.

Exceptions

SushiException: If the State is device-resident.

span< T > host() const

Returns a host-addressable span over the current field after one residency check.

Exceptions

SushiException: If the State is device-resident.

Residency residency() const noexcept

Reports where both fields live.

Returns

Residency::Shared for managed USM, Residency::Device for device-resident memory, Residency::Host for pinned host USM.

bool host_accessible() const noexcept

Tells whether the host may index the current field directly.

Returns

True for shared or host USM; false for device-resident memory, which must go through read_range()/write_range().

std::vector< T > read_range(ElementRange range) const

Copies a sub-range of the current field out to a host vector.

Parameters

range: Element window to read; count is clamped to the field size.

void write_range(ElementRange range, const T *src)

Copies a host range into a sub-range of the current field.

Parameters

range: Element window to write; count is clamped to the field size.
src: Host source of at least range.count elements.

void advance() noexcept

Swaps current and next so the just-written state becomes current.

The runtime calls this once per step.