Make explicit guarantees about `Vec`’s allocator #145260

SabrinaJewson · 2025-08-11T16:17:29Z

This commit amends the documentation of Vec::as_mut_ptr and Vec::into_raw_parts to make it explicit that such calls may be paired with calls to dealloc with a suitable layout. This guarantee was effectively already provided by the docs of Vec::from_raw_parts mentioning alloc.

Additionally, we copy-paste and adjust the “Memory layout” section from the documentation of std::boxed to std::vec. This explains the allocator guarantees in more detail.

This commit amends the documentation of `Vec::as_mut_ptr` and `Vec::into_raw_parts` to make it explicit that such calls may be paired with calls to `dealloc` with a suitable layout. This guarantee was effectively already provided by the docs of `Vec::from_raw_parts` mentioning `alloc`. Additionally, we copy-paste and adjust the “Memory layout” section from the documentation of `std::boxed` to `std::vec`. This explains the allocator guarantees in more detail.

rustbot · 2025-08-11T16:17:34Z

r? @ibraheemdev

rustbot has assigned @ibraheemdev.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

Kivooeo

Some nits

library/alloc/src/vec/mod.rs

ibraheemdev · 2025-08-11T17:09:42Z

r? libs-api

dtolnay

This guarantee was effectively already provided by the docs of Vec::from_raw_parts mentioning alloc.

This is also my understanding. If you can feed an arbitrary heap allocation into Vec::from_raw_parts and get it back from into_raw_parts / as_mut_ptr / capacity, it's effectively a guarantee that these things can be deallocated in the obvious way.

There is one other piece required to complete the argument. The above by itself does not guarantee that a ZST vector ptr is fine to "leak" as written in this PR: "and if T is zero-sized nothing needs to be done". This scenario falls outside any consequences drawn from from_raw_parts because from_raw_parts is documented as follows: "ptr must have been allocated using the global allocator, such as via the alloc::alloc function", and allocating a zero-sized layout with a global allocator is documented as being UB. If Vec somehow allocated nonzero size internally for ZST vectors, this PR would be a new guarantee. But there is plenty of existing documentation that Vec does not allocate for ZST.

Hypothetically, dropping a vector of ZST could require some other non-allocator thing, such as std::internal::decrement_outstanding_zst_vectors(). But this is pretty outlandish and I do not believe we require a team consensus to rule this out.

Thank you for the improvements!

Separately, it would be good to update the documentation of from_raw_parts to speak about the ZST case. As currently written, it seems to imply round-tripping into_raw_parts -> from_raw_parts can be UB, which is not the intention.

dtolnay · 2025-08-11T18:41:32Z

@bors r+ rollup

bors · 2025-08-11T18:41:34Z

📌 Commit 45e2449 has been approved by dtolnay

It is now in the queue for this repository.

…r=dtolnay Make explicit guarantees about `Vec`’s allocator This commit amends the documentation of `Vec::as_mut_ptr` and `Vec::into_raw_parts` to make it explicit that such calls may be paired with calls to `dealloc` with a suitable layout. This guarantee was effectively already provided by the docs of `Vec::from_raw_parts` mentioning `alloc`. Additionally, we copy-paste and adjust the “Memory layout” section from the documentation of `std::boxed` to `std::vec`. This explains the allocator guarantees in more detail.

theemathas · 2025-08-12T01:38:29Z

This PR is incorrect. It needs to mention the case where the Vec is zero-length in addition to the case where T is zero-sized.

Rollup of 15 pull requests Successful merges: - #131477 (Apple: Always pass SDK root when linking with `cc`, and pass it via `SDKROOT` env var) - #139806 (std: sys: pal: uefi: Overhaul Time) - #144386 (Extract TraitImplHeader in AST/HIR) - #144542 (Stabilize `sse4a` and `tbm` target features) - #144921 (Don't emit `rustdoc::broken_intra_doc_links` for GitHub-flavored Markdown admonitions like `[!NOTE]`) - #145155 (Port `#[allow_internal_unsafe]` to the new attribute system (attempt 2)) - #145214 (fix: re-enable self-assignment) - #145216 (rustdoc: correct negative-to-implicit discriminant display) - #145238 (Tweak invalid builtin attribute output) - #145249 (Rename entered trace span variables from `_span` to `_trace`) - #145251 (Support using #[unstable_feature_bound] on trait) - #145253 (Document compiler and stdlib in stage1 in `pr-check-2` CI job) - #145260 (Make explicit guarantees about `Vec`’s allocator) - #145263 (Update books) - #145273 (Account for new `assert!` desugaring in `!condition` suggestion) r? `@ghost` `@rustbot` modify labels: rollup

fmease · 2025-08-12T02:19:07Z

The overarching rollup is 20mins in (out if ~3h15 total). If theemathas's concern is valid, either r- now-ish or wait for the rollup to fail or get merged (in the latter case: plz open a follow-up PR instead). Either way, don't push before an r-.

fmease · 2025-08-12T02:38:26Z

Ok, rollup failed. I'll tangentially r- this due to the concern raised in #145260 (comment) (of which I don't know if it is valid).
@bors r-

SabrinaJewson · 2025-08-12T04:13:28Z

The comment is correct – that’s an oversight on my part. I also updated the docs of Vec::from_raw_parts while I was at it.

dtolnay · 2025-08-12T04:21:31Z

@bors r+

bors · 2025-08-12T04:21:33Z

📌 Commit 1ce4b37 has been approved by dtolnay

It is now in the queue for this repository.

…r=dtolnay Make explicit guarantees about `Vec`’s allocator This commit amends the documentation of `Vec::as_mut_ptr` and `Vec::into_raw_parts` to make it explicit that such calls may be paired with calls to `dealloc` with a suitable layout. This guarantee was effectively already provided by the docs of `Vec::from_raw_parts` mentioning `alloc`. Additionally, we copy-paste and adjust the “Memory layout” section from the documentation of `std::boxed` to `std::vec`. This explains the allocator guarantees in more detail.

Rollup of 17 pull requests Successful merges: - #131477 (Apple: Always pass SDK root when linking with `cc`, and pass it via `SDKROOT` env var) - #139806 (std: sys: pal: uefi: Overhaul Time) - #144210 (std: thread: Return error if setting thread stack size fails) - #144386 (Extract TraitImplHeader in AST/HIR) - #144921 (Don't emit `rustdoc::broken_intra_doc_links` for GitHub-flavored Markdown admonitions like `[!NOTE]`) - #145155 (Port `#[allow_internal_unsafe]` to the new attribute system (attempt 2)) - #145214 (fix: re-enable self-assignment) - #145216 (rustdoc: correct negative-to-implicit discriminant display) - #145238 (Tweak invalid builtin attribute output) - #145249 (Rename entered trace span variables from `_span` to `_trace`) - #145251 (Support using #[unstable_feature_bound] on trait) - #145253 (Document compiler and stdlib in stage1 in `pr-check-2` CI job) - #145260 (Make explicit guarantees about `Vec`’s allocator) - #145263 (Update books) - #145273 (Account for new `assert!` desugaring in `!condition` suggestion) - #145283 (Make I-miscompile imply I-prioritize) - #145291 (bootstrap: Only warn about `rust.debug-assertions` if downloading rustc) r? `@ghost` `@rustbot` modify labels: rollup

the8472 · 2025-08-12T11:16:49Z

library/alloc/src/vec/mod.rs

+    /// ```
+    /// use std::mem::{ManuallyDrop, MaybeUninit};
+    ///
+    /// let mut v = ManuallyDrop::new(vec![0, 1, 2]);


Maybe it'd be a better example to use types that are Drop and run drop_in_place with the right amount of data before deallocating. Otherwise one would cause leaks by following this pattern.

Rollup of 17 pull requests Successful merges: - #131477 (Apple: Always pass SDK root when linking with `cc`, and pass it via `SDKROOT` env var) - #139806 (std: sys: pal: uefi: Overhaul Time) - #144386 (Extract TraitImplHeader in AST/HIR) - #144921 (Don't emit `rustdoc::broken_intra_doc_links` for GitHub-flavored Markdown admonitions like `[!NOTE]`) - #145155 (Port `#[allow_internal_unsafe]` to the new attribute system (attempt 2)) - #145214 (fix: re-enable self-assignment) - #145216 (rustdoc: correct negative-to-implicit discriminant display) - #145238 (Tweak invalid builtin attribute output) - #145249 (Rename entered trace span variables from `_span` to `_trace`) - #145251 (Support using #[unstable_feature_bound] on trait) - #145253 (Document compiler and stdlib in stage1 in `pr-check-2` CI job) - #145260 (Make explicit guarantees about `Vec`’s allocator) - #145263 (Update books) - #145273 (Account for new `assert!` desugaring in `!condition` suggestion) - #145283 (Make I-miscompile imply I-prioritize) - #145291 (bootstrap: Only warn about `rust.debug-assertions` if downloading rustc) - #145292 (Fix a typo in range docs) r? `@ghost` `@rustbot` modify labels: rollup

Rollup merge of #145260 - SabrinaJewson:vec-allocator-docs, r=dtolnay Make explicit guarantees about `Vec`’s allocator This commit amends the documentation of `Vec::as_mut_ptr` and `Vec::into_raw_parts` to make it explicit that such calls may be paired with calls to `dealloc` with a suitable layout. This guarantee was effectively already provided by the docs of `Vec::from_raw_parts` mentioning `alloc`. Additionally, we copy-paste and adjust the “Memory layout” section from the documentation of `std::boxed` to `std::vec`. This explains the allocator guarantees in more detail.

Rollup of 17 pull requests Successful merges: - rust-lang/rust#131477 (Apple: Always pass SDK root when linking with `cc`, and pass it via `SDKROOT` env var) - rust-lang/rust#139806 (std: sys: pal: uefi: Overhaul Time) - rust-lang/rust#144386 (Extract TraitImplHeader in AST/HIR) - rust-lang/rust#144921 (Don't emit `rustdoc::broken_intra_doc_links` for GitHub-flavored Markdown admonitions like `[!NOTE]`) - rust-lang/rust#145155 (Port `#[allow_internal_unsafe]` to the new attribute system (attempt 2)) - rust-lang/rust#145214 (fix: re-enable self-assignment) - rust-lang/rust#145216 (rustdoc: correct negative-to-implicit discriminant display) - rust-lang/rust#145238 (Tweak invalid builtin attribute output) - rust-lang/rust#145249 (Rename entered trace span variables from `_span` to `_trace`) - rust-lang/rust#145251 (Support using #[unstable_feature_bound] on trait) - rust-lang/rust#145253 (Document compiler and stdlib in stage1 in `pr-check-2` CI job) - rust-lang/rust#145260 (Make explicit guarantees about `Vec`’s allocator) - rust-lang/rust#145263 (Update books) - rust-lang/rust#145273 (Account for new `assert!` desugaring in `!condition` suggestion) - rust-lang/rust#145283 (Make I-miscompile imply I-prioritize) - rust-lang/rust#145291 (bootstrap: Only warn about `rust.debug-assertions` if downloading rustc) - rust-lang/rust#145292 (Fix a typo in range docs) r? `@ghost` `@rustbot` modify labels: rollup

…r=dtolnay Make explicit guarantees about `Vec`’s allocator This commit amends the documentation of `Vec::as_mut_ptr` and `Vec::into_raw_parts` to make it explicit that such calls may be paired with calls to `dealloc` with a suitable layout. This guarantee was effectively already provided by the docs of `Vec::from_raw_parts` mentioning `alloc`. Additionally, we copy-paste and adjust the “Memory layout” section from the documentation of `std::boxed` to `std::vec`. This explains the allocator guarantees in more detail.

Rollup of 17 pull requests Successful merges: - rust-lang/rust#131477 (Apple: Always pass SDK root when linking with `cc`, and pass it via `SDKROOT` env var) - rust-lang/rust#139806 (std: sys: pal: uefi: Overhaul Time) - rust-lang/rust#144386 (Extract TraitImplHeader in AST/HIR) - rust-lang/rust#144921 (Don't emit `rustdoc::broken_intra_doc_links` for GitHub-flavored Markdown admonitions like `[!NOTE]`) - rust-lang/rust#145155 (Port `#[allow_internal_unsafe]` to the new attribute system (attempt 2)) - rust-lang/rust#145214 (fix: re-enable self-assignment) - rust-lang/rust#145216 (rustdoc: correct negative-to-implicit discriminant display) - rust-lang/rust#145238 (Tweak invalid builtin attribute output) - rust-lang/rust#145249 (Rename entered trace span variables from `_span` to `_trace`) - rust-lang/rust#145251 (Support using #[unstable_feature_bound] on trait) - rust-lang/rust#145253 (Document compiler and stdlib in stage1 in `pr-check-2` CI job) - rust-lang/rust#145260 (Make explicit guarantees about `Vec`’s allocator) - rust-lang/rust#145263 (Update books) - rust-lang/rust#145273 (Account for new `assert!` desugaring in `!condition` suggestion) - rust-lang/rust#145283 (Make I-miscompile imply I-prioritize) - rust-lang/rust#145291 (bootstrap: Only warn about `rust.debug-assertions` if downloading rustc) - rust-lang/rust#145292 (Fix a typo in range docs) r? `@ghost` `@rustbot` modify labels: rollup

rustbot assigned ibraheemdev Aug 11, 2025

rustbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. T-libs Relevant to the library team, which will review and decide on the PR/issue. labels Aug 11, 2025

Kivooeo reviewed Aug 11, 2025

View reviewed changes

rustbot added the T-libs-api Relevant to the library API team, which will review and decide on the PR/issue. label Aug 11, 2025

rustbot assigned dtolnay and unassigned ibraheemdev Aug 11, 2025

Respond to review comments

45e2449

dtolnay approved these changes Aug 11, 2025

View reviewed changes

bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Aug 11, 2025

fmease mentioned this pull request Aug 11, 2025

Rollup of 16 pull requests #145280

Closed

fmease mentioned this pull request Aug 12, 2025

Rollup of 15 pull requests #145281

Closed

fmease mentioned this pull request Aug 12, 2025

Rollup of 15 pull requests #145282

Closed

bors added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. labels Aug 12, 2025

Handle the capacity == 0 case

1ce4b37

dtolnay approved these changes Aug 12, 2025

View reviewed changes

bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Aug 12, 2025

Zalathar mentioned this pull request Aug 12, 2025

Rollup of 17 pull requests #145293

Closed

Zalathar mentioned this pull request Aug 12, 2025

Rollup of 17 pull requests #145300

Merged

the8472 reviewed Aug 12, 2025

View reviewed changes

bors merged commit 30ed54e into rust-lang:master Aug 12, 2025
10 checks passed

rustbot added this to the 1.91.0 milestone Aug 12, 2025

SabrinaJewson deleted the vec-allocator-docs branch August 12, 2025 17:04

Make explicit guarantees about Vec’s allocator #145260

Make explicit guarantees about Vec’s allocator #145260

Uh oh!

Conversation

SabrinaJewson commented Aug 11, 2025

Uh oh!

rustbot commented Aug 11, 2025

Uh oh!

Kivooeo left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ibraheemdev commented Aug 11, 2025

Uh oh!

dtolnay left a comment

Choose a reason for hiding this comment

Uh oh!

dtolnay commented Aug 11, 2025

Uh oh!

bors commented Aug 11, 2025

Uh oh!

theemathas commented Aug 12, 2025

Uh oh!

fmease commented Aug 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

fmease commented Aug 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

SabrinaJewson commented Aug 12, 2025

Uh oh!

dtolnay commented Aug 12, 2025

Uh oh!

bors commented Aug 12, 2025

Uh oh!

the8472 Aug 12, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Make explicit guarantees about `Vec`’s allocator #145260

Make explicit guarantees about `Vec`’s allocator #145260

fmease commented Aug 12, 2025 •

edited

Loading

fmease commented Aug 12, 2025 •

edited

Loading