Crate assert_no_alloc

assert_no_alloc

This crate provides a custom allocator that allows to temporarily disable memory (de)allocations for a thread. If a (de)allocation is attempted anyway, the program will abort or print a warning.

It uses thread local storage for the “disabled-flag/counter”, and thus should be thread safe, if the underlying allocator (currently hard-coded to std::alloc::System) is.

documentation @ docs.rs, crates.io

Rationale

No-allocation-zones are relevant e.g. in real-time scenarios like audio callbacks. Allocation and deallocation can take unpredictable amounts of time, and thus can sometimes lead to audible glitches because the audio data is not served in time.

Debugging such problems can be hard, because it is difficult to reproduce such problems consistently. Avoiding such problems is also hard, since allocation/deallocation is a common thing to do and most libraries are not explicit whether certain functions can allocate or not. Also, this might even depend on the run-time situation (e.g. a Vec::push might allocate, but it is guaranteed to not allocate if enough space has been reserve()d before).

To aid the developer in tackling these problems, this crate offers an easy way of detecting all forbidden allocations.

How to use

First, configure the features: warn_debug and warn_release change the behaviour from aborting your program into just printing an error message on stderr. Aborting is useful for debugging purposes, as it allows you to retrieve a stacktrace, while warning is less intrusive.

Note that you need to disable the (default-enabled) disable_release feature by specify default-features = false if you want to use warn_release. If disable_release is set (which is the default), then this crate will do nothing if built in --release mode.

Second, use the allocator provided by this crate. Add this to main.rs:

use assert_no_alloc::*;

#[cfg(debug_assertions)] // required when disable_release is set (default)
#[global_allocator]
static A: AllocDisabler = AllocDisabler;

Third, wrap code sections that may not allocate like this:

assert_no_alloc(|| {
	println!("This code can not allocate.");
});

Advanced use

Values can be returned using:

let answer = assert_no_alloc(|| { 42 });

The effect of assert_no_alloc can be overridden using permit_alloc:

assert_no_alloc(|| {
	permit_alloc(|| {
		// Allocate some memory here. This will work.
	});
});

This is useful for test stubs whose code is executed in an assert_no_alloc context.

Objects that deallocate upon Drop can be wrapped in PermitDrop:

let foo = PermitDrop::new(
    permit_alloc(||
        Box::new(...)
    )
);

Dropping foo will not trigger an assertion (but dropping a Box would).

assert_no_alloc() calls can be nested, with proper panic unwinding handling.

Note that to fully bypass this crate, e.g. when in release mode, you need to both have the disable_release feature flag enabled (which it is by default) and to not register AllocDisabler as global_allocator.

Examples

See examples/main.rs for an example.

You can try out the different feature flags:

• cargo run --example main -> memory allocation of 4 bytes failed. Aborted (core dumped)
• cargo run --example main --release --no-default-features -> same as above.
• cargo run --example main --features=warn_debug -> Tried to (de)allocate memory in a thread that forbids allocator calls! This will not be executed if the above allocation has aborted.
• cargo run --example main --features=warn_release --release --no-default-features -> same as above.
• cargo run --example main --release will not even check for forbidden allocations

Test suite

The tests will fail to compile with the default features. Run them using:

cargo test --features=warn_debug --tests

Structs

• AllocDisabler
  The custom allocator that handles the checking.
• PermitDrop
  Wrapper for objects whose Drop implementation shall be permitted to (de)allocate.

Functions

• assert_no_alloc
  Calls the func closure, but forbids any (de)allocations.
• permit_alloc
  Calls the func closure. Allocations are temporarily allowed, even if this code runs inside of assert_no_alloc.
• reset_violation_count
  Resets the count of allocation warnings to zero.
• violation_count
  Returns the count of allocation warnings emitted so far.