Rename .cap() methods to .capacity()
As mentioned in #60316, there are a few `.cap()` methods, which seem out-of-place because such methods are called `.capacity()` in the rest of the code.
This PR renames them to `.capacity()` but leaves `RawVec::cap()` in there for backwards compatibility.
I didn't try to mark the old version as "deprecated", because I guess this would cause too much noise.
The acronym is not descriptive unless one has seen it before.
* Rename the `oom` function to `handle_alloc_error`. It was **stabilized in 1.28**, so if we do this at all we need to land it this cycle.
* Rename `set_oom_hook` to `set_alloc_error_hook`
* Rename `take_oom_hook` to `take_alloc_error_hook`
Bikeshed: `alloc` v.s. `allocator`, `error` v.s. `failure`
As discussed in
https://github.com/rust-lang/rust/issues/49668#issuecomment-384893456
and subsequent, there are use-cases where the OOM handler needs to know
the size of the allocation that failed. The alignment might also be a
cause for allocation failure, so providing it as well can be useful.
When the RawVec::try_reserve* methods were added, they took the place of
the ::reserve* methods in the source file, and new ::reserve* methods
wrapping the new try_reserve* methods were created. But the
documentation didn't move along, such that:
- reserve_* methods are barely documented.
- try_reserve_* methods have unmodified documentation from reserve_*,
such that their documentation indicate they are panicking/aborting.
This moves the documentation back to the right methods, with a
placeholder documentation for the try_reserve* methods.
std: Minimize size of panicking on wasm
This commit applies a few code size optimizations for the wasm target to
the standard library, namely around panics. We notably know that in most
configurations it's impossible for us to print anything in
wasm32-unknown-unknown so we can skip larger portions of panicking that
are otherwise simply informative. This allows us to get quite a nice
size reduction.
Finally we can also tweak where the allocation happens for the
`Box<Any>` that we panic with. By only allocating once unwinding starts
we can reduce the size of a panicking wasm module from 44k to 350 bytes.
Some modules were still using the deprecated `allocator` module, use the
`alloc` module instead.
Some modules were using `super` while it's not needed.
Some modules were more or less ordering them, and other not, so the
latter have been modified to match the others.
Create one canonical location which panics with "capacity overflow" instead of
having many. This reduces the size of a `panic!("{}", 1)` binary on wasm from
34k to 17k.
94d1970bba moved the alloc::allocator
module to core::heap, moving e.g. Alloc and Layout out of the alloc
crate. While alloc::heap reexports them, it's better to use them from
where they really come from.
