silk/metrics

Provider-owned allocation counters that can be published as ordinary copyable data.

When to use

Embed AllocationMetrics in a custom Allocator provider when tests or diagnostics need acquisition, release, current-live, or peak-live counts. Code that never imports this module pays no instrumentation cost.

Details

The compiler does not collect these metrics. A provider calls recordAcquire and recordRelease at its own allocation boundary, then exposes an independent snapshot with copy. Counts belong to that provider instance rather than to the process globally.

Gotchas

Recording is intentionally minimal and assumes every release corresponds to an earlier acquire. The module does not identify allocations or repair an unbalanced provider.

Examples

Publish a snapshot of one allocation ledger

import silk.metrics as Metrics

import silk.usize as usize

pub fn main() -> i32 {
  let mut metrics = Metrics.make()
  Metrics.recordAcquire(&mut metrics)
  Metrics.recordAcquire(&mut metrics)
  Metrics.recordRelease(&mut metrics)

  let snapshot = Metrics.copy(&metrics)
  if snapshot.acquired != usize.add(0, 2) {
    return 1
  }
  if snapshot.released != usize.ONE {
    return 2
  }
  if Metrics.live(&snapshot) != usize.ONE {
    return 3
  }
  if snapshot.peakLive != usize.add(0, 2) {
    return 4
  }
  return 42
}

Import as AllocationMetrics with import silk.metrics.

Public declarations: 6.

AllocationMetrics

pub struct AllocationMetrics

Copyable counters for one provider's successful allocation acquisitions and releases.

Details

acquired and released are cumulative. peakLive is the greatest value of acquired - released observed by recordAcquire. Use live for the current difference.

Field acquired

pub acquired: usize

The cumulative number of successful acquisitions recorded by the provider.

Field released

pub released: usize

The cumulative number of releases recorded by the provider.

Field peakLive

pub peakLive: usize

The greatest live-allocation count observed after an acquisition.

Implementation Copy for AllocationMetrics

impl Copy for AllocationMetrics

make

pub fn make() -> AllocationMetrics

Creates a ledger with zero acquisitions, zero releases, and a zero peak.

copy

pub fn copy(self: &silk/metrics.AllocationMetrics) -> AllocationMetrics

Copies the current counters without moving or changing the provider's ledger.

When to use

Use this function when a provider must publish metrics while it keeps the mutable ledger.

live

pub fn live(self: &silk/metrics.AllocationMetrics) -> usize

Returns acquired - released, which is the number of recorded live allocations.

Gotchas

If released is greater than acquired, the unsigned subtraction traps. Record each release only after its matching successful acquisition.

recordAcquire

pub fn recordAcquire(self: &mut silk/metrics.AllocationMetrics) -> ()

Adds one successful acquisition and updates the peak live count.

Details

Call this function only after the provider acquires the allocation. A failed acquisition must not change the counters.

Gotchas

The operation traps if acquired overflows usize. An unbalanced prior release can also make the live-count subtraction trap.

recordRelease

pub fn recordRelease(self: &mut silk/metrics.AllocationMetrics) -> ()

Adds one release without changing the historical peak live count.

Details

Call this function after the provider releases one allocation that it previously recorded.

Gotchas

This function does not check that a matching acquisition exists. If releases become greater than acquisitions, live traps.