Auto merge of #42313 - pnkfelix:allocator-integration, r=alexcrichton

Allocator integration

Lets start getting some feedback on `trait Alloc`.

Here is:
 *  the `trait Alloc` itself,
 * the `struct Layout` and `enum AllocErr` that its API relies on
 * a `struct HeapAlloc` that exposes the system allocator as an instance of `Alloc`
 * an integration of `Alloc` with `RawVec`
 * ~~an integration of `Alloc` with `Vec`~~

 TODO
 * [x] split `fn realloc_in_place` into `grow` and `shrink` variants
 * [x] add `# Unsafety` and `# Errors` sections to documentation for all relevant methods
 * [x] remove `Vec` integration with `Allocator`
 * [x] add `allocate_zeroed` impl to `HeapAllocator`
 * [x] remove typedefs e.g. `type Size = usize;`
 * [x] impl `trait Error` for all error types in PR
 * [x] make `Layout::from_size_align` public
 * [x] clarify docs of `fn padding_needed_for`.
 * [x] revise `Layout` constructors to ensure that [size+align combination is valid](#42313 (comment))
 * [x] resolve mismatch re requirements of align on dealloc. See [comment](#42313 (comment)).

Author: bors

src/doc/unstable-book/src/library-features/allocator-api.md

@@ -0,0 +1,15 @@
+# `allocator_api`
+
+The tracking issue for this feature is [#32838]
+
+[#32838]: https://github.com/rust-lang/rust/issues/32838
+
+------------------------
+
+Sometimes you want the memory for one collection to use a different
+allocator than the memory for another collection. In this case,
+replacing the global allocator is not a workable option. Instead,
+you need to pass in an instance of an `Alloc` to each collection
+for which you want a custom allocator.
+
+TBD