allocator-fallback

This crate provides a minimal fallback for the standard library’s allocator API, which is currently unstable.

Usage

Because allocator-fallback can be configured to re-export the real unstable allocator API via the allocator_api crate feature, your crate must conditionally enable #![feature(allocator_api)] in preparation for this occurrence; otherwise, compilation errors may occur. This is true even if your crate never directly enables the allocator_api feature, because a different crate that also depends on allocator-fallback could enable it.

To accomplish this, in Cargo.toml, add allocator-fallback as both a regular dependency and a build dependency:

[dependencies]
allocator-fallback = "0.1.9"

[build-dependencies]
allocator-fallback = "0.1.9"

Note: It is very important that the two dependencies are identical. Do not enable a feature in one without enabling it in the other.

Then add a build script (build.rs) with the following contents:[^1]

fn main() {
   if allocator_fallback::HAS_ALLOCATOR_API {
       println!("cargo:rustc-cfg=has_allocator_api");
   }
   println!("cargo:rerun-if-changed=build.rs");
}

Finally, at the top of your crate root (likely lib.rs or main.rs), add the following:

#![cfg_attr(has_allocator_api, feature(allocator_api))]

Rust may show a warning about an “unexpected cfg condition name”; you can silence it by adding the following to Cargo.toml:

[lints.rust.unexpected_cfgs]
level = "warn"
check-cfg = ["cfg(has_allocator_api)"]

Use as an optional dependency

If you’d like allocator-fallback to be an optional dependency, first add optional = true to both of its declarations as a dependency:

[dependencies.allocator-fallback]
version = "0.1.9"
optional = true

[build-dependencies.allocator-fallback]
version = "0.1.9"
optional = true

Then adjust build.rs as follows:[^1]

fn main() {
   #[cfg(feature = "allocator-fallback")]
   if allocator_fallback::HAS_ALLOCATOR_API {
       println!("cargo:rustc-cfg=has_allocator_api");
   }
   println!("cargo:rerun-if-changed=build.rs");
}

Finally, make sure you still have the following in your crate root:

#![cfg_attr(has_allocator_api, feature(allocator_api))]

[^1]: These build script code snippets have been released to the public domain using the CC0 1.0 Universal Public Domain Dedication.

Exposing an allocator_api feature in your crate

If you want your crate to directly provide an allocator_api feature that enables the real allocator API, add the following to your Cargo.toml:

[features]
allocator_api = ["allocator-fallback/allocator_api"]

If you declared allocator-fallback as an optional dependency, add the following instead:

[features]
allocator_api = ["allocator-fallback?/allocator_api"]

Crate features

If the crate feature allocator_api is enabled, this crate will simply re-export the real allocator API in the standard library. Of course, this requires Rust nightly.

If the crate feature std is enabled (the default), the crate will use std; otherwise, it will be no_std. Using std allows AllocError to implement std::error::Error.