Tracking issue for the #[alloc_error_handler] attribute (for no_std + liballoc)

[SimonSapin]

This attribute is mandatory when using the alloc crate without the std crate. It is used like this:

#[alloc_error_handler]
fn foo(_: core::alloc::Layout) -> ! {
    // …
}

Implementation PR: #52191

Blocking issues

• Adding #[track_caller] on #[alloc_error_handler] seems to cause undefined behavior #83430
• Who is responsible for preventing reentrancy issues through the allocator? unsafe-code-guidelines#506
• alloc_error_handler can be an unsafe fn which is then unsoundly invoked #134225
• The combination of alloc_error_handler and target_features_11 is unsound #134234

Original issue:

---

In a no_std program or staticlib, linking to the alloc crate may cause this error:

error: language item required, but not found: `oom`

This is fixed by providing the oom lang item, which is is normally provided by the std crate (where it calls a dynamically-settable hook #51245, then aborts). This is called by alloc::alloc::handle_alloc_error (which is called by Vec and others on memory allocation failure).

#![feature(lang_items)]

#[lang = "oom"]
extern fn foo(_: core::alloc::Layout) -> ! {
    // example implementation based on libc
    extern "C" { fn abort() -> !; }
    unsafe { abort() }
}

However, defining a lang item is an unstable feature.

Possible solutions include:

1. Add and stabilize a dedicated attribute similar to the #[panic_implementation] attribute:

#[alloc_error_handler]
fn foo(_: core::alloc::Layout) -> ! {
    // …
}

The downside is that this is one more mandatory hoop to jump through for no_std program that would have been fine with a default hook that aborts.

2. Move std’s dynamically-settable hook into alloc: Move OOM handling to liballoc and remove the oom lang item #51607. The downside is some mandatory space overhead.

[SimonSapin]

Better idea: remove the lang item and move all of OOM handling to liballoc, except for the default hook that prints to stderr. Have compiler magic similar to that of #[global_allocator] that uses the printing default hook when std is linked, or a no-op default hook otherwise.

[glandium]

Bikeshedding on oom renaming: alloc_error would be shorter.

[SimonSapin]

I forgot to link #51543, which does indeed use alloc_error.

[SimonSapin]

@japaric, @glandium, @Amanieu I’ve updated the the issue description here with arguments from #51607 and rust-lang/rfcs#2480 and to list two alternatives.

[japaric]

Replying to @glandium's rust-lang/rfcs#2480 (comment) here to not derail the alloc RFC.

Every #[no_std] user of the alloc crate would have to implement their own

Not everyone has to implement their own. An implementation can be packed into a crate and it just takes adding a extern crate oom_abort; to register an OOM handler -- this is no different than what we have for global allocators (e.g. extern crate alloc_jemalloc).

and they can't use instrinsics::abort, so it becomes harder than necessary.

Then stabilize intrinsics::abort or provide a stable oom_abort crate with the rust-std component. Though it's better to stabilize intrinsics::abort because then we can use it for #[panic_implementation] too.

The problem is that with a #[oom] attribute, you don't get a default handler at all.

No default OOM handler is good. There's no sensible default for every single combination of no_std program and target anyways. For example, intrinsics::abort produces a linker error on MSP430 because there's no abort instruction in the MSP430 instruction set.

Also, not having a default is consistent with both #[panic_implementation] and #[global_allocator] in #[no_std] context. Why special case the OOM handler?

---

Another reason why I like static registration of global properties is that it's less error prone. Say you want the OOM (or panic) handler to behave differently between development and final release. With #[oom] you can write this:

#[cfg(debug_assertions)]
extern crate oom_report; // for development, verbose

#[cfg(debug_assertions)]
extern crate oom_panic; // for release, minimal size

This is clearly wrong, you get a compiler error. With the set_alloc_error_hook you don't get a compiler error; you won't notice the problem until you hit an OOM in dev and lost your opportunity to track down the root of the OOM.

The other reason I like #[oom] / #[panic_implementation] is that you can be sure of the behavior of the OOM / panic if you register the handler in the top crate.

extern crate oom_abort; // I'm 100% sure OOM = abort

With the hook API you have no guarantee

fn main() {
    set_alloc_error_hook(|| abort()); // OOM = abort, maybe

    dependency::function(); // this is totally free to change the OOM handler

    // ..
}

---

Finally, if you need the ability to override the OOM handler at runtime using hooks you can implement that on top of #[oom].

[SimonSapin]

@japaric I find this convincing regarding static v.s. dynamic, thanks.

For example, intrinsics::abort produces a linker error on MSP430 because there's no abort instruction in the MSP430 instruction set.

Oh, I was wondering if something like that ever happened.

How does one typically deal with unrecoverable situations on MSP430? An infinite loop?

No default OOM handler is good.

I think we can have a default, with a Sufficiently Advanced Compiler. (Grep for has_global_allocator for code that does something similar.)

But you’re saying we should not, and force that question on ever no_std user. This would be one more barrier before being able to get to Hello World.

[SimonSapin]

#51607 (comment)

FWIW an attribute like #[oom] I also think would be a great idea (and I think I'm also convinced that it may be worth it over this dynamic strategy), and it could be implemented pretty similar to #[panic_implementation]

Right. I think the remaining question is: should there be a default? If not, what should be a "typical" implementation that we’d recommend in docs? Should we add a stable wrapper for core::intrinsics::abort? (In what module?)

The docs for core::intrinsics::abort claim:

The stabilized version of this intrinsic is std::process::abort

But besides availability, the two functions do not have equivalent behavior: servo/servo#16899.

[japaric]

How does one typically deal with unrecoverable situations on MSP430? An infinite loop?

@pftbest and @cr1901 would be more qualified to answer that question. I'm not a MSP430 developer myself.

On Cortex-M the abort instruction triggers the HardFault handler. While developing I configure panic and HardFault to log info about the program, or just to trigger a breakpoint if binary size is a problem. In release mode, I usually set panic to abort and make the HardFault handler disable interrupts, shut down the system (e.g. turn off motors), signal the failure (e.g. turn on a red LED) and go into an infinite loop but this is very application specific. Also, in some applications reaching an unrecoverable situation means that something is (very) wrong with your software and that it should not be deployed until it's fixed.

But you’re saying we should not, and force that question on ever no_std user. This would be one more barrier before being able to get to Hello World.

#[global_allocator] is not mandatory for #[no_std] binaries. And the oom lang item is only required when you are using #[global_allocator]. So, no, not all no_std program developers have to deal with the oom handler.

---

should there be a default?

I think there should not be a default.

If not, what should be a "typical" implementation that we’d recommend in docs?

The #![no_std] application - target space is too broad to recommend anything that will behave the same everywhere. Consider intrinsics::abort:

• on wasm means terminate executino and notify the wasm interpreter or host system
• on msp430 it causes a linker error
• on Cortex-M it defers the error handling to the HardFault exception handler
• on Linux systems it terminates the process with a SIGILL exit code

Should we add a stable wrapper for core::intrinsics::abort? (In what module?)

Yes. As core::arch::$ARCH::abort maybe? But only on architectures whose instruction sets define an abort / trap instruction.

The docs for core::intrinsics::abort claim:

Those docs should be fixed. iirc process::abort tries to does some clean up (of the Rust runtime?) before aborting the process. intrinsics::abort is an LLVM intrinsic that maps to the abort instruction of the target instruction set so the two are not equivalent.

[cr1901]

How does one typically deal with unrecoverable situations on MSP430? An infinite loop?

Infinite loop is how I typically deal w/ it. @pftbest can override me if he knows something better though, as it's been a while since I delved into msp430 internals :).

[SimonSapin]

#52191 has landed with an attribute for a statically-dispatched function, and no default.

[mark-i-m]

mm/krust/libkrust.a(alloc-062fb091d60c735a.alloc.67kypoku-cgu.11.rcgu.o): In function `alloc::alloc::handle_alloc_error':
alloc.67kypoku-cgu.11:(.text._ZN5alloc5alloc18handle_alloc_error17h59bd4dd5f11cdd3fE+0x2): undefined reference to `rust_oom'

I'm getting the above in one my projects. I have defined the handle_alloc_error function as in the OP. The code compiles just fine, but the linker cannot find the function.

[rfcbot]

🔔 This is now entering its final comment period, as per the review above. 🔔

[rfcbot]

The final comment period, with a disposition to close, as per the review above, is now complete.

As the automated representative of the governance process, I would like to thank the author for their work and everyone else who contributed.

[RalfJung]

Given that this issue is closed, why is the unstable book still listing a feature that points here?
https://doc.rust-lang.org/nightly/unstable-book/language-features/alloc-error-handler.html

[SimonSapin]

This tracking issue was closed when PR #109507 merged to remove the feature, but that was reverted in PR #110782. Reopening to reflect that.

PR #112331 is open to remove the feature again, and is already marked as closing this.