std::bytebuf

std/src/bytebuf.mo

Standard library: ByteBuf -- a flat byte buffer the C FFI can address (SSL_read/SSL_write in motes/tls take a void* plus a length; nothing else in std/ exposes one).

A ByteBuf records its length: length is the byte count it was created with (or later truncated to), and to_list's len is clamped to that, so an over-large len cannot read past the allocation. truncate a buffer to SSL_read's return to keep only what actually came back. Values are opaque like FdStream (std/stream.mo): never pattern-match, compare or print one.

Compiled, a ByteBuf is the heap kind plans/bootstrapping/ mlir-codegen.md's Buf E generalises ("a fourth heap kind"): a block carrying its element kind (u8), its length, and a 64-byte-aligned atomic payload. ByteBuf is that kind's u8 case, so the buffer an FFI function sees is already the memory a kernel memref would. free is a deliberate no-op there -- Boehm reclaims a forgotten buffer, and a real free on a word another live value holds would be a use-after-free.

The two backends hold different words and values never cross between them. Interpreted, it is a registry id (the Fiber/Scope handle convention, core_native.rs) whose length is its Vec's, and free really drops it. ptr hands out the raw address and so exists only compiled -- under the interpreter forcing it fails unknown native: bytebuf_ptr.

typeByteBuf#
pub type ByteBuf {
    bytebuf
}
defByteBuf.alloc#
pub def ByteBuf.alloc (n : I64) : IO ByteBuf

Allocate n zeroed bytes.

defByteBuf.ptr#
pub def ByteBuf.ptr (b : ByteBuf) : Ptr

The raw address of the payload, for FFI functions that write into or read out of it. Compiled backend only (see the module doc).

defByteBuf.take_ptr#
pub def ByteBuf.take_ptr (b : ByteBuf) : Ptr

Read the pointer-sized word at the start of the buffer, for a C function that returns a handle through an out-parameter. The buffer must hold at least 8 bytes; a shorter one yields the NULL word instead of reading past its payload. Compiled backend only, like ptr: the interpreter has no raw addresses.

This is the typed alternative to a general load(ptr) helper. The argument is a ByteBuf, so no arbitrary address can be supplied, and the runtime checks the buffer's kind and length.

defByteBuf.length#
pub def ByteBuf.length (b : ByteBuf) : I64

How many bytes the buffer holds: its creation size, or what truncate cut it to.

defByteBuf.of_list#
pub def ByteBuf.of_list (xs : List U8) : IO ByteBuf

Copy xs into a fresh buffer.

defByteBuf.to_list#
pub def ByteBuf.to_list (b : ByteBuf) (len : I64) : IO (List U8)

The first len bytes of the buffer as a list, clamped to the buffer's own length.

defByteBuf.free#
pub def ByteBuf.free (b : ByteBuf) : IO Unit

Release the buffer (a no-op under the compiled GC backend).

defByteBuf.to_string#
pub def ByteBuf.to_string (b : ByteBuf) (len : I64) : IO String

The first len bytes of the buffer as a String, clamped to the buffer's own length exactly as to_list is -- one copy, where String.from_list (ByteBuf.to_list ...) would build and walk a cons cell per byte. Bytes that are not valid UTF-8 come back lossily (U+FFFD) under the interpreter, whose String must be UTF-8; the compiled backend copies them verbatim.

defByteBuf.of_string#
pub def ByteBuf.of_string (s : String) : IO ByteBuf

Copy s's bytes into a fresh buffer -- of_list's shape, from text.

defByteBuf.truncate#
pub def ByteBuf.truncate (b : ByteBuf) (n : I64) : IO Unit

Shrink the recorded length to n, keeping the first n bytes; n is clamped to [0, length], so this never grows a buffer. The allocation itself is unchanged -- the bytes past n just stop being part of it.

defByteBuf.copy_into#
pub def ByteBuf.copy_into (dst : ByteBuf) (offset : I64) (src : ByteBuf) : IO ByteBuf

Copy all of src into dst starting at byte offset -- one memmove. Clamped to dst's length, so this never grows dst; an offset outside [0, length dst] copies nothing. Gathering chunks into one buffer this way is how IO.read_file decodes a file ONCE rather than chunk by chunk (a character split across two chunks would otherwise decode as U+FFFD under the interpreter).

Consumes and returns dst (view-types P2's shape, applied to the mutable buffer): the caller threads the returned handle on rather than mentioning the input twice.