std/src/runtime/raw_mem.nv - main - nv-lang/nova

std/src/runtime/raw_mem.nv
127 строк5 KB
Evgeniy Golovin
merge: comment-hygiene-2 — чистка комментариев std (batch 1-20) + линт-свип 330→13
01 авг 2026, 18:13
01 авг 2026, 18:13bb8b33d
// SPDX-License-Identifier: MIT OR Apache-2.0
//
// std.runtime.raw_mem — low-level byte-level memory intrinsics для
// FFI / driver / embedded scenarios.
//
// **RawMem namespace** (`type RawMem`) groups raw memory operations.
// All methods operate on raw pointers — caller wraps calls in `unsafe { }` block.
//
// V1 scope (this file): byte-level untyped operations. User responsible
// for size calculations (`count * sizeof(T)` patterns). Generic typed
// variants (`RawMem.copy[T]`) — V2 follow-on, require `sizeof[T]()`
// const fn intrinsic propagation.
//
// Pointer types: `*u8` (default ro) для src,
// `*mut u8` (pointee-mut postfix) для dst.
// Rust precedents:
//   - ptr::copy (memmove)              -> RawMem.copy
//   - ptr::copy_nonoverlapping (memcpy) -> RawMem.copy_nonoverlapping
//   - ptr::write_bytes (memset)        -> RawMem.fill
//
// Zig precedents:
//   - @memcpy(dst, src) -> RawMem.copy_nonoverlapping
//   - @memset(dst, val) -> RawMem.fill

module runtime.raw_mem

/// RawMem — a namespace for low-level memory operations.
///
/// Unit type (no fields). Used as static-method namespace per Nova
/// convention (see spec/02-types.md examples `type Empty` / `type Sentinel`).
export type RawMem

/// memmove — copy `n` bytes from `src` to `dst`. Overlap-safe.
///
/// Mirrors the semantics of `[]T.copy_from` (Plan 90 / D141): safe even when
/// `src` and `dst` ranges overlap. ~2-5% slower than `copy_nonoverlapping`
/// due to the overlap check, yet safe for arbitrary pointer pairs.
///
/// Use cases: generic memory copy where overlap possible (slice
/// rotation, buffer scrolling).
///
/// Caller wraps in `unsafe { }` block — raw pointer operation.
export extern "nova" unsafe fn RawMem.copy(src *u8, dst *mut u8, n int) -> ()

/// memcpy — copy `n` bytes from `src` to `dst`. UB on overlap.
///
/// Faster than `copy` (no overlap check). Caller must ensure
/// `[src, src+n)` and `[dst, dst+n)` ranges do NOT overlap.
///
/// Use cases: known-distinct buffers (e.g., between two arrays,
/// from an FFI buffer to a Nova buffer).
export extern "nova" unsafe fn RawMem.copy_nonoverlapping(src *u8, dst *mut u8, n int) -> ()

/// memset — fill `n` bytes at `dst` with byte-pattern `val`.
///
/// Single-byte fill. For typed-element fill (e.g., u32 array filled with
/// specific i32 value), iterate manually. Mirrors both `@memset` (Zig) and
/// `ptr::write_bytes` (Rust) — one canonical name (`fill`), no alias.
export extern "nova" unsafe fn RawMem.fill(dst *mut u8, val u8, n int) -> ()

/// memcmp — compare `n` bytes at `a` and `b`. Returns -1/0/+1.
///
/// Result normalized to -1/0/+1 (libc memcmp's non-zero result
/// is implementation-defined; Nova normalizes for consistency).
///
///   - Returns `0` if bytes equal
///   - Returns `-1` if the first differing byte in `a` is less than in `b`
///   - Returns `+1` if the first differing byte in `a` is greater than in `b`
export extern "nova" unsafe fn RawMem.compare(a *u8, b *u8, n int) -> int

/// Allocate `n` bytes of GC-tracked zeroed memory. Returns raw `*mut u8`.
///
/// Backed by `nova_alloc(n)` from `nova_rt/alloc.h`. Memory is
/// GC-collectable — do NOT store pointer in static/global without GC-root
/// registration (use `RawMem.alloc_uncollectable` for long-lived buffers).
///
/// CONTRACT: returns zeroed memory (all bytes = 0x00).
/// Alignment: 8-byte (nova_alloc guarantee).
/// Size: `n > 0` recommended; behaviour with `n = 0` is implementation-defined.
///
export extern "nova" unsafe fn RawMem.alloc(n int) -> *mut u8

/// Allocate `n` bytes NOT GC-tracked. Caller must call `RawMem.free_uncollectable`.
///
/// Backed by `nova_alloc_uncollectable(n)`. Memory persists until explicit
/// `RawMem.free_uncollectable` call — GC will NOT collect it. Use for
/// long-lived buffers that must not be collected between cross-thread
/// write and read (avoids conservative-scan miss on Windows fiber arena).
///
/// CONTRACT: returns zeroed memory (all bytes = 0x00).
/// Alignment: 8-byte.
///
export extern "nova" unsafe fn RawMem.alloc_uncollectable(n int) -> *mut u8

/// Free a pointer allocated with `RawMem.alloc_uncollectable`.
///
/// Backed by `nova_free_uncollectable(ptr)`. UB if called on a GC-tracked
/// pointer (from `RawMem.alloc`) — use GC-tracked memory only with GC.
/// Double-free is UB.
export extern "nova" unsafe fn RawMem.free_uncollectable(ptr *mut u8) -> ()

/// Typed memmove — copy `count` **elements** of `T` from `src` to `dst`.
/// Overlap-safe (mirrors `RawMem.copy`, scaled by `size_of[T]()`).
///
/// Rust precedent: `ptr::copy<T>`. Count is in *elements*, not bytes — the
/// byte-level `RawMem.copy` requires the caller to multiply by
/// `size_of[T]()` at every call site; this wrapper does that once, here.
///
/// Caller wraps in `unsafe { }` block — raw pointer operation.
export unsafe fn RawMem.copy_n[T](src *T, dst *mut T, count int) -> ()
    requires count >= 0
{
    RawMem.copy(src as *u8, dst as *mut u8, count * size_of[T]())
}

/// Typed memcpy — copy `count` **elements** of `T` from `src` to `dst`. UB on
/// overlap (mirrors `RawMem.copy_nonoverlapping`, scaled by `size_of[T]()`).
///
/// Rust precedent: `ptr::copy_nonoverlapping<T>`. Count is in *elements*, not
/// bytes.
///
/// Caller wraps in `unsafe { }` block — raw pointer operation.
export unsafe fn RawMem.copy_n_nonoverlapping[T](src *T, dst *mut T, count int) -> ()
    requires count >= 0
{
    RawMem.copy_nonoverlapping(src as *u8, dst as *mut u8, count * size_of[T]())
}