bjoernager/rust
bjoernager/rust
1
Fork 0
Code Activity

Rollup merge of #133055 - kpreid:clone-uninit-doc, r=Mark-Simulacrum

Browse source 
Expand `CloneToUninit` documentation.

* Clarify relationship to `dyn` after #133003.
* Add an example of using it with `dyn` as #133003 enabled.
* Replace parameter name `dst` with `dest` to avoid confusion between abbreviations for “DeSTination” and “Dynamically-Sized Type”.
* Add an example of implementing it.
* Add links to Rust Reference for the mentioned concepts.
* Mention that its method should rarely be called.
* Various small corrections.

Please review the `unsafe` code closely, as I am not an expert in the best possible ways to express these operations. (It might also be better to omit the implementation example entirely.)

cc `@zachs18` #126799
This commit is contained in:
许杰友 Jieyou Xu (Joe) 2025-03-16 09:40:01 +08:00 • committed by GitHub
commit 4946818306
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 145 additions and 30 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -262,34 +262,150 @@ 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> {
/// label: String,
/// 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!`.
/// //
/// // SAFETY: `self` by definition points somewhere before `&self.contents` in the same
/// // allocation.
/// let offset_of_contents = unsafe {
/// (&raw const self.contents).byte_offset_from_unsigned(self)
/// };
///
/// // Clone the *sized* fields of `self` (just one, in this example).
/// // (By cloning this first and storing it temporarily in a local variable, we avoid
/// // leaking it in case of any panic, using the ordinary automatic cleanup of local
/// // variables. Such a leak would be sound, but undesirable.)
/// let label = self.label.clone();
///
/// // SAFETY: The caller must provide a `dest` such that these field offsets are valid
/// // to write to.
/// unsafe {
/// // Clone the unsized field directly from `self` to `dest`.
/// self.contents.clone_to_uninit(dest.add(offset_of_contents));
///
/// // Now write all the sized fields.
/// //
/// // Note that we only do this once all of the clone() and clone_to_uninit() calls
/// // have completed, and therefore we know that there are no more possible panics;
/// // this ensures no memory leaks in case of panic.
/// dest.add(offset_of!(Self, label)).cast::<String>().write(label);
/// }
/// // 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 {
/// label: String::from("hello"),
/// 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]);
/// assert_eq!(second.label, "hello");
/// }
/// ```
///
/// # 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 +413,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,27 +423,26 @@ 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`,
/// if applicable, to avoid a memory leak, and may need to take other precautions to ensure
/// soundness in the presence of unwinding.
/// The caller may wish to to take care to deallocate the allocation pointed to by `dest`,
/// if applicable, to avoid a memory leak (but this is not a requirement).
///
/// Implementors should avoid leaking values by, upon unwinding, dropping all component values
/// 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 +450,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 +461,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) }
}
}