Skip to content

CEP-0059: Testing Allocator and Leak Reporting

Draft

Draft proposal for a standard testing allocator that reports leaks. V1 does not require a public concrete allocator implementation.

Summary

Catalyst should eventually define a standard allocator for tests that tracks live allocations and reports leaks deterministically.

V1 keeps the Allocator contract in the prelude and leaves concrete allocator implementations in std.mem. A testing allocator is useful enough to preserve as its own proposal because it crosses allocator policy, test runner reporting, diagnostics, ownership cleanup, and deterministic snapshot behavior.

Motivation

Allocation visibility is a core Catalyst design value, but visible allocation is only useful if tests can verify cleanup behavior. A leak-reporting allocator gives examples, standard-library tests, and user tests one common way to catch missed dispose, destroy, or free calls.

Leak reporting also needs sharper policy than a normal allocator:

  • when leak checks run;
  • how leak details are reported;
  • whether leak reports fail the test, trap, or produce structured diagnostics;
  • how nested/scoped allocators compose;
  • whether allocation site metadata is captured;
  • how reporting stays deterministic across targets and build profiles.

Proposed Direction

The future design should cover:

  • a concrete testing allocator type or factory under std.mem or std.testing;
  • whether the public spelling is std.mem.TestingAllocator, std.testing.allocator, or another focused API;
  • allocator construction, reset, leak-check, and disposal behavior;
  • deterministic leak reports that avoid pointer addresses and host-specific formatting;
  • integration with std.testing so leaked allocations fail tests in a standard way;
  • optional allocation-site capture using source metadata when available;
  • scoped child allocators or checkpoints for subtests and fixtures;
  • behavior when the wrapped allocator itself fails;
  • interaction with Box, collections, dynamic iteration, and other allocator-taking APIs;
  • whether the allocator exposes a *impl Allocator static path, an erased *dyn Allocator adapter, or both.

Example

Possible future shape:

fn test_box_cleanup() void!AllocError {
  var testing_alloc = std.testing.LeakAllocator.create()
  defer testing_alloc.dispose()

  const alloc = testing_alloc.allocator()
  var item = try Box(Item).create(alloc, Item.init())
  defer item.dispose()

  std.testing.assert_no_leaks(&testing_alloc)
}

The exact API shape is deferred. The important direction is that leak reporting is explicit, deterministic, and integrated with standard test failure reporting rather than hidden in ordinary allocation.

V1 Compatibility

V1 does not require a public testing allocator implementation. V1 examples that need allocation should take allocator authority as an explicit parameter or use implementation-private test fixtures.

The accepted V1 standard-library skeleton may reserve namespace ownership for testing allocators, but no constructor, singleton, leak-report format, allocation-site metadata, or test-runner integration is accepted until this CEP is designed.