Add documentation guaranteeing global allocator use of TLS

Remove outdated part of comment claiming thread_local re-enters global allocator

Fix typo in doc comment

Add comments for guarantees given and footnote that System may still be called

Revise mention of using the global allocator

Allow for the possibility that the global allocator is the system allocator.

Co-authored-by: Mark Rousskov <[email protected]>

Author: orlp

library/core/src/alloc/global.rs

@@ -115,6 +115,31 @@ use crate::{cmp, ptr};
 ///   Whether allocations happen or not is not part of the program behavior, even if it
 ///   could be detected via an allocator that tracks allocations by printing or otherwise
 ///   having side effects.
+///
+/// # Re-entrance
+///
+/// When implementing a global allocator one has to be careful not to create an infinitely recursive
+/// implementation by accident, as many constructs in the Rust standard library may allocate in
+/// their implementation. For example, on some platforms [`std::sync::Mutex`] may allocate, so using
+/// it is highly problematic in a global allocator.
+///
+/// Generally speaking for this reason one should stick to library features available through
+/// [`core`], and avoid using [`std`] in a global allocator. A few features from [`std`] are
+/// guaranteed to not use `#[global_allocator]` to allocate:
+///
+///  - [`std::thread_local`],
+///  - [`std::thread::current`],
+///  - [`std::thread::park`] and [`std::thread::Thread`]'s [`unpark`] method and
+/// [`Clone`] implementation.
+///
+/// [`std`]: ../../std/index.html
+/// [`std::sync::Mutex`]: ../../std/sync/struct.Mutex.html
+/// [`std::thread_local`]: ../../std/macro.thread_local.html
+/// [`std::thread::current`]: ../../std/thread/fn.current.html
+/// [`std::thread::park`]: ../../std/thread/fn.park.html
+/// [`std::thread::Thread`]: ../../std/thread/struct.Thread.html
+/// [`unpark`]: ../../std/thread/struct.Thread.html#method.unpark
+
 #[stable(feature = "global_alloc", since = "1.28.0")]
 pub unsafe trait GlobalAlloc {
     /// Allocates memory as described by the given `layout`.

library/std/src/alloc.rs

@@ -11,7 +11,7 @@
 //!
 //! This attribute allows configuring the choice of global allocator.
 //! You can use this to implement a completely custom global allocator
-//! to route all default allocation requests to a custom object.
+//! to route all[^system-alloc] default allocation requests to a custom object.
 //!
 //! ```rust
 //! use std::alloc::{GlobalAlloc, System, Layout};
@@ -52,6 +52,13 @@
 //!
 //! The `#[global_allocator]` can only be used once in a crate
 //! or its recursive dependencies.
+//!
+//! [^system-alloc]: Note that the Rust standard library internals may still
+//! directly call [`System`] when necessary (for example for the runtime
+//! support typically required to implement a global allocator, see [re-entrance] on [`GlobalAlloc`]
+//! for more details).
+//!
+//! [re-entrance]: trait.GlobalAlloc.html#re-entrance
 
 #![deny(unsafe_op_in_unsafe_fn)]
 #![stable(feature = "alloc_module", since = "1.28.0")]

library/std/src/thread/current.rs

@@ -270,15 +270,16 @@ fn init_current(current: *mut ()) -> Thread {
         // extra TLS write above shouldn't matter. The alternative is nearly always
         // a stack overflow.
 
-        // If you came across this message, contact the author of your allocator.
-        // If you are said author: A surprising amount of functions inside the
-        // standard library (e.g. `Mutex`, `thread_local!`, `File` when using long
-        // paths, even `panic!` when using unwinding), need memory allocation, so
-        // you'll get circular dependencies all over the place when using them.
-        // I (joboet) highly recommend using only APIs from core in your allocator
-        // and implementing your own system abstractions. Still, if you feel that
-        // a particular API should be entirely allocation-free, feel free to open
-        // an issue on the Rust repository, we'll see what we can do.
+        // If you came across this message, contact the author of your
+        // allocator. If you are said author: A surprising amount of functions
+        // inside the standard library (e.g. `Mutex`, `File` when using long
+        // paths, even `panic!` when using unwinding), need memory allocation,
+        // so you'll get circular dependencies all over the place when using
+        // them. I (joboet) highly recommend using only APIs from core in your
+        // allocator and implementing your own system abstractions. Still, if
+        // you feel that a particular API should be entirely allocation-free,
+        // feel free to open an issue on the Rust repository, we'll see what we
+        // can do.
         rtabort!(
             "\n\
             Attempted to access thread-local data while allocating said data.\n\

library/std/src/thread/local.rs

@@ -24,12 +24,17 @@ use crate::fmt;
 /// [`with`]) within a thread, and values that implement [`Drop`] get
 /// destructed when a thread exits. Some platform-specific caveats apply, which
 /// are explained below.
-/// Note that if the destructor panics, the whole process will be [aborted].
+/// Note that, should the destructor panic, the whole process will be [aborted].
+/// On platforms where initialization requires memory allocation, this is
+/// performed directly through [`System`], allowing the [global allocator]
+/// to make use of thread local storage.
 ///
 /// A `LocalKey`'s initializer cannot recursively depend on itself. Using a
 /// `LocalKey` in this way may cause panics, aborts, or infinite recursion on
 /// the first call to `with`.
 ///
+/// [`System`]: crate::alloc::System
+/// [global allocator]: crate::alloc
 /// [aborted]: crate::process::abort
 ///
 /// # Single-thread Synchronization