The residency surface
A small set of forms covers the whole surface:
| Form | Meaning | Cost |
|---|---|---|
gpu let g = … | Immutable device buffer | Upload (deferred to first capture) |
gpu var g = … | Mutable device buffer | Upload (deferred to first capture) |
forall i in 0..n | Launch a kernel over indices 0..n | Kernel launch (or a CPU loop — see below) |
let h = g | Copy a device buffer back to the host | Fence + readback |
gpu let b = g | Move a device buffer to a new binding | Free — the device handle transfers, no copy |
g.slice(a..b) | Partial readback of [a, b) | Fence + readback |
g.reduce(init, op) | On-device tree reduction to a scalar | Kernel launch |
What may be device-resident
A type can be bound with gpu only if it implements the Accelerable capability trait.
The standard library ships impls for Array<T, N> and List<T> over the
accelerable scalars — int, i32, i64, u32, u64,
f16, f32, f64, bool — plus the
vector types, Tensor, and user structs declared
implements Accelerable. String, Map, Set, and function
values are not accelerable. Binding one with gpu is a compile error that names the missing
trait.
No silent promotion. A host Array never becomes device-resident because a
kernel wants it. You write gpu let at the binding, and the upload is visible at that line.