Update docs for std::alloc to show how to turn on the system allocator

[brson]

On nightly/beta the global allocator API is enabled, but jemalloc is still the default. This does not seem to be indicated in the documentation though. This change makes it clear that jemalloc is the default allocator for executables on Unixes and shows how to instead enable the system allocator.

If this pull is accepted it should be backported to beta. Somebody please tag it as appropriate.

r? @steveklabnik

[brson]

Here's a PR against the reference: rust-lang/reference#367

[rust-highfive]

The job x86_64-gnu-llvm-3.9 of your PR failed on Travis (raw log). Through arcane magic we have determined that the following fragments from the build log may contain information about the problem.

Click to expand the log.

[01:16:23] 
[01:16:23]    Doc-tests std
[01:16:25] 
[01:16:25] running 931 tests
[01:16:58] iiFi................................................................................................
[01:17:29] ......i......i...i......i...........................................................................
[01:17:38] ....................................................................................................
[01:17:54] .....................iiii........ii.................................................................
[01:18:03] ....................................................................................................
---
[01:18:59] ---- alloc.rs - alloc (line 28) stdout ----
[01:18:59] error[E0432]: unresolved import `super::GLOBAL`
[01:18:59]  --> alloc.rs:30:1
[01:18:59]   |
[01:18:59] 5 | static GLOBAL: std::alloc::System = std::alloc::System;
[01:18:59]   | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ no `GLOBAL` in the root
[01:18:59] 
[01:18:59] thread 'alloc.rs - alloc (line 28)' panicked at 'assertion failed: prev.is_none()', librustc/middle/region.rs:509:13
[01:18:59] thread 'alloc.rs - alloc (line 28)' panicked at 'couldn't compile the test', librustdoc/test.rs:327:17
[01:18:59] 
[01:18:59] 
[01:18:59] failures:
[01:18:59] failures:
[01:18:59]     alloc.rs - alloc (line 28)
[01:18:59] 
[01:18:59] test result: FAILED. 906 passed; 1 failed; 24 ignored; 0 measured; 0 filtered out
[01:18:59] 
[01:18:59] error: test failed, to rerun pass '--doc'
[01:18:59] 
[01:18:59] 
[01:18:59] command did not execute successfully: "/checkout/obj/build/x86_64-unknown-linux-gnu/stage0/bin/cargo" "test" "--target" "x86_64-unknown-linux-gnu" "-j" "4" "--release" "--locked" "--color" "always" "--features" "panic-unwind jemalloc backtrace" "--manifest-path" "/checkout/src/libstd/Cargo.toml" "-p" "std" "--" "--quiet"
[01:18:59] 
[01:18:59] 
[01:18:59] failed to run: /checkout/obj/build/bootstrap/debug/bootstrap test
[01:18:59] Build completed unsuccessfully in 0:36:34
[01:18:59] Build completed unsuccessfully in 0:36:34
[01:18:59] make: *** [check] Error 1
[01:18:59] Makefile:58: recipe for target 'check' failed

The command "stamp sh -x -c "$RUN_SCRIPT"" exited with 2.
travis_time:start:182bbb78
$ date && (curl -fs --head https://google.com | grep ^Date: | sed 's/Date: //g' || true)

I'm a bot! I can only do what humans tell me to, so if this was not helpful or you have suggestions for improvements, please ping or otherwise contact @TimNN. (Feature Requests)

[steveklabnik]

@rust-lang/libs, is this something we want to do? my understanding is that

-//! Currently the default global allocator is unspecified.

because we want to switch to the system allocator.

[SimonSapin]

I think it’s fine to document the current reality as long as docs are clear that it is unspecified and expected to change in future versions. So rather than a note at the bottom I’d prefer leading with that, and then explaining what is current.

[alexcrichton]

I'd agree with @SimonSapin in that it should be fine to document reality so long as there's a lot of notes and caveats saying so and that it's subject to change (perhaps with links to tracking issues)

[stokhos]

Ping from triage @brson, any progress on this PR?

[TimNN]

Ping from triage, @brson: What is the status of this PR?

[pietroalbini]

Ping @brson, 1.28 will be released in a week, can you make the requested changes soon?

[TimNN]

Ping from triage @brson! We haven't heard from you in a while so I'm closing this PR for now. Please re-open it when you have time to work on it again.