silk/raw_buffer

Profiles: aarch64-apple-darwin, aarch64-unknown-linux-gnu, aarch64-unknown-linux-gnu-no-libc, wasm32-unknown-unknown, x86_64-unknown-linux-gnu, x86_64-unknown-linux-gnu-no-libc.

Low-level typed views over owned allocations for implementing collections and storage actors.

When to use

Prefer silk.vector.Vector, silk.bytes.Bytes, or silk.box.Box in application code. Use these operations only when building a container that explicitly tracks capacity and which slots are initialized.

Details

copy supports overlapping ranges and behaves as though the moved elements passed through temporary storage. fill writes raw bytes and therefore operates only on RawBuffer<u8>.

Gotchas

These wrappers do not verify allocation capacity or initialization. The caller must prove that an allocation fits the recorded element count, every selected range is in bounds, and every read or view covers initialized elements. Releasing a raw buffer releases its allocation but does not discover and drop values still stored in it; a container must clear initialized Slot values before release.

Examples

Initialize and read a raw byte buffer

import silk.allocator { Allocator, OutOfMemoryError }

import silk.effect { Effect }

import silk.layout { Layout }

import silk.raw_buffer { RawBuffer }

import silk.u8

effect fn build() -> i32
! OutOfMemoryError {
  let mut allocator = Allocator.systemAllocatorProvider()
  let acquiring = Allocator.allocate(Layout.of<[u8; 3]>())
    |> Effect.provideMut<Allocator>(&mut allocator)
  let allocation = run acquiring
  unsafe {
    let mut buffer = RawBuffer.from<u8>(move allocation, 3)
    let filled = RawBuffer.fill(&mut buffer, 0, 3, u8.toU8(14))
    let values = RawBuffer.view<u8>(&buffer, 0, 3)
    return u8.toI32(values[0] + values[1] + values[2])
  }
  return 0
}

effect fn recover(error: OutOfMemoryError) -> i32 {
  return 0
}

pub fn main() -> i32 {
  return run Effect.catchAll(build(), recover)
}

Import as RawBuffer with import silk.raw_buffer { RawBuffer }.

Public declarations: 1.

RawBuffer

pub struct RawBuffer

The owner of the raw storage operations.

Details

This struct carries no data and is never constructed by the library. Every operation is an inherent member declared in impl RawBuffer, so import silk.raw_buffer { RawBuffer } is the one import that reaches RawBuffer.from(...) and the rest. It is unrelated to the builtin RawBuffer<T> type.

Associated function RawBuffer.from

pub fn from<T>(allocation: Allocation, count: usize) -> silk/core.RawBuffer<T>

Adopts an allocation as typed raw storage with the specified element capacity.

Gotchas

The caller must prove that the allocation has the size and alignment for count values of T.

Associated function RawBuffer.slot

pub fn slot<'storage, T>(buffer: &'storage mut silk/core.RawBuffer<T>, index: usize) -> silk/core.Slot<'storage, T>

Selects one raw storage slot after checking the buffer's recorded element count.

Gotchas

An index outside count traps. The caller must separately track whether the slot is initialized. The result retains exclusive access to the buffer until the slot is consumed. Lifetimes inside T remain separate from this storage access.

Associated function RawBuffer.count

pub fn count<T, 'life1>(buffer: &'life1 silk/core.RawBuffer<T>) -> usize

Returns the element capacity recorded by a raw buffer.

Associated function RawBuffer.read

pub fn read<T, 'life1>(buffer: &'life1 silk/core.RawBuffer<T>, index: usize) -> T

Copies one initialized element without changing its slot state.

Gotchas

index must be less than count, and the selected slot must contain an initialized T. A copied reference retains its original referent lifetime after the buffer is released.

Associated function RawBuffer.copy

pub fn copy<T, 'life1, 'life2>(destination: &'life1 mut silk/core.RawBuffer<T>, destinationOffset: usize, source: &'life2 [T], length: usize) -> ()

Moves a caller-proven initialized range into selected storage in one bulk transfer.

Details

Source and destination may overlap; the result is as if the elements travelled through an intermediate buffer.

Gotchas

The caller must prove that both selected ranges are in bounds. The source range must be initialized.

Associated function RawBuffer.fill

pub fn fill<'life0>(buffer: &'life0 mut silk/core.RawBuffer<u8>, offset: usize, length: usize, value: u8) -> ()

Initializes a selected byte range with one repeated byte value.

Gotchas

offset + length must not exceed count.

Associated function RawBuffer.view

pub fn view<T, 'life1>(buffer: &'life1 silk/core.RawBuffer<T>, offset: usize, length: usize) -> &'life1 [T]

Borrows a shared view of an initialized element range.

Gotchas

The selected range must be in bounds, and each selected slot must be initialized.

Associated function RawBuffer.viewMut

pub fn viewMut<T, 'life1>(buffer: &'life1 mut silk/core.RawBuffer<T>, offset: usize, length: usize) -> &'life1 mut [T]

Borrows an exclusive view of an initialized element range.

Gotchas

The selected range must be in bounds, and each selected slot must be initialized.