Crate trybox

Stable, no_std-compatible, fallible heap allocation for Box.

Basic usage is as follows:

match trybox::new(1) {
    Ok(heaped) => {
        let _: Box<i32> = heaped;
    }
    Err(ErrorWith(stacked)) => {
        let _: i32 = stacked; // failed object is returned on the stack
    },
}

You may drop the object after allocation failure instead, choosing to e.g propogate or wrap the Error.

fn fallible<T>(x: T) -> Result<Box<T>, Box<dyn std::error::Error + Send + Sync>> {
    Ok(trybox::or_drop(x)?)
}

Care has been taken to optimize the size of Error down to a single usize:

assert_eq!(size_of::<trybox::Error>(), size_of::<usize>());

And to provide ergonomic error messages:

memory allocation of 4 bytes (for type i32) failed

memory allocation of 2.44 kibibytes (for type [u8; 2500]) failed

Conversions to std::io::Error and std::io::ErrorKind::OutOfMemory are provided when the "std" feature is enabled:

fn fallible<T>(x: T) -> std::io::Result<Box<T>> {
    Ok(trybox::or_drop(x)?)
}

Comparison with other crates

• fallacy-box
  • requires a nightly compiler.
• fallible_collections
  • You must use either the TryBox wrapper struct, or the FallibleBox extension trait.
  • The returned error type doesn’t implement common error traits, and isn’t strictly minimal.

Structs

Error

Represents an allocation failure from or_drop.

ErrorWith

Represents the failure to allocate a particular object on the heap, returned from new.

Functions

new

Attempt to move x to a heap allocation, returning a wrapped x on failure.

or_drop

Attempt to move x to a heap allocation, immediately dropping x on failure, and returning a useful Error.