Crate checkers

Checkers is a simple allocation checker for Rust. It plugs in through the global allocator API and can sanity check your unsafe Rust during integration testing.

It can check for the following things:

• Double-frees.
• Attempts to free regions which are not allocated.
• Underlying allocator producting regions not adhering to the requested layout. Namely size and alignment.
• Other arbitrary user-defined conditions (see test).

What it can't do:

• Test multithreaded code. Since the allocator is global, it is difficult to scope the state for each test case.

Examples

You use checkers by installing checkers::Allocator as your allocator, then making use of either the #[checkers::test] or checkers::with! macros.

#[global_allocator]
static ALLOCATOR: checkers::Allocator = checkers::Allocator;

#[checkers::test]
fn test_leak_box() {
    let _ = Box::into_raw(Box::new(42));
}

The above would result in the following test output:

dangling region: 0x226e5784f30-0x226e5784f40 (size: 16, align: 8).
thread 'test_leak_box' panicked at 'allocation checks failed', tests\leaky_tests.rs:4:1

Macros

verify	Verify the state of the allocator.
with	Simplified helper macro to run the checkers environment over a closure.

Structs

Allocator	Allocator that needs to be installed.
Events	A fixed-size collection of allocations.
Machine	Fake machine implementation to validate an allocation history.
Pointer	A type-erased pointer. The inner representation is specifically not a raw pointer to avoid aliasing the pointers handled by the allocator.
Region
State	Structure containing all thread-local state required to use the single-threaded allocation checker.
StateGuard	A helper guard to make sure the state is de-allocated on drop.

Enums

Event	Metadata for a single allocation or deallocation.
Violation

Constants

MUTED
STATE	Thread-local state required by the allocator.

Functions

is_muted	Test if the crate is currently muted.
mute	Enable muting for the duration of the guard.

Attribute Macros

test	Marks a function to be run as a test in a checkers test suite.