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

std/src/runtime/gc.nv
134 строки6 KB
Evgeniy Golovin
docs(endocs): runtime — translate remaining /// docs to English
01 авг 2026, 01:57
01 авг 2026, 01:571162678
// std/runtime/gc.nv — GC introspection API (Plan 32).
//
// **NOT auto-gen.** Этот модуль документирует hard-coded namespace `gc.*`
// который dispatched через [compiler-codegen/src/codegen/emit_c.rs]
// special-cases (как `panic()`/`exit()`/`assert()`).
//
// `gc` — uniqueness: **lowercase namespace** (не type) для consistency с
// прецедентами в других языках:
//   - Go:     `runtime.GC()`, `runtime.ReadMemStats(&ms); ms.HeapAlloc`
//   - Java:   `System.gc()`, `Runtime.getRuntime().totalMemory()`
//   - Python: `gc.collect()`, `gc.get_stats()`
//   - .NET:   `GC.Collect()`, `GC.GetTotalMemory(false)`
//
// Использование:
//
//   import std.runtime.gc       // активирует name resolution для `gc.*`
//
//   let h = gc.heap_size()       // bytes; 0 если backend без introspection
//   let n = gc.live_count()      // приблизительное число live-объектов
//   let a = gc.alloc_count()     // монотонный счётчик с старта
//   gc.collect()                 // принудительный сбор (no-op под malloc)
//   gc.reset_stats()             // сброс счётчиков
//
// **Semantics per backend:**
//
// | API              | malloc                           | boehm                    |
// |------------------|----------------------------------|--------------------------|
// | heap_size()      | 0 (honest "not supported")       | GC_get_heap_size()       |
// | live_count()     | alloc_count - free_count         | alloc_count (upper bound)|
// | alloc_count()    | monotonic counter                | monotonic counter        |
// | collect()        | no-op                            | GC_gcollect()            |
// | reset_stats()    | zero counters                    | zero counters            |
//
// **`heap_size() == 0`** — honest sentinel «backend не поддерживает».
// Тесты могут использовать `if gc.heap_size() == 0 { ... skip ... }`
// для differential-behaviour, либо marker `// ALLOC_REQUIRES boehm`
// для жёсткого скипа.
//
// **`gc.collect()`** — тяжёлая операция (full mark-sweep под Boehm).
// Не использовать в hot path. Назначение — manual API для diagnostic
// и явной разгрузки перед blocking I/O.
//
// ──────────────────────────────────────────────────────────────────────────
// Источник истины для type-checker'а И codegen
// ──────────────────────────────────────────────────────────────────────────
//
// Эти `external fn` объявления — **единственный source of truth**, и для
// type-checker'а (обычный `import`), и для codegen: c-имя (`nova_gc_*`)
// приходит через `ExternalRegistry::NAMESPACE_OVERRIDES`
// (compiler-codegen/src/codegen/external_registry.rs) — этот файл
// embedded builtin source, ручной синхронизации с emit_c.rs больше не
// требуется ([M-compiler-nv-porting-wave] item B1, 2026-07-07).
//
// Используется `gc` как identifier-name (D-spec exception: lowercase для
// namespace-like API, аналог Python `gc.collect()` или Go
// `runtime.GC()`). При изменении API — обновить **оба** места.

module runtime.gc

// ─── gc namespace ───────────────────────────────────────────────────────

/// Heap size in bytes.
///
/// With the malloc backend always returns `0` (honest sentinel "backend does not
/// support introspection"). With Boehm returns `GC_get_heap_size()`.
///
/// Tests can use `if gc.heap_size() == 0 { ... skip ... }`
/// for backend-dependent differential behaviour.
///
/// # See Also
///
/// - `[gc.live_count]` — approximate number of live objects
/// - `[gc.alloc_count]` — monotonic allocation counter
#stable(since = "0.1")
export extern "nova" fn gc.heap_size() -> int

/// Approximate number of live objects.
///
/// With malloc: `alloc_count - free_count` (free_count always 0 → the value
/// grows monotonically). With Boehm: upper bound via `alloc_count`
/// (Boehm does not expose the real live count).
///
/// # See Also
///
/// - `[gc.alloc_count]` — monotonic counter
/// - `[gc.collect]` — forced collection
#stable(since = "0.1")
export extern "nova" fn gc.live_count() -> int

/// Monotonic allocation counter since start or `gc.reset_stats()`.
///
/// Useful for smoke tests of the "heap does not grow over N iterations" kind.
/// The value is reset by calling `[gc.reset_stats]`.
///
/// # Examples
///
/// ```nova
/// gc.reset_stats()
/// // ... some allocations ...
/// assert(gc.alloc_count() > 0)
/// ```
#stable(since = "0.1")
export extern "nova" fn gc.alloc_count() -> int

/// Force a garbage collection.
///
/// With malloc — no-op. With Boehm — a synchronous full mark-sweep via
/// `GC_gcollect()`. WARNING: a heavy operation, do not use in a hot path.
/// Purpose — manual diagnostics or an explicit drain before blocking I/O.
///
/// # Effects
///
/// With Boehm runs a full mark-sweep GC cycle.
#stable(since = "0.1")
export extern "nova" fn gc.collect() -> ()

/// Reset the allocation counters (`alloc_count` → 0).
///
/// Used for per-test isolation. Boehm's own GC stats are not
/// reset — Boehm does not support runtime-level reset.
#stable(since = "0.1")
export extern "nova" fn gc.reset_stats() -> ()

/// Duration of the last GC cycle in nanoseconds.
///
/// With the malloc backend always `0` (no collect cycle). With Boehm —
/// measured with a monotonic timer around `GC_gcollect()`.
/// Useful for `nova bench run --profile gc` and production observability.
///
/// # See Also
///
/// - `[gc.collect]` — forced collection
#stable(since = "0.1")
export extern "nova" fn gc.last_pause_ns() -> int