Add some docs to Global

[maxdexh]

r? libs

[maxdexh]

r? clarfonthey

[clarfonthey]

@bors r+ rollup

@rustbot label:beta-nominated

(but only if this is merged post-branch; I don't want to rush merging it in)

[rust-bors]

📌 Commit 3e574ad has been tentatively approved by clarfonthey

It will be put into the queue for this repository once PR CI succeeds.

[Mark-Simulacrum]

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]

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]

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]

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]

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]

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.