user0/rust
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Expand CloneToUninit documentation.

Browse source 
* Clarify relationship to `dyn` after #133003.
* Add an example of using it with `dyn` as #133003 enabled.
* Add an example of implementing it.
* Add links to Rust Reference for the mentioned concepts.
* Mention that its method should rarely be called.
* Replace parameter name `dst` with `dest` to avoids confusion between
  “DeSTination” and “Dynamically-Sized Type”.
* Various small corrections.
This commit is contained in:
Kevin Reid 2024-11-14 10:43:04 -08:00
parent f5a1ef7121
commit 769425a4ea
1 changed files with 131 additions and 28 deletions
Download patch file Download diff file Expand all files Collapse all files

159
library/core/src/clone.rs
View file

@ -262,34 +262,137 @@ pub struct AssertParamIsCopy<T: Copy + ?Sized> {
_field: crate::marker::PhantomData<T>,
}
/// A generalization of [`Clone`] to dynamically-sized types stored in arbitrary containers.
/// A generalization of [`Clone`] to [dynamically-sized types][DST] stored in arbitrary containers.
///
/// This trait is implemented for all types implementing [`Clone`], and also [slices](slice) of all
/// such types. You may also implement this trait to enable cloning trait objects and custom DSTs
/// (structures containing dynamically-sized fields).
/// This trait is implemented for all types implementing [`Clone`], [slices](slice) of all
/// such types, and other dynamically-sized types in the standard library.
/// You may also implement this trait to enable cloning custom DSTs
/// (structures containing dynamically-sized fields), or use it as a supertrait to enable
/// cloning a [trait object].
///
/// This trait is normally used via operations on container types which support DSTs,
/// so you should not typically need to call `.clone_to_uninit()` explicitly except when
/// implementing such a container or otherwise performing explicit management of an allocation,
/// or when implementing `CloneToUninit` itself.
///
/// # Safety
///
/// Implementations must ensure that when `.clone_to_uninit(dst)` returns normally rather than
/// panicking, it always leaves `*dst` initialized as a valid value of type `Self`.
/// Implementations must ensure that when `.clone_to_uninit(dest)` returns normally rather than
/// panicking, it always leaves `*dest` initialized as a valid value of type `Self`.
///
/// # See also
/// # Examples
///
/// * [`Clone::clone_from`] is a safe function which may be used instead when `Self` is a [`Sized`]
// FIXME(#126799): when `Box::clone` allows use of `CloneToUninit`, rewrite these examples with it
// since `Rc` is a distraction.
///
/// If you are defining a trait, you can add `CloneToUninit` as a supertrait to enable cloning of
/// `dyn` values of your trait:
///
/// ```
/// #![feature(clone_to_uninit)]
/// use std::rc::Rc;
///
/// trait Foo: std::fmt::Debug + std::clone::CloneToUninit {
/// fn modify(&mut self);
/// fn value(&self) -> i32;
/// }
///
/// impl Foo for i32 {
/// fn modify(&mut self) {
/// *self *= 10;
/// }
/// fn value(&self) -> i32 {
/// *self
/// }
/// }
///
/// let first: Rc<dyn Foo> = Rc::new(1234);
///
/// let mut second = first.clone();
/// Rc::make_mut(&mut second).modify(); // make_mut() will call clone_to_uninit()
///
/// assert_eq!(first.value(), 1234);
/// assert_eq!(second.value(), 12340);
/// ```
///
/// The following is an example of implementing `CloneToUninit` for a custom DST.
/// (It is essentially a limited form of what `derive(CloneToUninit)` would do,
/// if such a derive macro existed.)
///
/// ```
/// #![feature(clone_to_uninit)]
/// use std::clone::CloneToUninit;
/// use std::mem::offset_of;
/// use std::rc::Rc;
///
/// #[derive(PartialEq)]
/// struct MyDst<T: ?Sized> {
/// flag: bool,
/// contents: T,
/// }
///
/// unsafe impl<T: ?Sized + CloneToUninit> CloneToUninit for MyDst<T> {
/// unsafe fn clone_to_uninit(&self, dest: *mut u8) {
/// // The offset of `self.contents` is dynamic because it depends on the alignment of T
/// // which can be dynamic (if `T = dyn SomeTrait`). Therefore, we have to obtain it
/// // dynamically by examining `self`, rather than using `offset_of!`.
/// let offset_of_contents =
/// (&raw const self.contents).byte_offset_from_unsigned(&raw const *self);
///
/// // Since `flag` implements `Copy`, we can just copy it.
/// // We use `pointer::write()` instead of assignment because the destination must be
/// // assumed to be uninitialized, whereas an assignment assumes it is initialized.
/// dest.add(offset_of!(Self, flag)).cast::<bool>().write(self.flag);
///
/// // Note: if `flag` owned any resources (i.e. had a `Drop` implementation), then we
/// // must prepare to drop it in case `self.contents.clone_to_uninit()` panics.
/// // In this simple case, where we have exactly one field for which `mem::needs_drop()`
/// // might be true (`contents`), we don’t need to care about cleanup or ordering.
/// self.contents.clone_to_uninit(dest.add(offset_of_contents));
///
/// // All fields of the struct have been initialized, therefore the struct is initialized,
/// // and we have satisfied our `unsafe impl CloneToUninit` obligations.
/// }
/// }
///
/// fn main() {
/// // Construct MyDst<[u8; 4]>, then coerce to MyDst<[u8]>.
/// let first: Rc<MyDst<[u8]>> = Rc::new(MyDst {
/// flag: true,
/// contents: [1, 2, 3, 4],
/// });
///
/// let mut second = first.clone();
/// // make_mut() will call clone_to_uninit().
/// for elem in Rc::make_mut(&mut second).contents.iter_mut() {
/// *elem *= 10;
/// }
///
/// assert_eq!(first.contents, [1, 2, 3, 4]);
/// assert_eq!(second.contents, [10, 20, 30, 40]);
/// }
/// ```
///
/// # See Also
///
/// * [`Clone::clone_from`] is a safe function which may be used instead when [`Self: Sized`](Sized)
/// and the destination is already initialized; it may be able to reuse allocations owned by
/// the destination.
/// the destination, whereas `clone_to_uninit` cannot, since its destination is assumed to be
/// uninitialized.
/// * [`ToOwned`], which allocates a new destination container.
///
/// [`ToOwned`]: ../../std/borrow/trait.ToOwned.html
/// [DST]: https://doc.rust-lang.org/reference/dynamically-sized-types.html
/// [trait object]: https://doc.rust-lang.org/reference/types/trait-object.html
#[unstable(feature = "clone_to_uninit", issue = "126799")]
pub unsafe trait CloneToUninit {
/// Performs copy-assignment from `self` to `dst`.
/// Performs copy-assignment from `self` to `dest`.
///
/// This is analogous to `std::ptr::write(dst.cast(), self.clone())`,
/// except that `self` may be a dynamically-sized type ([`!Sized`](Sized)).
/// This is analogous to `std::ptr::write(dest.cast(), self.clone())`,
/// except that `Self` may be a dynamically-sized type ([`!Sized`](Sized)).
///
/// Before this function is called, `dst` may point to uninitialized memory.
/// After this function is called, `dst` will point to initialized memory; it will be
/// Before this function is called, `dest` may point to uninitialized memory.
/// After this function is called, `dest` will point to initialized memory; it will be
/// sound to create a `&Self` reference from the pointer with the [pointer metadata]
/// from `self`.
///
@ -297,8 +400,8 @@ pub unsafe trait CloneToUninit {
///
/// Behavior is undefined if any of the following conditions are violated:
///
/// * `dst` must be [valid] for writes for `size_of_val(self)` bytes.
/// * `dst` must be properly aligned to `align_of_val(self)`.
/// * `dest` must be [valid] for writes for `size_of_val(self)` bytes.
/// * `dest` must be properly aligned to `align_of_val(self)`.
///
/// [valid]: crate::ptr#safety
/// [pointer metadata]: crate::ptr::metadata()
@ -307,11 +410,11 @@ pub unsafe trait CloneToUninit {
///
/// This function may panic. (For example, it might panic if memory allocation for a clone
/// of a value owned by `self` fails.)
/// If the call panics, then `*dst` should be treated as uninitialized memory; it must not be
/// If the call panics, then `*dest` should be treated as uninitialized memory; it must not be
/// read or dropped, because even if it was previously valid, it may have been partially
/// overwritten.
///
/// The caller may also need to take care to deallocate the allocation pointed to by `dst`,
/// The caller may also need to take care to deallocate the allocation pointed to by `dest`,
/// if applicable, to avoid a memory leak, and may need to take other precautions to ensure
/// soundness in the presence of unwinding.
///
@ -319,15 +422,15 @@ pub unsafe trait CloneToUninit {
/// that might have already been created. (For example, if a `[Foo]` of length 3 is being
/// cloned, and the second of the three calls to `Foo::clone()` unwinds, then the first `Foo`
/// cloned should be dropped.)
unsafe fn clone_to_uninit(&self, dst: *mut u8);
unsafe fn clone_to_uninit(&self, dest: *mut u8);
}
#[unstable(feature = "clone_to_uninit", issue = "126799")]
unsafe impl<T: Clone> CloneToUninit for T {
#[inline]
unsafe fn clone_to_uninit(&self, dst: *mut u8) {
unsafe fn clone_to_uninit(&self, dest: *mut u8) {
// SAFETY: we're calling a specialization with the same contract
unsafe { <T as self::uninit::CopySpec>::clone_one(self, dst.cast::<T>()) }
unsafe { <T as self::uninit::CopySpec>::clone_one(self, dest.cast::<T>()) }
}
}
@ -335,10 +438,10 @@ unsafe impl<T: Clone> CloneToUninit for T {
unsafe impl<T: Clone> CloneToUninit for [T] {
#[inline]
#[cfg_attr(debug_assertions, track_caller)]
unsafe fn clone_to_uninit(&self, dst: *mut u8) {
let dst: *mut [T] = dst.with_metadata_of(self);
unsafe fn clone_to_uninit(&self, dest: *mut u8) {
let dest: *mut [T] = dest.with_metadata_of(self);
// SAFETY: we're calling a specialization with the same contract
unsafe { <T as self::uninit::CopySpec>::clone_slice(self, dst) }
unsafe { <T as self::uninit::CopySpec>::clone_slice(self, dest) }
}
}
@ -346,21 +449,21 @@ unsafe impl<T: Clone> CloneToUninit for [T] {
unsafe impl CloneToUninit for str {
#[inline]
#[cfg_attr(debug_assertions, track_caller)]
unsafe fn clone_to_uninit(&self, dst: *mut u8) {
unsafe fn clone_to_uninit(&self, dest: *mut u8) {
// SAFETY: str is just a [u8] with UTF-8 invariant
unsafe { self.as_bytes().clone_to_uninit(dst) }
unsafe { self.as_bytes().clone_to_uninit(dest) }
}
}
#[unstable(feature = "clone_to_uninit", issue = "126799")]
unsafe impl CloneToUninit for crate::ffi::CStr {
#[cfg_attr(debug_assertions, track_caller)]
unsafe fn clone_to_uninit(&self, dst: *mut u8) {
unsafe fn clone_to_uninit(&self, dest: *mut u8) {
// SAFETY: For now, CStr is just a #[repr(trasnsparent)] [c_char] with some invariants.
// And we can cast [c_char] to [u8] on all supported platforms (see: to_bytes_with_nul).
// The pointer metadata properly preserves the length (so NUL is also copied).
// See: `cstr_metadata_is_length_with_nul` in tests.
unsafe { self.to_bytes_with_nul().clone_to_uninit(dst) }
unsafe { self.to_bytes_with_nul().clone_to_uninit(dest) }
}
}