From e30ee537e1ad23ca44fbaa65cc3890584f2081b7 Mon Sep 17 00:00:00 2001 From: Brian Anderson Date: Sun, 1 Jul 2018 15:26:48 -0700 Subject: [PATCH] Update docs for std::alloc to show how to turn on the system allocator --- src/libstd/alloc.rs | 31 +++++++++++++++++++++++-------- 1 file changed, 23 insertions(+), 8 deletions(-) diff --git a/src/libstd/alloc.rs b/src/libstd/alloc.rs index f28e91e19b73c..a11452b9a06ac 100644 --- a/src/libstd/alloc.rs +++ b/src/libstd/alloc.rs @@ -10,14 +10,29 @@ //! Memory allocation APIs //! -//! In a given program, the standard library has one “global” memory allocator -//! that is used for example by `Box` and `Vec`. -//! -//! Currently the default global allocator is unspecified. -//! The compiler may link to a version of [jemalloc] on some platforms, -//! but this is not guaranteed. -//! Libraries, however, like `cdylib`s and `staticlib`s are guaranteed -//! to use the [`System`] by default. +//! In a given program, the standard library has one global memory allocator +//! that allocates space on the heap for types like `Box` and `Vec`. +//! It is similar in function to `malloc` in C. +//! +//! The global memory allocator is typically provided either by the operating +//! system's default allocator (the [`System`] allocator), or by [jemalloc], a +//! high-performance allocator tuned for parallel workloads. +//! +//! On Mac OS X, Linux and most Unixes (but not Windows), jemalloc is the +//! default allocator for executables. `cdylib`s and `staticlib`s however always +//! use the system allocator for compatibility with their host programs. +//! +//! The following overrides the default jemalloc-based allocator and +//! instead uses the system allocator for global allocations. +//! +//! ```rust +//! #[global_allocator] +//! static GLOBAL: std::alloc::System = std::alloc::System; +//! ``` +//! +//! Note: in the future the default allocator for all platforms +//! will be the system allocator, and external crates will +//! provide alternative allocators, including jemalloc. //! //! [jemalloc]: https://github.com/jemalloc/jemalloc //! [`System`]: struct.System.html