[Merged by Bors] - Add a method for converting MutUntyped -> Mut<T>

[JoJoJet]

Objective

MutUntyped is a struct that stores a PtrMut alongside change tick metadata. Working with this type is cumbersome, and has few benefits over storing the pointer and change ticks separately.

Related: #6430 (title is out of date)

Solution

Add a convenience method for transforming an untyped change detection pointer into its typed counterpart.

---

Changelog

• Added the method MutUntyped::with_type.

[JoJoJet]

I relaxed the language on the *Ptr methods. Previously I wrote that the pointer must be "valid for reads/writes" or that it must be initialized. However, this is unnecessary, since it is unsound to create invalid instances of PtrMut and friends in the first place. Those invariants should be considered when constructing a pointer, not when consuming it.

[BoxyUwU]

I disagree with this PR adding alignment safety invariants to read/deref. Ptr/PtrMut/OwningPtr etc are documented as being "type erased borrows" and should require alignment on construction of them not on read/writes.

[james7132]

We should add the invariant to byte_add that it cannot make the pointer unaligned then. Since that would violate that invariant if the offset is not a multiple of the alignment.

[JoJoJet]

I disagree with this PR adding alignment safety invariants to read/deref. Ptr/PtrMut/OwningPtr etc are documented as being "type erased borrows" and should require alignment on construction of them not on read/writes.

The docs make no mention of any alignment requirement for these types:

/// This type tries to act "borrow-like" which means that:
/// - Pointer is considered exclusive and mutable. It cannot be cloned as this would lead to
/// aliased mutability.
/// - It must always points to a valid value of whatever the pointee type is.
/// - The lifetime 'a accurately represents how long the pointer is valid for.

The docs for Ptr*::new state this:

/// # Safety
/// The lifetime for the returned item must not exceed the lifetime inner is valid for

Again, no alignment requirements. Since these types have no alignment guarantee, you need to ensure they are aligned when you dereference them. This PR isn't adding any invariants, it's documenting invariants that used to be implicit.

We could add the requirement that these types must be aligned. But as discussed in #7117, it is useful to be able to create unaligned pointers. I don't think we should do this, it would make these types less valuable.

Also, to clarify one point that might be confusing:

/// - It must always points to a valid value of whatever the pointee type is.

This does not require the pointer to be aligned. Alignment is a property of a pointer, not the value it is pointing to.

[BoxyUwU]

The docs make no mention of any alignment requirement for these types:

Again, no alignment requirements. Since these types have no alignment guarantee, you need to ensure they are aligned when you dereference them

I'm aware of this. This should be changed by documenting alignment requirements.

This PR isn't adding any invariants, it's documenting invariants that used to be implicit.

They could implicitly be on Ptr::new and the docs of Ptr rather than read/deref etc

This does not require the pointer to be aligned

This is reasonable if its enforced on construction, imo the only safety invariants on read or deref should be that when you provide the type of the pointee it is the same as whatever conceptually is the "underlying" erased type. That means you dont have to reason about send/sync or lifetimes or aliasing or alignment etc.

We could add the requirement that these types must be aligned

as mentioned in #7117 we could have separate types for when alignment is not being upheld (which if we were starting from a position of having read/deref have an invariant that the pointer is aligned I would consider this to be a good step forwards for safety)

This does not require the pointer to be aligned. Alignment is a property of a pointer, not the value it is pointing to.

A better way of wording the safety invaraints on read/deref etc would probably be to talk about T having to be the same as the "underlying" erased type although that is slightly overly restrictive. With all the other invariants required for these methods to be sound enforced on construction of the Ptr type.

[JoJoJet]

I've reverted everything to use the incorrect invariants again, so we can have this discussion elsewhere.

[alice-i-cecile]

I've reverted everything to use the incorrect invariants again, so we can have this discussion elsewhere.

Agreed, this deserves its own issue or PR.

[alice-i-cecile]

bors r+

[bors]

Pull request successfully merged into main.

Build succeeded:

• build-and-install-on-iOS
• build-android
• build (macos-latest)
• build (ubuntu-latest)
• build-wasm
• build (windows-latest)
• build-without-default-features (bevy)
• build-without-default-features (bevy_ecs)
• build-without-default-features (bevy_reflect)
• check-compiles
• check-doc
• check-missing-examples-in-docs
• ci
• markdownlint
• msrv
• run-examples
• run-examples-on-wasm
• run-examples-on-windows-dx12