std::buf
std/src/buf.mo
Standard library: Buf E -- a flat, unboxed, element-typed buffer.
This is the polymorphic generalisation of ByteBuf, and the two share
ONE heap kind (BufObj, MONAD_BUF_TAG in runtime/src/runtime_core.c):
an element kind, an element count, and a 64-byte-aligned atomic payload.
ByteBuf is the u8 case; Buf F32 is the case that matters here.
Why it is not Array
An Array A IS its backing constructor: one boxed 8-byte word per
element, from a GC_malloc'd block the collector scans for pointers
(std/src/array.mo's representation note). That is the right shape for
a general-purpose sequence and the wrong one for a kernel argument: an
F32 would occupy eight bytes instead of four, the collector would scan
float bit patterns as candidate addresses, and the address of the first
element would not be 64-byte aligned.
A Buf E is the other shape -- packed, typed, aligned, and invisible to
the collector -- so Buf F32 genuinely IS memref<Nxf32> and a kernel
can take its payload address as a bare pointer with no conversion
(plans/bootstrapping/mlir-codegen.md Decision 3).
What is safe and what is not
Everything in this module except data_ptr is total: every index is
bounds-checked and an out-of-range access reads or writes nothing,
returning a zero element or leaving the buffer unchanged. That is
deliberately the same clamp the interpreter applies (core_native.rs),
so the two backends agree even on a wrong index -- which is the whole
point of having two.
data_ptr is the one unsafe primitive, and it is not pub. Raw
memory is reached only through with_ptr, which is the single place a
kernel launch can obtain an address; an escape hatch left open in a
dependently-typed language is a permanent hole. with_ptr needs a
kernel call to be useful, so the whole launch story arrives at once in
plans/bootstrapping/mlir-codegen.md Phase 2 -- until then data_ptr
is exercised only by the test that proves it returns the payload.
Element kinds, and the F32/U8 asymmetry
I64, F64 and F32 buffers are eight, eight and four bytes per
element; I32 and U8 are four and one. get_f32/set_f32 store the
single-precision value in the payload and move it through the runtime's
F32 boundary convention (an f32-rounded value held in a double), so
what a kernel reads from a Buf F32 is exactly what Monad wrote.
U8 is spelled as its own type here rather than reusing ByteBuf: one
heap kind, two surfaces, no conversion between them. Converting is
Buf.copy_into within a kind, or to_list/from_list across.
Values are opaque like ByteBuf and FdStream: never pattern-match,
compare or print one.
pub type Buf E {
buf_witness
}A flat buffer of len elements, each of the kind its constructor
chose. Built only by this module's new_* natives: the witness is
unreferenceable (#[opaque]), so there is no way to forge one.
pub def Buf.new_i64 (n : I64) : IO (Buf I64)n zeroed I64 elements.
pub def Buf.new_f64 (n : I64) : IO (Buf F64)n zeroed F64 elements.
pub def Buf.new_f32 (n : I64) : IO (Buf F32)n zeroed F32 elements -- four bytes each, so this is the buffer a
memref<Nxf32> kernel takes.
pub def Buf.new_i32 (n : I64) : IO (Buf I32)n zeroed I32 elements.
pub def Buf.new_u8 (n : I64) : IO (Buf U8)n zeroed bytes.
pub def Buf.length (b : Shared (Buf E)) : I64How many elements the buffer holds (its element count, not its byte
size -- test_u8_length_is_element_count_not_bytes pins that).
pub def Buf.elem_kind (b : Shared (Buf E)) : I64pub def Buf.get_i64 (b : Shared (Buf I64)) (i : I64) : I64pub def Buf.get_f64 (b : Shared (Buf F64)) (i : I64) : F64pub def Buf.get_f32 (b : Shared (Buf F32)) (i : I64) : F32pub def Buf.get_i32 (b : Shared (Buf I32)) (i : I64) : I32pub def Buf.get_u8 (b : Shared (Buf U8)) (i : I64) : U8pub def Buf.set_i64 (b : Buf I64) (i : I64) (v : I64) : IO Unitpub def Buf.set_f64 (b : Buf F64) (i : I64) (v : F64) : IO Unitpub def Buf.set_f32 (b : Buf F32) (i : I64) (v : F32) : IO Unitpub def Buf.set_i32 (b : Buf I32) (i : I64) (v : I32) : IO Unitpub def Buf.set_u8 (b : Buf U8) (i : I64) (v : U8) : IO Unitpub def Buf.copy_into (dst : Buf E) (offset : I64) (src : Buf E) : IO (Buf E)Copy every element of src into dst starting at element offset.
One memmove, CLAMPED to dst's remaining length -- this never grows
dst, and an offset outside [0, Buf.length dst] copies nothing.
Same element kind only; the runtime rejects a mismatch rather than
reinterpreting bytes.
Consumes and returns dst (view-types P2's shape, as
ByteBuf.copy_into): the caller threads the returned handle on rather
than mentioning the input twice, which is what the affine rule wants.
pub def Buf.to_list_f32 (b : Buf F32) : IO (List F32)Buf F32 -> List F32, one element per index. The buffer travels as
a Shared handle for the same affine reason from_list_f32 gives:
every read is a separate use of the same buffer.
pub def Buf.with_ptr {A : Type} (b : Buf E) (f : Ptr -> A) : ARun f with the buffer's payload address, for a kernel call or a C
FFI function that writes into it. The address is valid only for the
duration of f, and only as long as b is live -- Buf is affine
and not Copy, so the type system keeps the buffer alive across the
call.
This is the scoped form the unsafe primitive is meant to be used
through; data_ptr itself stays private so there is no way to obtain
an address that outlives its scope by accident.