diff options
author | Haibo Huang <hhb@google.com> | 2020-07-10 20:23:30 -0700 |
---|---|---|
committer | Chih-Hung Hsieh <chh@google.com> | 2020-07-13 22:26:50 -0700 |
commit | d58366dc4a1a1ec807bb02dfc7928051799130ac (patch) | |
tree | 99470e8e8e4787e90b156f71bafac98438d6c39a /src | |
parent | 09ba014483c2506939704e0b993a728958553e25 (diff) | |
download | pin-project-d58366dc4a1a1ec807bb02dfc7928051799130ac.tar.gz |
Upgrade rust/crates/pin-project to 0.4.22android-r-beta-3android-r-beta-2
* Keep local change in src/lib.rs
Test: make
Change-Id: I63ca4a3f247df2028bcb6cb849823b296865f444
Diffstat (limited to 'src')
-rw-r--r-- | src/lib.rs | 109 |
1 files changed, 63 insertions, 46 deletions
@@ -1,8 +1,9 @@ -//! A crate for safe and ergonomic pin-projection. +//! A crate for safe and ergonomic [pin-projection]. //! -//! ## Examples +//! # Examples //! -//! [`pin_project`] attribute creates a projection type covering all the fields of struct or enum. +//! [`#[pin_project]`][`pin_project`] attribute creates projection types +//! covering all the fields of struct or enum. //! //! ```rust //! use pin_project::pin_project; @@ -16,7 +17,7 @@ //! } //! //! impl<T, U> Struct<T, U> { -//! fn foo(self: Pin<&mut Self>) { +//! fn method(self: Pin<&mut Self>) { //! let this = self.project(); //! let _: Pin<&mut T> = this.pinned; // Pinned reference to the field //! let _: &mut U = this.unpinned; // Normal reference to the field @@ -24,17 +25,18 @@ //! } //! ``` //! -//! [Code like this will be generated](https://github.com/taiki-e/pin-project/blob/master/examples/struct-default-expanded.rs) +//! [*code like this will be generated*][struct-default-expanded] //! -//! See [`pin_project`] attribute for more details. -//! -//! Also, there are examples and generated code of each feature in [examples](https://github.com/taiki-e/pin-project/blob/master/examples/README.md) directory. +//! See [`#[pin_project]`][`pin_project`] attribute for more details, and +//! see [examples] directory for more examples and generated code. //! //! [`pin_project`]: attr.pin_project.html +//! [examples]: https://github.com/taiki-e/pin-project/blob/master/examples/README.md +//! [pin-projection]: https://doc.rust-lang.org/nightly/std/pin/index.html#projections-and-structural-pinning +//! [struct-default-expanded]: https://github.com/taiki-e/pin-project/blob/master/examples/struct-default-expanded.rs #![no_std] -#![recursion_limit = "256"] -#![doc(html_root_url = "https://docs.rs/pin-project/0.4.17")] +#![doc(html_root_url = "https://docs.rs/pin-project/0.4.22")] #![doc(test( no_crate_inject, attr(deny(warnings, rust_2018_idioms, single_use_lifetimes), allow(dead_code)) @@ -44,6 +46,8 @@ // mem::take and #[non_exhaustive] requires Rust 1.40 #![allow(clippy::mem_replace_with_default, clippy::manual_non_exhaustive)] #![allow(clippy::needless_doctest_main)] +// https://github.com/rust-lang/rust-clippy/issues/5704 +#![allow(clippy::unnested_or_patterns)] // ANDROID: Use std to allow building as a dylib. extern crate std; @@ -54,18 +58,21 @@ pub use pin_project_internal::pin_project; #[doc(inline)] pub use pin_project_internal::pinned_drop; +#[allow(deprecated)] #[doc(inline)] pub use pin_project_internal::project; +#[allow(deprecated)] #[doc(inline)] pub use pin_project_internal::project_ref; +#[allow(deprecated)] #[doc(inline)] pub use pin_project_internal::project_replace; /// A trait used for custom implementations of [`Unpin`]. /// This trait is used in conjunction with the `UnsafeUnpin` -/// argument to [`pin_project`] +/// argument to [`#[pin_project]`][`pin_project`] /// /// The Rust [`Unpin`] trait is safe to implement - by itself, /// implementing it cannot lead to undefined behavior. Undefined @@ -78,9 +85,9 @@ pub use pin_project_internal::project_replace; /// /// However, things change if you want to provide a custom [`Unpin`] impl /// for your `#[pin_project]` type. As stated in [the Rust -/// documentation](https://doc.rust-lang.org/nightly/std/pin/index.html#projections-and-structural-pinning), -/// you must be sure to only implement [`Unpin`] when all of your `#[pin]` fields (i.e. structurally -/// pinned fields) are also [`Unpin`]. +/// documentation][pin-projection], you must be sure to only implement [`Unpin`] +/// when all of your `#[pin]` fields (i.e. structurally pinned fields) are also +/// [`Unpin`]. /// /// To help highlight this unsafety, the `UnsafeUnpin` trait is provided. /// Implementing this trait is logically equivalent to implementing [`Unpin`] - @@ -92,15 +99,16 @@ pub use pin_project_internal::project_replace; /// /// Note that if you specify `#[pin_project(UnsafeUnpin)]`, but do *not* /// provide an impl of `UnsafeUnpin`, your type will never implement [`Unpin`]. -/// This is effectively the same thing as adding a [`PhantomPinned`] to your type +/// This is effectively the same thing as adding a [`PhantomPinned`] to your +/// type. /// -/// Since this trait is `unsafe`, impls of it will be detected by the `unsafe_code` lint, -/// and by tools like `cargo geiger`. +/// Since this trait is `unsafe`, impls of it will be detected by the +/// `unsafe_code` lint, and by tools like [`cargo geiger`][cargo-geiger]. /// -/// ## Examples +/// # Examples /// -/// An `UnsafeUnpin` impl which, in addition to requiring that structurally pinned -/// fields be [`Unpin`], imposes an additional requirement: +/// An `UnsafeUnpin` impl which, in addition to requiring that structurally +/// pinned fields be [`Unpin`], imposes an additional requirement: /// /// ```rust /// use pin_project::{pin_project, UnsafeUnpin}; @@ -117,13 +125,23 @@ pub use pin_project_internal::project_replace; /// /// [`PhantomPinned`]: core::marker::PhantomPinned /// [`pin_project`]: attr.pin_project.html +/// [pin-projection]: https://doc.rust-lang.org/nightly/std/pin/index.html#projections-and-structural-pinning +/// [cargo-geiger]: https://github.com/rust-secure-code/cargo-geiger pub unsafe trait UnsafeUnpin {} // Not public API. #[doc(hidden)] pub mod __private { + #[doc(hidden)] + pub use core::{ + marker::{PhantomData, PhantomPinned, Unpin}, + mem::ManuallyDrop, + ops::Drop, + pin::Pin, + ptr, + }; + use super::UnsafeUnpin; - use core::{marker::PhantomData, mem::ManuallyDrop, pin::Pin, ptr}; #[doc(hidden)] pub use pin_project_internal::__PinProjectInternalDerive; @@ -153,6 +171,7 @@ pub mod __private { // // Supposed we have the following code: // + // ```rust // #[pin_project(UnsafeUnpin)] // struct MyStruct<T> { // #[pin] field: T @@ -160,37 +179,43 @@ pub mod __private { // // impl<T> Unpin for MyStruct<T> where MyStruct<T>: UnsafeUnpin {} // generated by pin-project-internal // impl<T> Unpin for MyStruct<T> where T: Copy // written by the user + // ``` // - // We want this code to be rejected - the user is completely bypassing `UnsafeUnpin`, - // and providing an unsound Unpin impl in safe code! + // We want this code to be rejected - the user is completely bypassing + // `UnsafeUnpin`, and providing an unsound Unpin impl in safe code! // // Unfortunately, the Rust compiler will accept the above code. // Because MyStruct is declared in the same crate as the user-provided impl, - // the compiler will notice that 'MyStruct<T>: UnsafeUnpin' never holds. + // the compiler will notice that `MyStruct<T>: UnsafeUnpin` never holds. // - // The solution is to introduce the 'Wrapper' struct, which is defined - // in the 'pin-project' crate. + // The solution is to introduce the `Wrapper` struct, which is defined + // in the `pin-project` crate. // // We now have code that looks like this: // + // ```rust // impl<T> Unpin for MyStruct<T> where Wrapper<MyStruct<T>>: UnsafeUnpin {} // generated by pin-project-internal // impl<T> Unpin for MyStruct<T> where T: Copy // written by the user + // ``` // - // We also have 'unsafe impl<T> UnsafeUnpin for Wrapper<T> where T: UnsafeUnpin {}' in the - // 'pin-project' crate. + // We also have `unsafe impl<T> UnsafeUnpin for Wrapper<T> where T: UnsafeUnpin {}` + // in the `pin-project` crate. // - // Now, our generated impl has a bound involving a type defined in another crate - Wrapper. - // This will cause rust to conservatively assume that 'Wrapper<MyStruct<T>>: UnsafeUnpin' - // holds, in the interest of preserving forwards compatibility (in case such an impl is added - // for Wrapper<T> in a new version of the crate). + // Now, our generated impl has a bound involving a type defined in another + // crate - Wrapper. This will cause rust to conservatively assume that + // `Wrapper<MyStruct<T>>: UnsafeUnpin` holds, in the interest of preserving + // forwards compatibility (in case such an impl is added for Wrapper<T> in + // a new version of the crate). // - // This will cause rust to reject any other Unpin impls for MyStruct<T>, since it will - // assume that our generated impl could potentially apply in any situation. + // This will cause rust to reject any other `Unpin` impls for MyStruct<T>, + // since it will assume that our generated impl could potentially apply in + // any situation. // - // This achieves the desired effect - when the user writes `#[pin_project(UnsafeUnpin)]`, - // the user must either provide no impl of `UnsafeUnpin` (which is equivalent - // to making the type never implement Unpin), or provide an impl of `UnsafeUnpin`. - // It is impossible for them to provide an impl of `Unpin` + // This achieves the desired effect - when the user writes + // `#[pin_project(UnsafeUnpin)]`, the user must either provide no impl of + // `UnsafeUnpin` (which is equivalent to making the type never implement + // Unpin), or provide an impl of `UnsafeUnpin`. It is impossible for them to + // provide an impl of `Unpin` #[doc(hidden)] pub struct Wrapper<'a, T: ?Sized>(PhantomData<&'a ()>, T); @@ -232,11 +257,3 @@ pub mod __private { } } } - -// Not public API. -// See tests/overwriting_core_crate.rs for more. -#[doc(hidden)] -pub mod __reexport { - #[doc(hidden)] - pub use core::{marker, mem, ops, pin, ptr}; -} |