Crate checkers

Checkers is a simple allocation sanitizer for Rust. It plugs in through the global allocator and can sanity check your unsafe Rust during integration testing. Since it plugs in through the global allocator it doesn't require any additional dependencies and works for all platforms - but it is more limited in what it can verify.

It can check for the following things:

• Double-frees.
• Memory leaks.
• Freeing regions which are not allocated.
• Freeing only part of regions which are allocated.
• Freeing a region with a mismatched layout.
• That the underlying allocator produces regions adhering to the requested layout. Namely size and alignment.
• Detailed information on memory usage.
• Other 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.
• Detect out-of-bounds accesses.

Safety

With the default feature set, this library performs diagnostics which will produce undefined behavior. Therefore, it is recommended that you only use checkers for testing, and never in any production code.

If you want to avoid this, you'll have to disable the realloc and zeroed features, but this will also produce less actionable diagnostics.

In a future release, this behavior will be changed to be opt-in through feature flags instead of enabled by default.

Features

The following are features available, that changes how checkers work.

• realloc - Enabling this feature causes checker to verify that a realloc operation is correctly implemented. That bytes from the old region were faithfully transferred to the new, resized one. Since this can have a rather significant performance impact, it can be disabled. Note that this will produce undefined behavior (#1) by reading uninitialized memory, and should only be enabled to provide diagnostics on a best-effort basis.
• zeroed - Enabling this feature causes checkers to verify that a call to alloc_zeroed produces a region where all bytes are set to zero. Note that if the underlying allocator is badly implemented this will produce undefined behavior (#1) since it could read uninitialized memory.
• macros - Enables dependencies and re-exports of macros, like #[checkers::test].

Examples

It is recommended that you use checkers for integration tests, which by default lives in the ./tests directory. Each file in this directory will be compiled as a separate program, so the use of the global allocator can be more isolated.

We then use checkers by installing checkers::Allocator as the global allocator, after this we can make use of #[checkers::test] attribute macro or the checkers::with function in our tests.

#[global_allocator]
static ALLOCATOR: checkers::Allocator = checkers::Allocator::system();

#[checkers::test]
fn test_allocations() {
    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

With checkers::with, we can perform more detailed diagnostics:

#[global_allocator]
static ALLOCATOR: checkers::Allocator = checkers::Allocator::system();

#[test]
fn test_event_inspection() {
    let snapshot = checkers::with(|| {
        let _ = vec![1, 2, 3, 4];
    });

    assert_eq!(2, snapshot.events.len());
    assert!(snapshot.events[0].is_alloc_with(|r| r.size >= 16));
    assert!(snapshot.events[1].is_free_with(|a| a.size >= 16));
    assert_eq!(1, snapshot.events.allocs());
    assert_eq!(1, snapshot.events.frees());
    assert!(snapshot.events.max_memory_used().unwrap() >= 16);
}

Macros

verify

Verify the state of the allocator.

Structs

AllocZeroed	Description of an allocation that is zeroed by the allocator.
Allocator	Allocator that needs to be installed.
Events	Collections of events.
Machine	Fake machine implementation to validate an allocation history.
MuteGuard	A helper guard to make sure the state is de-allocated on drop.
Pointer	A type-erased pointer. The inner representation is specifically not a raw pointer to avoid aliasing the pointers handled by the allocator.
Realloc	Description of a reallocation.
Region	A memory region. Including its location in memory ptr, it's size and alignment align.
Snapshot	A snapshot of the state of the checkers allocator.
State	Structure containing all thread-local state required to use the single-threaded allocation checker.

Enums

Event	Metadata for a single allocation or deallocation.
Violation	A single violation in the variants enforced by checkers.

Functions

is_muted	Test if the crate is currently muted. The allocator is muted by default.
mute_guard	Enable muting for the duration of the guard. A guard ensures that the muted state is restored to its original value even if we are unwinding due to a panic. You should prefer to use with_unmuted when possible.
with	Run the specified closure and return a snapshot of the memory state afterwards.
with_state	Perform an operation, while having access to the thread-local state.
with_unmuted	Run the given closure while the allocator is muted.

Attribute Macros

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