Crate qadapt

debug_assert! for your memory usage

Please note: This crate has been deprecated in favor of alloc-counter.

This allocator is a helper for writing high-performance code that is memory-sensitive; a thread panic will be triggered if a function annotated with #[no_alloc], or code inside an assert_no_alloc! macro interacts with the allocator in any way. Wanton allocations and unforeseen drops no more - this library lets you focus on writing code without worrying if Rust properly managed to inline the variable into the stack.

Now, an allocator blowing up in production is a scary thought; that’s why QADAPT is designed to strip its own code out whenever you’re running with a release build. Just like the debug_assert! macro in Rust’s standard library, it’s safe to use without worrying about a unforeseen circumstance causing your application to crash.

Usage

Actually making use of QADAPT is straight-forward. To set up the allocator, place the following snippet in either your program binaries (main.rs) or tests:

use qadapt::QADAPT;

#[global_allocator]
static Q: QADAPT = QADAPT;

fn main() {
    assert!(qadapt::is_active());
}

After that, there are two ways of telling QADAPT that it should trigger a panic:

1. Annotate functions with the #[no_alloc] proc macro:

use qadapt::no_alloc;
use qadapt::QADAPT;
use std::panic::catch_unwind;

#[global_allocator]
static Q: QADAPT = QADAPT;

// This function is fine, there are no allocations here
#[no_alloc]
fn do_math() -> u8 {
    2 + 2
}

// This function will trigger a panic when called
#[no_alloc]
fn does_panic() -> Box<u32> {
    Box::new(5)
}

fn main() {
    do_math();

    let err = catch_unwind(|| does_panic());
    assert!(err.is_err());
}

2. Evaluate expressions with the assert_no_alloc! macro

use qadapt::assert_no_alloc;
use qadapt::QADAPT;

#[global_allocator]
static Q: QADAPT = QADAPT;

fn main() {
    // This code is allowed to trigger an allocation
    let b = Box::new(8);
     
    // This code would panic if an allocation occurred inside it
    let x = assert_no_alloc!(*b + 2);
    assert_eq!(x, 10);
}

Macros

assert_no_allocDeprecated

Get the result of an expression, guaranteeing that no memory accesses occur during its evaluation.

Structs

QADAPTDeprecated

The QADAPT allocator itself

Functions

enter_protectedDeprecated

Let QADAPT know that we are now entering a protected region and that panics should be triggered if allocations/drops happen while we are running.

exit_protectedDeprecated

Let QADAPT know that we are exiting a protected region. Will panic if we attempt to exit_protected more times than we enter_protected.

is_activeDeprecated

Determine whether QADAPT will trigger thread panics if an allocation happens during protected code. This should be used for making sure that QADAPT is properly set up and initialized.

protection_levelDeprecated

Get the current “protection level” in QADAPT: calls to enter_protected() - exit_protected().

Attribute Macros

no_alloc

Set up the QADAPT allocator to trigger a panic if any allocations happen during calls to this function.