mikros/rust
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

tweaks

Browse Source
This commit is contained in:
Ralf Jung 2019-02-20 09:45:28 +01:00
parent 9c241aa714
commit c52560d788
1 changed files with 15 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
src/libcore/pin.rs
View File

@ -16,7 +16,7 @@
//! [`Pin`] wraps a pointer type, so `Pin<Box<T>>` functions much like a regular `Box<T>`
//! (when a `Pin<Box<T>>` gets dropped, so do its contents, and the memory gets deallocated).
//! Similarily, `Pin<&mut T>` is a lot like `&mut T`. However, [`Pin`] does not let clients actually
//! obtain a `Box` or reference to pinned data, which implies that you cannot use
//! obtain a `Box<T>` or `&mut T` to pinned data, which implies that you cannot use
//! operations such as [`mem::swap`]:
//! ```
//! use std::pin::Pin;
@ -29,9 +29,10 @@
//! ```
//!
//! It is worth reiterating that [`Pin`] does *not* change the fact that a Rust compiler
//! considers all types movable. [`mem::swap`] remains callable for any `T`. Instead, `Pin`
//! considers all types movable. [`mem::swap`] remains callable for any `T`. Instead, `Pin`
//! prevents certain *values* (pointed to by pointers wrapped in `Pin`) from being
//! moved by making it impossible to call methods like [`mem::swap`] on them.
//! moved by making it impossible to call methods that require `&mut T` on them
//! (like [`mem::swap`]).
//!
//! [`Pin`] can be used to wrap any pointer type, and as such it interacts with
//! [`Deref`] and [`DerefMut`]. A `Pin<P>` where `P: Deref` should be considered
@ -221,7 +222,7 @@
//! reference we got later.
//!
//! On the other hand, if you decide *not* to offer any pinning projections, you
//! are free to `impl<T> Unpin for Container<T>`. In the standard library,
//! are free to `impl<T> Unpin for Container<T>`. In the standard library,
//! this is done for all pointer types: `Box<T>: Unpin` holds for all `T`.
//! It makes sense to do this for pointer types, because moving the `Box<T>`
//! does not actually move the `T`: the `Box<T>` can be freely movable even if the `T`
@ -341,7 +342,7 @@ impl<P: Deref> Pin<P> {
/// pointed to by `pointer` is pinned, meaning that the data will not be moved or
/// its storage invalidated until it gets dropped. If the constructed `Pin<P>` does
/// not guarantee that the data `P` points to is pinned, constructing a
/// `Pin<P>` is unsafe. In particular,
/// `Pin<P>` is unsafe.
///
/// By using this method, you are making a promise about the `P::Deref` and
/// `P::DerefMut` implementations, if they exist. Most importantly, they
@ -353,9 +354,9 @@ impl<P: Deref> Pin<P> {
/// must not be possible to obtain a `&mut P::Target` and then
/// move out of that reference (using, for example [`mem::swap`]).
///
/// For example, calling `Pin::new_unchecked`
/// on an `&'a mut T` is unsafe because while you are able to pin it for the given
/// lifetime `'a`, you have no control over whether it is kept pinned once `'a` ends:
/// For example, calling `Pin::new_unchecked` on an `&'a mut T` is unsafe because
/// while you are able to pin it for the given lifetime `'a`, you have no control
/// over whether it is kept pinned once `'a` ends:
/// ```
/// use std::mem;
/// use std::pin::Pin;
@ -395,10 +396,10 @@ impl<P: Deref> Pin<P> {
/// Gets a pinned shared reference from this pinned pointer.
///
/// This is a generic method to go from `&Pin<SmartPointer<T>>` to `Pin<&T>`.
/// This is a generic method to go from `&Pin<Pointer<T>>` to `Pin<&T>`.
/// It is safe because, as part of the contract of `Pin::new_unchecked`,
/// the pointee cannot move after `Pin<SmartPointer<T>>` got created.
/// "Malicious" implementations of `SmartPointer::Deref` are likewise
/// the pointee cannot move after `Pin<Pointer<T>>` got created.
/// "Malicious" implementations of `Pointer::Deref` are likewise
/// ruled out by the contract of `Pin::new_unchecked`.
#[stable(feature = "pin", since = "1.33.0")]
#[inline(always)]
@ -410,10 +411,10 @@ impl<P: Deref> Pin<P> {
impl<P: DerefMut> Pin<P> {
/// Gets a pinned mutable reference from this pinned pointer.
///
/// This is a generic method to go from `&mut Pin<SmartPointer<T>>` to `Pin<&mut T>`.
/// This is a generic method to go from `&mut Pin<Pointer<T>>` to `Pin<&mut T>`.
/// It is safe because, as part of the contract of `Pin::new_unchecked`,
/// the pointee cannot move after `Pin<SmartPointer<T>>` got created.
/// "Malicious" implementations of `SmartPointer::DerefMut` are likewise
/// the pointee cannot move after `Pin<Pointer<T>>` got created.
/// "Malicious" implementations of `Pointer::DerefMut` are likewise
/// ruled out by the contract of `Pin::new_unchecked`.
#[stable(feature = "pin", since = "1.33.0")]
#[inline(always)]