Clarify that `handle_alloc_error` may unwind

[kpreid]

Location

• https://doc.rust-lang.org/alloc/alloc/fn.handle_alloc_error.html
• https://doc.rust-lang.org/std/alloc/fn.set_alloc_error_hook.html

Summary

handle_alloc_error's documentation says:

Abort on memory allocation error or failure.

However,

1. it is also specified to call the hook set with set_alloc_error_hook() (unstable) which per its example is permitted to panic and thereby potentially unwind, and
2. per Announcing Rust 1.68.0, a “likely” future version of std might choose to panic on allocation failure instead.

Therefore, the documentation should be changed to not imply that this function will always abort, which could be taken as a promise that it will never unwind.

It also might be useful to expand the documentation of set_alloc_error_hook() so that the text and not only the example code specifies that it's okay to unwind from the hook (and what happens if you don't). (See also #56965 which is broader but doesn't mention this aspect.)

cc @xTachyon from discussion in Rust Community Discord

@rustbot label +A-allocators +T-libs-api

[kpreid]

@rustbot claim