Skip to content

Add some docs to Global #163332

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
rust-bors merged 1 commit into from
Sep 26, 2026
Merged

Add some docs to Global #163332

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 21 additions & 2 deletions library/alloc/src/alloc.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,8 +49,27 @@ unsafe extern "Rust" {
/// to the allocator registered with the `#[global_allocator]` attribute
/// if there is one, or the `std` crate’s default.
///
/// Note: while this type is unstable, the functionality it provides can be
/// accessed through the [free functions in `alloc`](self#functions).
/// Similar to [`alloc`], [`dealloc`], and the other global allocation functions,
/// the way in which calls are forwarded to the allocator registered with
/// `#[global_allocator]` is unspecified. See their safety docs for more information.
///
/// This allocator must be treated like an opaque allocator that only guarantees
/// the contract described in the docs of [`Allocator`], as well as the following
/// things:
/// * All instances of `Global` are [*equivalent*].
/// * Allocations from `Global` are only invalidated by calls to de-/reallocating functions.
/// If no such call is made, then the allocation will live for the rest of the program.
/// * The global allocation functions are equivalent to the methods on `Global`, except

@Mark-Simulacrum Mark-Simulacrum Sep 25, 2026 •
edited by rustbot
Loading

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is the implication that it's OK to Global.allocate and then std::alloc::deallocate that memory? I would expect that to not be the case. I think it definitely shouldn't be guaranteed that you can Global.allocate and System.deallocate, even if #[global_allocator] = System.

View changes since the review

@maxdexh maxdexh Sep 25, 2026 •
edited
Loading

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That must be the case, since otherwise the guarantees made by Box about this are broken, unless we special case around it by saying "if you go to a Box (or Vec) first, then you can alloc::dealloc or Global.deallocate". But at that point we might as well just guarantee this.

In particular, we allow you to create Box<T, Global> using alloc::alloc() and from_raw. Likewise for its allocator obviously. OTOH, we allow you to deallocate it using into_raw and alloc::dealloc, and obviously using its allocator.

@clarfonthey clarfonthey Sep 25, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note this is specifically for Global, not for anything that is equivalent to Global, like that example. The goal is to deprecate these methods explicitly in favour of methods on Global, so, it's useful to say they're identical.

@maxdexh maxdexh Sep 25, 2026 •
edited
Loading

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also note that using the allocator you registered as the global allocator (e.g. System) to deallocate stuff from Global/alloc::alloc(...) is never allowed. Does my text insinuate that? If so, it needs to be fixed

@Mark-Simulacrum Mark-Simulacrum Sep 26, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it would be worth making sure that these lines from std::alloc::alloc is copied here (or into doc comments on allocate/deallocate):

invoking this function is not equivalent to invoking the underlying GlobalAlloc::alloc method of the registered allocator directly

and:

The allocation can only be freed by invoking dealloc or realloc. In particular, passing a pointer to such an allocation directly to the underlying method on GlobalAlloc is not permitted.

I think that last paragraph at least implies you can't std::alloc::alloc() and then <Global as GlobalAlloc>::dealloc(...) -- perhaps the right thing is to rephrase it, alongside any coping done?

It may be worth expanding the documentation at the top level (std::alloc):

The global allocator is invoked via the functions in this module (alloc, alloc_zeroed, dealloc, realloc). Note, however, that invoking those functions is not equivalent to directly invoking the underlying methods on the declared global allocator! See the documentation of those functions for details.

This saying something about the relationship of methods from:

  • Global as Allocator
  • std::alloc free-standing functions
  • Global as GlobalAlloc
  • Global as GlobalAllocator

I believe we annotate some of these functions to LLVM -- maybe just the inner functions that we eventually call though? -- and given the proliferation of ways to reach the #[global_allocator] it seems worth documenting some more details.

I'm not sure if the text here insinuates you can interchange with System, but IMO we have a bunch of documentation around this that is not as clear as it used to be (in part due to added indirection and added Allocator stabilization), and probably was never crystal clear.

@maxdexh maxdexh Sep 26, 2026 •
edited
Loading

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it would be worth making sure that these lines from std::alloc::alloc is copied here (or into doc comments on allocate/deallocate):

sure, we can do that

The allocation can only be freed by invoking dealloc or realloc. In particular, passing a pointer to such an allocation directly to the underlying method on GlobalAlloc is not permitted.

I think that last paragraph at least implies you can't std::alloc::alloc() and then <Global as GlobalAlloc>::dealloc(...)

Global is not the underlying GlobalAlloc allocator. In fact Global does not implement GlobalAlloc. If it did, it would create an infinite loop when registered as the global allocator. Global is the allocator that invokes the registered #[global_allocator] through the free standing allocation functions in alloc, and is therefore equivalent to them. In particular, as contradictory as that might sound, Global is never a global allocator.

/// that they disallow zero-sized allocations, and implicitly ignore any returned
/// excess size.
///
/// Note that the current implementation of `Global` does not take advantage of
/// some features of [`Allocator`], such as zero-sized allocations (which currently always
/// return a dangling pointer) and overallocating.
///
/// This may change in the future. You must not rely on it for correctness!
///
/// [*equivalent*]: Allocator#equivalent-allocators
#[stable(feature = "allocator_api", since = "CURRENT_RUSTC_VERSION")]
#[derive(Copy, Debug)]
#[derive_const(Clone, Default)]
Expand Down
Loading