Contents

class

SushiRuntime::API::Buffer

template <typename T>

Owns a typed block of unified shared memory that the runtime tracks by owning queue.

Declared in
include/SushiRuntime/api/data/buffer.hpp

Template parameters

T

Element type; must be trivially copyable for device use.

See also

include/SushiRuntime/api/data/README.md

Public types

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

Element type, exposed so generic code can recover it.

Public member functions

Buffer()=default

Constructs an empty handle that owns no memory.

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

Allocates count elements of USM pinned to one device and records the owner.

See also

include/SushiRuntime/api/data/README.md

Buffer(std::shared_ptr< Execution::RuntimeContext > ctx, Memory::Allocation allocation, std::size_t count, DeviceIndex device_index, Residency residency)

Wraps memory another component allocated and will release.

Parameters

allocation

Owns at least count * sizeof(T) bytes; released when this buffer is.

Exceptions

SushiException

With allocation_failed when count overflows its byte count, or allocation is smaller than it; allocation is released before the exception propagates.

~Buffer()

Frees the owned allocation, if any.

Buffer(const Buffer &)=delete
Buffer & operator=(const Buffer &)=delete
Buffer(Buffer &&other) noexcept

Takes ownership of other's allocation and liveness token, leaving other empty.

Warning

Do not move a handle after Graph::add() recorded it; the graph keeps its old address.

See also

include/SushiRuntime/api/data/README.md

Buffer & operator=(Buffer &&other) noexcept

Frees this handle's memory, then takes other's.

Parameters

other

Buffer to take the allocation from; left empty.

Returns

*this, now owning other's allocation.

T * data() const noexcept

Exposes the raw pointer a kernel captures.

Returns

Pointer to the first element, or null if the handle is empty.

std::size_t size() const noexcept

Reports the allocation's capacity.

Returns

Number of elements, not bytes.

bool empty() const noexcept

Tells whether this handle still owns memory.

Returns

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

DeviceIndex device_index() const noexcept

Reports which device queue the allocation is pinned to.

Returns

The device index the buffer was allocated on.

Residency residency() const noexcept

Reports where the allocation lives.

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 this buffer directly.

Returns

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

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

Returns element i for host code; valid only for shared or host USM.

Exceptions

SushiException

If the buffer is device-resident.

See also

include/SushiRuntime/api/data/README.md

span< T > host() const

Returns a host-addressable span over the whole buffer after one residency check.

Returns

A span over all elements, valid while this buffer lives.

Exceptions

SushiException

If the buffer is device-resident.

See also

include/SushiRuntime/api/data/README.md

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

Copies a sub-range out to a host vector through the owning queue and waits for it.

Parameters

range

Element window to read; count is clamped to the remainder.

See also

include/SushiRuntime/api/data/README.md

void write_range(ElementRange range, const T *src)

Copies a host range into a sub-range through the owning queue and waits for it.

Parameters

range

Element window to write; count is clamped to the remainder.

src

Host source of at least range.count elements.

See also

include/SushiRuntime/api/data/README.md

void * dependency_key() const noexcept

Returns the allocation's base address, which the dependency tracker uses as the key.

Returns

The base pointer as a void*, or nullptr when empty.

See also

include/SushiRuntime/api/data/README.md

Core::LivenessObserver liveness() const noexcept

Returns a weak observer that expires when this buffer is destroyed or moved from.

See also

include/SushiRuntime/api/data/README.md

Core::ResourceRegion region(ElementRange range) const noexcept

Names a sub-range of this buffer so that tasks on disjoint ranges are not serialized.

Parameters

range

Element window, in elements; count is clamped to the remainder.

See also

include/SushiRuntime/api/data/README.md