silk/pointer

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.

Raw data pointers with explicit nullability, element extent, and minimum alignment.

When to use

Use these operations for foreign calls and storage that native code owns.

Details

A pointer is Copy. It holds no ownership or loan and keeps no storage alive. *const T and *mut T are non-null single-element pointers. [*] denotes many elements. A ? prefix permits null. A many-element pointer carries no length.

Gotchas

A non-null address does not prove that storage is live or initialized. Each unsafe memory operation requires the caller to prove its storage contract.

Import as Pointer with import silk.pointer { Pointer }.

Public declarations: 1.

Pointer

pub struct Pointer

The operations for data pointers, which hold no ownership or loan.

Associated function Pointer.bytes

pub unsafe fn bytes<T>(pointer: ?*const T) -> ?[*]const u8

Projects a typed raw pointer as a readonly byte address without reading storage.

Gotchas

The result preserves null and the address but grants no ownership or readable extent. Every later access must independently address initialized readable bytes. This permits inspection of a valid prefix of a variable-sized external record without loading the nominal record. It does not keep the allocation alive.

Associated function Pointer.address

pub fn address<T>(pointer: ?*const T) -> usize

Returns the unsigned numeric address of a raw data pointer.

Details

Null has address zero. Observation does not read memory or keep storage alive. The result has the selected target's pointer width and cannot reconstruct a pointer.

Associated function Pointer.addressMany

pub fn addressMany<T>(pointer: ?[*]const T) -> usize

Returns the unsigned numeric address of a many-element data pointer.

Details

Null has address zero. Observation does not read memory or keep storage alive. The result has the selected target's pointer width and cannot reconstruct a pointer.

Associated function Pointer.null

pub fn null<T>() -> ?*mut T

Returns a null single-element pointer.

Associated function Pointer.isNull

pub fn isNull<T>(pointer: ?*const T) -> bool

Reports whether a nullable single-element pointer is null.

Associated function Pointer.isNullMany

pub fn isNullMany<T>(pointer: ?[*]const T) -> bool

Reports whether a nullable many-element pointer is null.

Associated function Pointer.nonNull

pub fn nonNull<T>(pointer: ?*const T) -> silk/option.Option<*const T>

Returns a non-null shared pointer when the address is not zero.

Gotchas

A present result does not prove that the addressed storage is live or initialized.

Associated function Pointer.nonNullMut

pub fn nonNullMut<T>(pointer: ?*mut T) -> silk/option.Option<*mut T>

Returns a non-null writable pointer when the address is not zero.

Gotchas

A present result does not prove that the addressed storage is live or initialized.

Associated function Pointer.nonNullMany

pub fn nonNullMany<T>(pointer: ?[*]const T) -> silk/option.Option<[*]const T>

Returns a non-null shared many-element pointer when the address is not zero.

Gotchas

The result carries no length and proves no storage validity.

Associated function Pointer.nonNullManyMut

pub fn nonNullManyMut<T>(pointer: ?[*]mut T) -> silk/option.Option<[*]mut T>

Returns a non-null writable many-element pointer when the address is not zero.

Gotchas

The result carries no length and proves no storage validity.

Associated function Pointer.fromRef

pub fn fromRef<T, 'life1>(value: &'life1 T) -> *const T

Forms a non-null shared pointer without extending the reference's loan.

Gotchas

The pointer keeps no storage alive. A later access must prove that the storage remains live.

Associated function Pointer.fromMutRef

pub fn fromMutRef<T, 'life1>(value: &'life1 mut T) -> *mut T

Forms a non-null writable pointer without extending the reference's loan.

Gotchas

The pointer keeps no storage alive. A later access must prove that the storage remains live.

Associated function Pointer.fromSlice

pub fn fromSlice<T, 'life1>(values: &'life1 [T]) -> ?[*]const T

Forms a nullable shared many-element pointer from a slice address.

Gotchas

The pointer carries no length or loan. Pass the length separately and keep the storage live.

Associated function Pointer.fromMutSlice

pub fn fromMutSlice<T, 'life1>(values: &'life1 mut [T]) -> ?[*]mut T

Forms a nullable writable many-element pointer from a slice address.

Gotchas

The pointer carries no length or loan. Pass the length separately and keep the storage live.

Associated function Pointer.at

pub unsafe fn at<T>(pointer: [*]const T, index: usize) -> *const T

Returns a shared pointer to one element of a many-element pointer.

Gotchas

The caller must prove that index selects an element within the same live allocation.

Associated function Pointer.atMut

pub unsafe fn atMut<T>(pointer: [*]mut T, index: usize) -> *mut T

Returns a writable pointer to one element of a many-element pointer.

Gotchas

The caller must prove that index selects an element within the same live writable allocation.

Associated function Pointer.read

pub unsafe fn read<T>(pointer: *const T) -> T

Copies one initialized value from naturally aligned storage.

Gotchas

The caller must prove that the pointer addresses a live, readable, initialized T.

Associated function Pointer.write

pub unsafe fn write<T>(pointer: *mut T, value: T) -> ()

Writes one value into naturally aligned storage.

Gotchas

The caller must prove that the pointer addresses live writable storage for T.

Associated function Pointer.readUnaligned

pub unsafe fn readUnaligned<T>(pointer: *const align(1) T) -> T

Copies one initialized value from storage with byte alignment.

Gotchas

The caller must prove that the pointer addresses a live, readable, initialized T.

Associated function Pointer.writeUnaligned

pub unsafe fn writeUnaligned<T>(pointer: *mut align(1) T, value: T) -> ()

Writes one value into storage with byte alignment.

Gotchas

The caller must prove that the pointer addresses live writable storage for T.

Associated function Pointer.assumeAligned

pub unsafe fn assumeAligned<T>(pointer: *const align(1) T) -> *const T

Returns a pointer with the natural alignment of its pointee.

Gotchas

The caller must prove that the address satisfies the target alignment of T. The result holds no loan and keeps no storage alive.

Associated function Pointer.assumeMany

pub unsafe fn assumeMany<T>(pointer: *const T) -> [*]const T

Returns a many-element pointer without a length.

Gotchas

The caller must prove the element range separately before each indexed access. The result holds no loan and keeps no storage alive.

Associated function Pointer.assumeAlignedMut

pub unsafe fn assumeAlignedMut<T>(pointer: *mut align(1) T) -> *mut T

Returns a pointer with the natural alignment of its pointee.

Gotchas

The caller must prove that the address satisfies the target alignment of T. The result holds no loan and keeps no storage alive.

Associated function Pointer.assumeManyMut

pub unsafe fn assumeManyMut<T>(pointer: *mut T) -> [*]mut T

Returns a many-element pointer without a length.

Gotchas

The caller must prove the element range separately before each indexed access. The result holds no loan and keeps no storage alive.