[][src]Crate mockalloc

Mockalloc is a crate to allow testing code which uses the global allocator. It uses a probabilistic algorithm to detect and distinguish several kinds of allocation related bugs:

  • Memory leaks
  • Double frees
  • Invalid frees (bad pointer)
  • Invalid frees (bad size)
  • Invalid frees (bad alignment)

Once a bug is detected, you can enable the tracing feature of this crate to collect detailed information about the problem including backtraces showing where memory was allocated and freed.

In the case the memory was leaked, it is also possible to find a list of backtraces showing possibilities for where we expected the memory to be freed.

Note: the tracing feature incurs a significant performance penalty. (Although it is significantly faster than running the code under miri). You should also be aware that backtraces are often less complete in release builds where many frames are optimized out.


Typical use involves enabling the Mockalloc allocator during tests, eg:

mod tests {
    use std::alloc::System;
    use mockalloc::Mockalloc;

    static ALLOCATOR: Mockalloc<System> = Mockalloc(System);

Once the allocator is enabled, there are several ways to use it in your tests.

The easiest way is to use the #[mockalloc::test] attribute on your tests instead of the usual #[test] attribute:

    fn it_works() {
        // Some code which uses the allocator

The test will fail if any of the allocation bugs listed above are detected. The test will also fail with the NoData error if no allocations are detected so that you can be sure that the Mockalloc allocator is active.

You can also use mockalloc to test a specific section of code for memory issues without checking the entire test using the assert_allocs function.

The #[mockalloc::test] attribute in the prior example is simply a shorthand for:

    fn it_works() {
        mockalloc::assert_allocs(|| {
            // Some code which uses the allocator

It is also possible to make more detailed assertions: for example you may want to assert that a piece of code performs a specific number of allocations. For this you can use the record_allocs function:

    fn it_works() {
        let alloc_info = mockalloc::record_allocs(|| {
            // Some code which uses the allocator

        assert_eq!(alloc_info.num_allocs(), 2);

        // This is what `assert_allocs` does internally:


Allocations are tracked separately for each thread. This allows tests to be run in parallel, but it means that the library will report false positives if a pointer returned by an allocation on one thread is later freed by a different thread.

When the tracing feature is disabled, the algorithm cannot detect where the bug is, it can only indicate what kind of bug is present.

How it works

The allocator does its tracking without allocating any memory itself. It uses a probabilistic algorithm which works by hashing various pieces of metadata about allocations and frees, and then accumulating these using a commutative operation so that the order does not affect the result.

Depending on which of these accumulators returns to zero by the end of a region under test, different allocation bugs can be distinguished.

The following metadata is hashed and accumulated:

  • Pointer
  • Size & Pointer
  • Alignment & Pointer

In addition to tracking the total number of allocations and frees.

We can detect memory leaks and double frees by looking for a difference between the total numbers of allocations and frees.

Otherwise, if the pointer accumulator does not return to zero, we know that an invalid pointer was freed.

Otherwise, we know the right pointers were freed, but maybe with the wrong size and/or alignment, which we can detect with the other two accumulators.

If all accumulators returned to zero then we know everything is good.

Each accumulator and hash is 128 bits to essentially eliminate the chance of a collision.



Functionality for detailed tracing of allocations. Enabled with the tracing feature.



Captures information about the allocations performed by a region under test.


Wraps an existing allocator to allow detecting allocation bugs. You should use the #[global_allocator] attribute to activate this allocator.



Types of allocation bug which can be detected by the allocator.



Records the allocations within a code block and asserts that no issues were detected.


Returns true if allocations are currently being recorded, ie. if we're inside a call to record_allocs.


Records the allocations within a code block.

Attribute Macros


Replacement for the #[test] macro to automatically detect allocation bugs from within the test.