silk/raw_buffer

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 are unchecked. 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 }

import silk.allocator {Allocator}

import silk.effect { Effect }

import silk.layout as Layout

import silk.raw_buffer as RawBuffer

import silk.u8 as u8

effect fn build() -> i32
! Allocator.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: Allocator.OutOfMemoryError) -> i32 {
  return 0
}

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

Import as RawBuffer with import silk.raw_buffer.

Public declarations: 8.

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.

slot

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

Selects one raw storage slot without checking bounds or initialization.

Gotchas

index must be less than count. The caller must separately track whether the slot is initialized.

count

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

Returns the element capacity recorded by a raw buffer.

read

pub fn read<T>(buffer: &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.

copy

pub fn copy<T>(destination: &mut silk/core.RawBuffer<T>, destinationOffset: usize, source: &[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.

fill

pub fn fill(buffer: &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.

view

pub fn view<T>(buffer: &silk/core.RawBuffer<T>, offset: usize, length: usize) -> &[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.

viewMut

pub fn viewMut<T>(buffer: &mut silk/core.RawBuffer<T>, offset: usize, length: usize) -> &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.