Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

move the Pin API into its own module for centralized documentation #53227

Merged
merged 18 commits into from
Aug 28, 2018
Merged

move the Pin API into its own module for centralized documentation #53227

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
13da951
move PinMut into pin module and export through std
nivkner Aug 9, 2018
971d7ed
move PinBox into pin module and export through std
nivkner Aug 9, 2018
30bb4af
add top-level documentation to the std pin module
nivkner Aug 9, 2018
c4ec0cd
attempt to work around Box<T> not being recognized as local type
nivkner Aug 10, 2018
c110388
fix link to PinMut
nivkner Aug 10, 2018
f9efd05
move pin module to liballoc and reexport that
nivkner Aug 14, 2018
1bb0579
expand the documentation on PinBox
nivkner Aug 14, 2018
2f501a1
fix PinMut documentation
nivkner Aug 14, 2018
8e9aad2
deemphasize immutability and improve swap explanation in pin module
nivkner Aug 14, 2018
6b47a61
allow unused mut for pinning explanation
nivkner Aug 18, 2018
1c26be3
fix broken link to Unpin due to reexport
nivkner Aug 18, 2018
1304cee
add more info on Unpin and connect paragraphs better
nivkner Aug 21, 2018
871e89b
capitalize and punctuate libcore pin module
nivkner Aug 21, 2018
bfed149
reexport Unpin into pin module
nivkner Aug 21, 2018
c3fd65b
link Unpin to pin module documentation
nivkner Aug 21, 2018
3683bf2
adjust PinMut import in Unpin docs
nivkner Aug 22, 2018
b26cce5
link to items in pin module to std docs
nivkner Aug 22, 2018
83ca347
remove copyright headers now that they are not madatory
nivkner Aug 24, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
211 changes: 9 additions & 202 deletions src/liballoc/boxed.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -64,12 +64,14 @@ use core::future::{Future, FutureObj, LocalFutureObj, UnsafeFutureObj};
use core::hash::{Hash, Hasher};
use core::iter::FusedIterator;
use core::marker::{Unpin, Unsize};
use core::mem::{self, PinMut};
use core::mem;
use core::pin::PinMut;
use core::ops::{CoerceUnsized, Deref, DerefMut, Generator, GeneratorState};
use core::ptr::{self, NonNull, Unique};
use core::task::{Context, Poll, Spawn, SpawnErrorKind, SpawnObjError};

use raw_vec::RawVec;
use pin::PinBox;
use str::from_boxed_utf8_unchecked;

/// A pointer type for heap allocation.
Expand Down Expand Up @@ -758,166 +760,6 @@ impl<T> Generator for Box<T>
}
}

/// A pinned, heap allocated reference.
#[unstable(feature = "pin", issue = "49150")]
#[fundamental]
#[repr(transparent)]
pub struct PinBox<T: ?Sized> {
inner: Box<T>,
}

#[unstable(feature = "pin", issue = "49150")]
impl<T> PinBox<T> {
/// Allocate memory on the heap, move the data into it and pin it.
#[unstable(feature = "pin", issue = "49150")]
pub fn new(data: T) -> PinBox<T> {
PinBox { inner: Box::new(data) }
}
}

#[unstable(feature = "pin", issue = "49150")]
impl<T: ?Sized> PinBox<T> {
/// Get a pinned reference to the data in this PinBox.
#[inline]
pub fn as_pin_mut<'a>(&'a mut self) -> PinMut<'a, T> {
unsafe { PinMut::new_unchecked(&mut *self.inner) }
}

/// Constructs a `PinBox` from a raw pointer.
///
/// After calling this function, the raw pointer is owned by the
/// resulting `PinBox`. Specifically, the `PinBox` destructor will call
/// the destructor of `T` and free the allocated memory. Since the
/// way `PinBox` allocates and releases memory is unspecified, the
/// only valid pointer to pass to this function is the one taken
/// from another `PinBox` via the [`PinBox::into_raw`] function.
///
/// This function is unsafe because improper use may lead to
/// memory problems. For example, a double-free may occur if the
/// function is called twice on the same raw pointer.
///
/// [`PinBox::into_raw`]: struct.PinBox.html#method.into_raw
///
/// # Examples
///
/// ```
/// #![feature(pin)]
/// use std::boxed::PinBox;
/// let x = PinBox::new(5);
/// let ptr = PinBox::into_raw(x);
/// let x = unsafe { PinBox::from_raw(ptr) };
/// ```
#[inline]
pub unsafe fn from_raw(raw: *mut T) -> Self {
PinBox { inner: Box::from_raw(raw) }
}

/// Consumes the `PinBox`, returning the wrapped raw pointer.
///
/// After calling this function, the caller is responsible for the
/// memory previously managed by the `PinBox`. In particular, the
/// caller should properly destroy `T` and release the memory. The
/// proper way to do so is to convert the raw pointer back into a
/// `PinBox` with the [`PinBox::from_raw`] function.
///
/// Note: this is an associated function, which means that you have
/// to call it as `PinBox::into_raw(b)` instead of `b.into_raw()`. This
/// is so that there is no conflict with a method on the inner type.
///
/// [`PinBox::from_raw`]: struct.PinBox.html#method.from_raw
///
/// # Examples
///
/// ```
/// #![feature(pin)]
/// use std::boxed::PinBox;
/// let x = PinBox::new(5);
/// let ptr = PinBox::into_raw(x);
/// ```
#[inline]
pub fn into_raw(b: PinBox<T>) -> *mut T {
Box::into_raw(b.inner)
}

/// Get a mutable reference to the data inside this PinBox.
///
/// This function is unsafe. Users must guarantee that the data is never
/// moved out of this reference.
#[inline]
pub unsafe fn get_mut<'a>(this: &'a mut PinBox<T>) -> &'a mut T {
&mut *this.inner
}

/// Convert this PinBox into an unpinned Box.
///
/// This function is unsafe. Users must guarantee that the data is never
/// moved out of the box.
#[inline]
pub unsafe fn unpin(this: PinBox<T>) -> Box<T> {
this.inner
}
}

#[unstable(feature = "pin", issue = "49150")]
impl<T: ?Sized> From<Box<T>> for PinBox<T> {
fn from(boxed: Box<T>) -> PinBox<T> {
PinBox { inner: boxed }
}
}

#[unstable(feature = "pin", issue = "49150")]
impl<T: Unpin + ?Sized> From<PinBox<T>> for Box<T> {
fn from(pinned: PinBox<T>) -> Box<T> {
pinned.inner
}
}

#[unstable(feature = "pin", issue = "49150")]
impl<T: ?Sized> Deref for PinBox<T> {
type Target = T;

fn deref(&self) -> &T {
&*self.inner
}
}

#[unstable(feature = "pin", issue = "49150")]
impl<T: Unpin + ?Sized> DerefMut for PinBox<T> {
fn deref_mut(&mut self) -> &mut T {
&mut *self.inner
}
}

#[unstable(feature = "pin", issue = "49150")]
impl<T: fmt::Display + ?Sized> fmt::Display for PinBox<T> {
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
fmt::Display::fmt(&*self.inner, f)
}
}

#[unstable(feature = "pin", issue = "49150")]
impl<T: fmt::Debug + ?Sized> fmt::Debug for PinBox<T> {
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
fmt::Debug::fmt(&*self.inner, f)
}
}

#[unstable(feature = "pin", issue = "49150")]
impl<T: ?Sized> fmt::Pointer for PinBox<T> {
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
// It's not possible to extract the inner Uniq directly from the Box,
// instead we cast it to a *const which aliases the Unique
let ptr: *const T = &*self.inner;
fmt::Pointer::fmt(&ptr, f)
}
}

#[unstable(feature = "pin", issue = "49150")]
impl<T: ?Sized + Unsize<U>, U: ?Sized> CoerceUnsized<PinBox<U>> for PinBox<T> {}

#[unstable(feature = "pin", issue = "49150")]
impl<T: ?Sized> Unpin for PinBox<T> {}

#[unstable(feature = "futures_api", issue = "50547")]
impl<F: ?Sized + Future + Unpin> Future for Box<F> {
type Output = F::Output;
Expand All @@ -927,15 +769,6 @@ impl<F: ?Sized + Future + Unpin> Future for Box<F> {
}
}

#[unstable(feature = "futures_api", issue = "50547")]
impl<F: ?Sized + Future> Future for PinBox<F> {
type Output = F::Output;

fn poll(mut self: PinMut<Self>, cx: &mut Context) -> Poll<Self::Output> {
self.as_pin_mut().poll(cx)
}
}

#[unstable(feature = "futures_api", issue = "50547")]
unsafe impl<'a, T, F> UnsafeFutureObj<'a, T> for Box<F>
where F: Future<Output = T> + 'a
Expand All @@ -955,25 +788,6 @@ unsafe impl<'a, T, F> UnsafeFutureObj<'a, T> for Box<F>
}
}

#[unstable(feature = "futures_api", issue = "50547")]
unsafe impl<'a, T, F> UnsafeFutureObj<'a, T> for PinBox<F>
where F: Future<Output = T> + 'a
{
fn into_raw(self) -> *mut () {
PinBox::into_raw(self) as *mut ()
}

unsafe fn poll(ptr: *mut (), cx: &mut Context) -> Poll<T> {
let ptr = ptr as *mut F;
let pin: PinMut<F> = PinMut::new_unchecked(&mut *ptr);
pin.poll(cx)
}

unsafe fn drop(ptr: *mut ()) {
drop(PinBox::from_raw(ptr as *mut F))
}
}

#[unstable(feature = "futures_api", issue = "50547")]
impl<Sp> Spawn for Box<Sp>
where Sp: Spawn + ?Sized
Expand All @@ -990,13 +804,6 @@ impl<Sp> Spawn for Box<Sp>
}
}

#[unstable(feature = "futures_api", issue = "50547")]
impl<'a, F: Future<Output = ()> + Send + 'a> From<PinBox<F>> for FutureObj<'a, ()> {
fn from(boxed: PinBox<F>) -> Self {
FutureObj::new(boxed)
}
}

#[unstable(feature = "futures_api", issue = "50547")]
impl<'a, F: Future<Output = ()> + Send + 'a> From<Box<F>> for FutureObj<'a, ()> {
fn from(boxed: Box<F>) -> Self {
Expand All @@ -1005,15 +812,15 @@ impl<'a, F: Future<Output = ()> + Send + 'a> From<Box<F>> for FutureObj<'a, ()>
}

#[unstable(feature = "futures_api", issue = "50547")]
impl<'a, F: Future<Output = ()> + 'a> From<PinBox<F>> for LocalFutureObj<'a, ()> {
fn from(boxed: PinBox<F>) -> Self {
impl<'a, F: Future<Output = ()> + 'a> From<Box<F>> for LocalFutureObj<'a, ()> {
fn from(boxed: Box<F>) -> Self {
LocalFutureObj::new(boxed)
}
}

#[unstable(feature = "futures_api", issue = "50547")]
impl<'a, F: Future<Output = ()> + 'a> From<Box<F>> for LocalFutureObj<'a, ()> {
fn from(boxed: Box<F>) -> Self {
LocalFutureObj::new(boxed)
#[unstable(feature = "pin", issue = "49150")]
impl<T: Unpin + ?Sized> From<PinBox<T>> for Box<T> {
fn from(pinned: PinBox<T>) -> Box<T> {
unsafe { PinBox::unpin(pinned) }
}
}
1 change: 1 addition & 0 deletions src/liballoc/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -159,6 +159,7 @@ pub mod collections;
pub mod sync;
pub mod rc;
pub mod raw_vec;
pub mod pin;
pub mod prelude;
pub mod borrow;
pub mod fmt;
Expand Down
Loading