diff options
author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-05-30 18:31:44 +0000 |
---|---|---|
committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-05-30 18:31:44 +0000 |
commit | c23a457e72abe608715ac76f076f47dc42af07a5 (patch) | |
tree | 2772049aaf84b5c9d0ed12ec8d86812f7a7904b6 /library/std/src/alloc.rs | |
parent | Releasing progress-linux version 1.73.0+dfsg1-1~progress7.99u1. (diff) | |
download | rustc-c23a457e72abe608715ac76f076f47dc42af07a5.tar.xz rustc-c23a457e72abe608715ac76f076f47dc42af07a5.zip |
Merging upstream version 1.74.1+dfsg1.
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'library/std/src/alloc.rs')
-rw-r--r-- | library/std/src/alloc.rs | 26 |
1 files changed, 20 insertions, 6 deletions
diff --git a/library/std/src/alloc.rs b/library/std/src/alloc.rs index 1eae7fa6a..bb786bd59 100644 --- a/library/std/src/alloc.rs +++ b/library/std/src/alloc.rs @@ -290,15 +290,29 @@ static HOOK: AtomicPtr<()> = AtomicPtr::new(ptr::null_mut()); /// Registers a custom allocation error hook, replacing any that was previously registered. /// -/// The allocation error hook is invoked when an infallible memory allocation fails, before -/// the runtime aborts. The default hook prints a message to standard error, -/// but this behavior can be customized with the [`set_alloc_error_hook`] and -/// [`take_alloc_error_hook`] functions. +/// The allocation error hook is invoked when an infallible memory allocation fails — that is, +/// as a consequence of calling [`handle_alloc_error`] — before the runtime aborts. /// -/// The hook is provided with a `Layout` struct which contains information +/// The allocation error hook is a global resource. [`take_alloc_error_hook`] may be used to +/// retrieve a previously registered hook and wrap or discard it. +/// +/// # What the provided `hook` function should expect +/// +/// The hook function is provided with a [`Layout`] struct which contains information /// about the allocation that failed. /// -/// The allocation error hook is a global resource. +/// The hook function may choose to panic or abort; in the event that it returns normally, this +/// will cause an immediate abort. +/// +/// Since [`take_alloc_error_hook`] is a safe function that allows retrieving the hook, the hook +/// function must be _sound_ to call even if no memory allocations were attempted. +/// +/// # The default hook +/// +/// The default hook, used if [`set_alloc_error_hook`] is never called, prints a message to +/// standard error (and then returns, causing the runtime to abort the process). +/// Compiler options may cause it to panic instead, and the default behavior may be changed +/// to panicking in future versions of Rust. /// /// # Examples /// |