Rollup merge of rust-lang#45217 - SimonSapin:alloc-doc, r=steveklabnik

Fix out of date unstable book entries for `alloc_*` features.

The `alloc_jemalloc` crate does not provide a type to use with `#[global_allocator]`, and (according to Alex) `extern crate alloc_jemalloc;` alone became a no-op when `#[global_allocator]` was introduced.

src/doc/unstable-book/src/library-features/alloc-jemalloc.md

@@ -8,55 +8,6 @@ See also [`alloc_system`](library-features/alloc-system.html).
 
 ------------------------
 
-The compiler currently ships two default allocators: `alloc_system` and
-`alloc_jemalloc` (some targets don't have jemalloc, however). These allocators
-are normal Rust crates and contain an implementation of the routines to
-allocate and deallocate memory. The standard library is not compiled assuming
-either one, and the compiler will decide which allocator is in use at
-compile-time depending on the type of output artifact being produced.
-
-Binaries generated by the compiler will use `alloc_jemalloc` by default (where
-available). In this situation the compiler "controls the world" in the sense of
-it has power over the final link. Primarily this means that the allocator
-decision can be left up the compiler.
-
-Dynamic and static libraries, however, will use `alloc_system` by default. Here
-Rust is typically a 'guest' in another application or another world where it
-cannot authoritatively decide what allocator is in use. As a result it resorts
-back to the standard APIs (e.g. `malloc` and `free`) for acquiring and releasing
-memory.
-
-# Switching Allocators
-
-Although the compiler's default choices may work most of the time, it's often
-necessary to tweak certain aspects. Overriding the compiler's decision about
-which allocator is in use is done simply by linking to the desired allocator:
-
-```rust,no_run
-#![feature(alloc_system)]
-
-extern crate alloc_system;
-
-fn main() {
-    let a = Box::new(4); // Allocates from the system allocator.
-    println!("{}", a);
-}
-```
-
-In this example the binary generated will not link to jemalloc by default but
-instead use the system allocator. Conversely to generate a dynamic library which
-uses jemalloc by default one would write:
-
-```rust,ignore
-#![feature(alloc_jemalloc)]
-#![crate_type = "dylib"]
-
-extern crate alloc_jemalloc;
-
-pub fn foo() {
-    let a = Box::new(4); // Allocates from jemalloc.
-    println!("{}", a);
-}
-# fn main() {}
-```
+This feature has been replaced by [the `jemallocator` crate on crates.io.][jemallocator].
 
+[jemallocator]: https://crates.io/crates/jemallocator

src/doc/unstable-book/src/library-features/alloc-system.md

@@ -1,10 +1,10 @@
 # `alloc_system`
 
-The tracking issue for this feature is: [#33082]
+The tracking issue for this feature is: [#32838]
 
-[#33082]: https://github.com/rust-lang/rust/issues/33082
+[#32838]: https://github.com/rust-lang/rust/issues/32838
 
-See also [`alloc_jemalloc`](library-features/alloc-jemalloc.html).
+See also [`global_allocator`](language-features/global-allocator.html).
 
 ------------------------
 
@@ -30,13 +30,18 @@ memory.
 
 Although the compiler's default choices may work most of the time, it's often
 necessary to tweak certain aspects. Overriding the compiler's decision about
-which allocator is in use is done simply by linking to the desired allocator:
+which allocator is in use is done through the `#[global_allocator]` attribute:
 
 ```rust,no_run
-#![feature(alloc_system)]
+#![feature(alloc_system, global_allocator, allocator_api)]
 
 extern crate alloc_system;
 
+use alloc_system::System;
+
+#[global_allocator]
+static A: System = System;
+
 fn main() {
     let a = Box::new(4); // Allocates from the system allocator.
     println!("{}", a);
@@ -47,16 +52,26 @@ In this example the binary generated will not link to jemalloc by default but
 instead use the system allocator. Conversely to generate a dynamic library which
 uses jemalloc by default one would write:
 
+(The `alloc_jemalloc` crate cannot be used to control the global allocator,
+crate.io’s `jemallocator` crate provides equivalent functionality.)
+
+```toml
+# Cargo.toml
+[dependencies]
+jemallocator = "0.1"
+```
 ```rust,ignore
-#![feature(alloc_jemalloc)]
+#![feature(global_allocator)]
 #![crate_type = "dylib"]
 
-extern crate alloc_jemalloc;
+extern crate jemallocator;
+
+#[global_allocator]
+static ALLOC: jemallocator::Jemalloc = jemallocator::Jemalloc;
 
 pub fn foo() {
     let a = Box::new(4); // Allocates from jemalloc.
     println!("{}", a);
 }
 # fn main() {}
 ```
-

src/liballoc_system/lib.rs

@@ -14,7 +14,7 @@
 #![unstable(feature = "alloc_system",
             reason = "this library is unlikely to be stabilized in its current \
                       form or name",
-            issue = "27783")]
+            issue = "32838")]
 #![feature(global_allocator)]
 #![feature(allocator_api)]
 #![feature(alloc)]