@@ -343,18 +343,31 @@ extern "Rust" {
343
343
fn __rust_alloc_error_handler ( size : usize , align : usize ) -> !;
344
344
}
345
345
346
- /// Abort on memory allocation error or failure .
346
+ /// Signal a memory allocation error.
347
347
///
348
- /// Callers of memory allocation APIs wishing to abort computation
348
+ /// Callers of memory allocation APIs wishing to cease execution
349
349
/// in response to an allocation error are encouraged to call this function,
350
- /// rather than directly invoking `panic!` or similar.
350
+ /// rather than directly invoking [ `panic!`] or similar.
351
351
///
352
- /// The default behavior of this function is to print a message to standard error
353
- /// and abort the process.
354
- /// It can be replaced with [`set_alloc_error_hook`] and [`take_alloc_error_hook`].
352
+ /// This function is guaranteed to diverge (not return normally with a value), but depending on
353
+ /// global configuration, it may either panic (resulting in unwinding or aborting as per
354
+ /// configuration for all panics), or abort the process (with no unwinding).
355
+ ///
356
+ /// The default behavior is:
357
+ ///
358
+ /// * If the binary links against `std` (typically the case), then
359
+ /// print a message to standard error and abort the process.
360
+ /// This behavior can be replaced with [`set_alloc_error_hook`] and [`take_alloc_error_hook`].
361
+ /// Future versions of Rust may panic by default instead.
362
+ ///
363
+ /// * If the binary does not link against `std` (all of its crates are marked
364
+ /// [`#![no_std]`][no_std]), then call [`panic!`] with a message.
365
+ /// [The panic handler] applies as to any panic.
355
366
///
356
367
/// [`set_alloc_error_hook`]: ../../std/alloc/fn.set_alloc_error_hook.html
357
368
/// [`take_alloc_error_hook`]: ../../std/alloc/fn.take_alloc_error_hook.html
369
+ /// [The panic handler]: https://doc.rust-lang.org/reference/runtime.html#the-panic_handler-attribute
370
+ /// [no_std]: https://doc.rust-lang.org/reference/names/preludes.html#the-no_std-attribute
358
371
#[ stable( feature = "global_alloc" , since = "1.28.0" ) ]
359
372
#[ rustc_const_unstable( feature = "const_alloc_error" , issue = "92523" ) ]
360
373
#[ cfg( all( not( no_global_oom_handling) , not( test) ) ) ]
0 commit comments