Messages in this thread | | | From | "Andreas Hindborg (Samsung)" <> | Subject | Re: [PATCH v1] rust: add improved version of `ForeignOwnable::borrow_mut` | Date | Wed, 23 Aug 2023 10:40:54 +0200 |
| |
Alice Ryhl <aliceryhl@google.com> writes:
> Andreas Hindborg <nmi@metaspace.dk> writes: >>> + /// Borrows a foreign-owned object mutably. >>> + /// >>> + /// This method provides a way to access a foreign-owned value from Rust mutably. It provides >>> + /// you with exactly the same abilities as an `&mut Self` when the value is Rust-owned, except >>> + /// that this method does not let you swap the foreign-owned object for another. (That is, it >>> + /// does not let you change the address of the void pointer that the foreign code is storing.) >> >> How about this: >> >> "For a smart pointer P<T> this method provides mutable access to T if >> &mut P<T> would allow mutable access to T. Otherwise it provides >> immutable access to T." >> >> The point is that the method provides access to the pointee, not the >> smart pointer itself. In fact it is perfectly fine to do a mem::swawp() >> for the pointee in the case of Box and depending on interpretation the >> sentence "does not let you swap the foreign-owned object for another" is >> confusing. > > Yeah, I agree that the phrasing is somewhat confusing. > > How about this: > > /// This method provides a way to access a foreign-owned value from Rust mutably. It provides > /// you with exactly the same abilities as an `&mut Self` when the value is Rust-owned, except > /// that the address of the object must not be changed. > /// > /// Note that for types like [`Arc`], an `&mut Arc<T>` only gives you immutable access to the > /// inner value, so this method also only provides immutable access in that case. > /// > /// In the case of `Box<T>`, this method gives you the ability to modify the inner `T`, but it > /// does not let you change the box itself. That is, you cannot change which allocation the box > /// points at.
Sounds good 👍
BR Andreas
| |