[−][src]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.
Features
The following are features available, that changes how checkers work.
realloc
- Enabling this feature causes checker to verify that arealloc
operation is correct. 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.
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 a zero-allocation. |
Allocator | |
Events | A fixed-size collection of allocations. |
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 | |
Snapshot | |
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 |
Functions
is_muted | Test if the crate is currently muted. |
mute_guard | Enable muting for the duration of the guard. |
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. |
Attribute Macros
test | Marks a function to be run as a test in a checkers test suite. |