Rename `Alloc` to `AllocRef`

[TimDiekmann]

@SimonSapin suggested to rename Alloc to AllocHandle in rust-lang/rust#58457 (comment):

we might want to add Handle to the trait names [...] in order to show that they are typically implemented for a reference or smart pointer or ZST, not directly for the type that actually holds the allocator’s state.

This would also apply to #9 and rename Dealloc to DeallocHandle.

Edit: Rename AllocHandle to AllocRef as stated in #8 (comment)

[Amanieu]

IMO the main benefit here is that it clarifies the semantics of Clone on an allocator. In the case of AllocHandle, it is clear that the cloned handle still points to the same allocator instance, and that you can free data allocated from one handle with another handle.

[SimonSapin]

I hope this renaming would help clear some confusion that I’ve seen happen multiple times:

“If A is the type for 'the allocator' and Box<T, A> has direct ownership of a value of type A, does that means that an allocator instance can only be used in one box? Shouldn’t Box own &'a A instead or something?”

Or: “Why does Alloc::alloc take &mut self? Shouldn’t that be &self so that the allocator can be shared?”

It turns out that Box having ownership of a bare A and Alloc::alloc taking &mut self are what provides maximum flexibility, but it’s not obvious at all why. When creating your own MyAllocator type, there are typically two scenarios: the type is a zero-size unit struct that anyone can “construct” out of thin air (see std::alloc::Global), or you’d implement the Alloc trait not for your type directly but with some indirection like &'a MyAllocator or Arc<MyAllocator> (or both). Then, Alloc::alloc’s &mut self is e.g. &mut &'a MyAllocator. (Cases where &mut self over &self is important are probably less typical, but there is basically no downside in supporting them.)

Having vocabulary that separates “an allocator” and “a handle to that allocator” (and naming APIs accordingly) can hopefully make this indirection more discoverable.

[scottjmaddox]

I strongly support this change. Just in discussing other issues over the last day or two there have been multiple times when I felt that calling it AllocHandle would be much more clear.

[gnzlbg]

I think many will expect to be able to just write Vec<T, AllocStorage<[T; 16]>> and get something like ArrayVec<[T; 16]> (or SmallVec, etc.), but that won't obviously work. Renaming Alloc to AllocHandle would clarify that this is not intended to work, so I think this would be a good thing.

[glandium]

It should, actually, be possible to get something like ArrayVec.

[TimDiekmann]

I think many will expect to be able to just write Vec<T, AllocStorage<[T; 16]>> and get something like ArrayVec<[T; 16]> (or SmallVec, etc.), but that won't obviously work. Renaming Alloc to AllocHandle would clarify that this is not intended to work, so I think this would be a good thing.

Could you elaborate on this?

[SimonSapin]

ArrayVec seems incompatible with an API where allocating returns a pointer that is then passed again when deallocating. The ArrayVec value might have moved, and the address of its inline storage changed.

You might consider something like the Pin API to prevent moves, but that’s much less useful than an ArrayVec that can move.

[gnzlbg]

Basically what @SimonSapin says, but I want to expand on why it is not worth it to support this use case for an MVP.

As @SimonSapin mentions, if the allocation storage lives within the AllocHandle, then when Vec<T, A> is moved, the storage is moved. Vec has a pointer to the allocation, and this pointer would be invalidated on move.

We'd have to make those allocators !Move, or use Pin like @SimonSapin suggest.

If we wanted to support moving these, we'd need to support correcting this pointer on move. I don't see a way of achieving that without adding move constructors to the language, which would be a huge language change.

So, AFAICT, we just can't support this right now, and the changes required to the language to support these are out-of-scope of this WG.