diff options
Diffstat (limited to 'third_party/rust/pin-project/examples')
9 files changed, 511 insertions, 0 deletions
diff --git a/third_party/rust/pin-project/examples/README.md b/third_party/rust/pin-project/examples/README.md new file mode 100644 index 0000000000..6234900131 --- /dev/null +++ b/third_party/rust/pin-project/examples/README.md @@ -0,0 +1,9 @@ +## Examples and generated code of each feature of pin-project + +* [Basic usage of `#[pin_project]` on structs.](struct-default.rs) -- [generated code](struct-default-expanded.rs) + +* [Basic usage of `#[pin_project]` on enums.](enum-default.rs) -- [generated code](enum-default-expanded.rs) + +* [Manual implementation of `Unpin` by `UnsafeUnpin`.](unsafe_unpin.rs) -- [generated code](unsafe_unpin-expanded.rs) + +* [Manual implementation of `Drop` by `#[pinned_drop]`.](pinned_drop.rs) -- [generated code](pinned_drop-expanded.rs) diff --git a/third_party/rust/pin-project/examples/enum-default-expanded.rs b/third_party/rust/pin-project/examples/enum-default-expanded.rs new file mode 100644 index 0000000000..568f9b2c23 --- /dev/null +++ b/third_party/rust/pin-project/examples/enum-default-expanded.rs @@ -0,0 +1,86 @@ +// Original code (./enum-default.rs): +// +// ```rust +// #![allow(dead_code)] +// +// use pin_project::pin_project; +// +// #[pin_project] +// enum Enum<T, U> { +// Pinned(#[pin] T), +// Unpinned(U), +// } +// +// fn main() {} +// ``` + +#![allow(dead_code, unused_imports, unused_parens)] + +use pin_project::pin_project; + +enum Enum<T, U> { + Pinned(/* #[pin] */ T), + Unpinned(U), +} + +#[allow(clippy::mut_mut)] // This lint warns `&mut &mut <ty>`. +#[allow(dead_code)] // This lint warns unused fields/variants. +enum __EnumProjection<'pin, T, U> { + Pinned(::core::pin::Pin<&'pin mut (T)>), + Unpinned(&'pin mut (U)), +} + +#[allow(dead_code)] // This lint warns unused fields/variants. +enum __EnumProjectionRef<'pin, T, U> { + Pinned(::core::pin::Pin<&'pin (T)>), + Unpinned(&'pin (U)), +} + +impl<T, U> Enum<T, U> { + fn project<'pin>(self: ::core::pin::Pin<&'pin mut Self>) -> __EnumProjection<'pin, T, U> { + unsafe { + match self.get_unchecked_mut() { + Enum::Pinned(_0) => __EnumProjection::Pinned(::core::pin::Pin::new_unchecked(_0)), + Enum::Unpinned(_0) => __EnumProjection::Unpinned(_0), + } + } + } + fn project_ref<'pin>(self: ::core::pin::Pin<&'pin Self>) -> __EnumProjectionRef<'pin, T, U> { + unsafe { + match self.get_ref() { + Enum::Pinned(_0) => { + __EnumProjectionRef::Pinned(::core::pin::Pin::new_unchecked(_0)) + } + Enum::Unpinned(_0) => __EnumProjectionRef::Unpinned(_0), + } + } + } +} + +// Automatically create the appropriate conditional `Unpin` implementation. +// +// See ./struct-default-expanded.rs and https://github.com/taiki-e/pin-project/pull/53. +// for details. +#[allow(non_snake_case)] +fn __unpin_scope_Enum() { + struct __Enum<'pin, T, U> { + __pin_project_use_generics: ::pin_project::__private::AlwaysUnpin<'pin, (T, U)>, + __field0: T, + } + impl<'pin, T, U> ::core::marker::Unpin for Enum<T, U> where __Enum<'pin, T, U>: ::core::marker::Unpin + {} +} + +// Ensure that enum does not implement `Drop`. +// +// See ./struct-default-expanded.rs for details. +trait EnumMustNotImplDrop {} +#[allow(clippy::drop_bounds)] +impl<T: ::core::ops::Drop> EnumMustNotImplDrop for T {} +#[allow(single_use_lifetimes)] +impl<T, U> EnumMustNotImplDrop for Enum<T, U> {} + +// We don't need to check for '#[repr(packed)]', +// since it does not apply to enums. + +fn main() {} diff --git a/third_party/rust/pin-project/examples/enum-default.rs b/third_party/rust/pin-project/examples/enum-default.rs new file mode 100644 index 0000000000..ab5a4bc2a5 --- /dev/null +++ b/third_party/rust/pin-project/examples/enum-default.rs @@ -0,0 +1,13 @@ +// See ./enum-default-expanded.rs for generated code. + +#![allow(dead_code)] + +use pin_project::pin_project; + +#[pin_project] +enum Enum<T, U> { + Pinned(#[pin] T), + Unpinned(U), +} + +fn main() {} diff --git a/third_party/rust/pin-project/examples/pinned_drop-expanded.rs b/third_party/rust/pin-project/examples/pinned_drop-expanded.rs new file mode 100644 index 0000000000..d96dd98e12 --- /dev/null +++ b/third_party/rust/pin-project/examples/pinned_drop-expanded.rs @@ -0,0 +1,133 @@ +// Original code (./pinned_drop.rs): +// +// ```rust +// #![allow(dead_code)] +// +// use pin_project::{pin_project, pinned_drop}; +// use std::pin::Pin; +// +// #[pin_project(PinnedDrop)] +// pub struct Foo<'a, T> { +// was_dropped: &'a mut bool, +// #[pin] +// field: T, +// } +// +// #[pinned_drop] +// fn drop_foo<T>(mut this: Pin<&mut Foo<'_, T>>) { +// **this.project().was_dropped = true; +// } +// +// fn main() {} +// ``` + +#![allow(dead_code, unused_imports, unused_parens)] + +use pin_project::{pin_project, pinned_drop}; +use std::pin::Pin; + +pub struct Foo<'a, T> { + was_dropped: &'a mut bool, + // #[pin] + field: T, +} + +#[allow(clippy::mut_mut)] // This lint warns `&mut &mut <ty>`. +#[allow(dead_code)] // This lint warns unused fields/variants. +pub(crate) struct __FooProjection<'pin, 'a, T> { + was_dropped: &'pin mut (&'a mut bool), + field: ::core::pin::Pin<&'pin mut (T)>, +} + +#[allow(dead_code)] // This lint warns unused fields/variants. +pub(crate) struct __FooProjectionRef<'pin, 'a, T> { + was_dropped: &'pin (&'a mut bool), + field: ::core::pin::Pin<&'pin (T)>, +} + +impl<'a, T> Foo<'a, T> { + pub(crate) fn project<'pin>( + self: ::core::pin::Pin<&'pin mut Self>, + ) -> __FooProjection<'pin, 'a, T> { + unsafe { + let Foo { was_dropped, field } = self.get_unchecked_mut(); + __FooProjection { was_dropped, field: ::core::pin::Pin::new_unchecked(field) } + } + } + pub(crate) fn project_ref<'pin>( + self: ::core::pin::Pin<&'pin Self>, + ) -> __FooProjectionRef<'pin, 'a, T> { + unsafe { + let Foo { was_dropped, field } = self.get_ref(); + __FooProjectionRef { was_dropped, field: ::core::pin::Pin::new_unchecked(field) } + } + } +} + +#[allow(single_use_lifetimes)] +impl<'a, T> ::core::ops::Drop for Foo<'a, T> { + fn drop(&mut self) { + // Safety - we're in 'drop', so we know that 'self' will + // never move again. + let pinned_self = unsafe { ::core::pin::Pin::new_unchecked(self) }; + // We call `pinned_drop` only once. Since `PinnedDrop::drop` + // is an unsafe function and a private API, it is never called again in safe + // code *unless the user uses a maliciously crafted macro*. + unsafe { + ::pin_project::__private::PinnedDrop::drop(pinned_self); + } + } +} + +// It is safe to implement PinnedDrop::drop, but it is not safe to call it. +// This is because destructors can be called multiple times (double dropping +// is unsound: rust-lang/rust#62360). +// +// Ideally, it would be desirable to be able to prohibit manual calls in the +// same way as Drop::drop, but the library cannot. So, by using macros and +// replacing them with private traits, we prevent users from calling +// PinnedDrop::drop. +// +// Users can implement `Drop` safely using `#[pinned_drop]`. +// **Do not call or implement this trait directly.** +impl<T> ::pin_project::__private::PinnedDrop for Foo<'_, T> { + // Since calling it twice on the same object would be UB, + // this method is unsafe. + unsafe fn drop(self: Pin<&mut Self>) { + fn __drop_inner<T>(__self: Pin<&mut Foo<'_, T>>) { + **__self.project().was_dropped = true; + } + __drop_inner(self); + } +} + +// Automatically create the appropriate conditional `Unpin` implementation. +// +// See ./struct-default-expanded.rs and https://github.com/taiki-e/pin-project/pull/53. +// for details. +#[allow(non_snake_case)] +fn __unpin_scope_Foo() { + pub struct __Foo<'pin, 'a, T> { + __pin_project_use_generics: ::pin_project::__private::AlwaysUnpin<'pin, (T)>, + __field0: T, + __lifetime0: &'a (), + } + impl<'pin, 'a, T> ::core::marker::Unpin for Foo<'a, T> where + __Foo<'pin, 'a, T>: ::core::marker::Unpin + { + } +} + +// Ensure that it's impossible to use pin projections on a #[repr(packed)] struct. +// +// See ./struct-default-expanded.rs and https://github.com/taiki-e/pin-project/pull/34 +// for details. +#[allow(single_use_lifetimes)] +#[allow(non_snake_case)] +#[deny(safe_packed_borrows)] +fn __pin_project_assert_not_repr_packed_Foo<'a, T>(val: &Foo<'a, T>) { + &val.was_dropped; + &val.field; +} + +fn main() {} diff --git a/third_party/rust/pin-project/examples/pinned_drop.rs b/third_party/rust/pin-project/examples/pinned_drop.rs new file mode 100644 index 0000000000..3dcfc6afe9 --- /dev/null +++ b/third_party/rust/pin-project/examples/pinned_drop.rs @@ -0,0 +1,22 @@ +// See ./pinned_drop-expanded.rs for generated code. + +#![allow(dead_code)] + +use pin_project::{pin_project, pinned_drop}; +use std::pin::Pin; + +#[pin_project(PinnedDrop)] +pub struct Foo<'a, T> { + was_dropped: &'a mut bool, + #[pin] + field: T, +} + +#[pinned_drop] +impl<T> PinnedDrop for Foo<'_, T> { + fn drop(self: Pin<&mut Self>) { + **self.project().was_dropped = true; + } +} + +fn main() {} diff --git a/third_party/rust/pin-project/examples/struct-default-expanded.rs b/third_party/rust/pin-project/examples/struct-default-expanded.rs new file mode 100644 index 0000000000..ec454b7971 --- /dev/null +++ b/third_party/rust/pin-project/examples/struct-default-expanded.rs @@ -0,0 +1,128 @@ +// Original code (./struct-default.rs): +// +// ```rust +// #![allow(dead_code)] +// +// use pin_project::pin_project; +// +// #[pin_project] +// struct Struct<T, U> { +// #[pin] +// pinned: T, +// unpinned: U, +// } +// +// fn main() {} +// ``` + +#![allow(dead_code, unused_imports, unused_parens)] + +use pin_project::pin_project; + +struct Struct<T, U> { + // #[pin] + pinned: T, + unpinned: U, +} + +#[allow(clippy::mut_mut)] // This lint warns `&mut &mut <ty>`. +#[allow(dead_code)] // This lint warns unused fields/variants. +struct __StructProjection<'pin, T, U> { + pinned: ::core::pin::Pin<&'pin mut (T)>, + unpinned: &'pin mut (U), +} +#[allow(dead_code)] // This lint warns unused fields/variants. +struct __StructProjectionRef<'pin, T, U> { + pinned: ::core::pin::Pin<&'pin (T)>, + unpinned: &'pin (U), +} + +impl<T, U> Struct<T, U> { + fn project<'pin>(self: ::core::pin::Pin<&'pin mut Self>) -> __StructProjection<'pin, T, U> { + unsafe { + let Struct { pinned, unpinned } = self.get_unchecked_mut(); + __StructProjection { pinned: ::core::pin::Pin::new_unchecked(pinned), unpinned } + } + } + fn project_ref<'pin>(self: ::core::pin::Pin<&'pin Self>) -> __StructProjectionRef<'pin, T, U> { + unsafe { + let Struct { pinned, unpinned } = self.get_ref(); + __StructProjectionRef { pinned: ::core::pin::Pin::new_unchecked(pinned), unpinned } + } + } +} + +// Automatically create the appropriate conditional `Unpin` implementation. +// +// Basically this is equivalent to the following code: +// ```rust +// impl<T, U> Unpin for Struct<T, U> where T: Unpin {} +// ``` +// +// However, if struct is public and there is a private type field, +// this would cause an E0446 (private type in public interface). +// +// When RFC 2145 is implemented (rust-lang/rust#48054), +// this will become a lint, rather then a hard error. +// +// As a workaround for this, we generate a new struct, containing all of the pinned +// fields from our #[pin_project] type. This struct is declared within +// a function, which makes it impossible to be named by user code. +// This guarantees that it will use the default auto-trait impl for Unpin - +// that is, it will implement Unpin iff all of its fields implement Unpin. +// This type can be safely declared as 'public', satisfying the privacy +// checker without actually allowing user code to access it. +// +// This allows users to apply the #[pin_project] attribute to types +// regardless of the privacy of the types of their fields. +// +// See also https://github.com/taiki-e/pin-project/pull/53. +#[allow(non_snake_case)] +fn __unpin_scope_Struct() { + struct __Struct<'pin, T, U> { + __pin_project_use_generics: ::pin_project::__private::AlwaysUnpin<'pin, (T, U)>, + __field0: T, + } + impl<'pin, T, U> ::core::marker::Unpin for Struct<T, U> where + __Struct<'pin, T, U>: ::core::marker::Unpin + { + } +} + +// Ensure that struct does not implement `Drop`. +// +// There are two possible cases: +// 1. The user type does not implement Drop. In this case, +// the first blanked impl will not apply to it. This code +// will compile, as there is only one impl of MustNotImplDrop for the user type +// 2. The user type does impl Drop. This will make the blanket impl applicable, +// which will then conflict with the explicit MustNotImplDrop impl below. +// This will result in a compilation error, which is exactly what we want. +trait StructMustNotImplDrop {} +#[allow(clippy::drop_bounds)] +impl<T: ::core::ops::Drop> StructMustNotImplDrop for T {} +#[allow(single_use_lifetimes)] +impl<T, U> StructMustNotImplDrop for Struct<T, U> {} + +// Ensure that it's impossible to use pin projections on a #[repr(packed)] struct. +// +// Taking a reference to a packed field is unsafe, and applying +// #[deny(safe_packed_borrows)] makes sure that doing this without +// an 'unsafe' block (which we deliberately do not generate) +// is a hard error. +// +// If the struct ends up having #[repr(packed)] applied somehow, +// this will generate an (unfriendly) error message. Under all reasonable +// circumstances, we'll detect the #[repr(packed)] attribute, and generate +// a much nicer error above. +// +// See https://github.com/taiki-e/pin-project/pull/34 for more details. +#[allow(single_use_lifetimes)] +#[allow(non_snake_case)] +#[deny(safe_packed_borrows)] +fn __pin_project_assert_not_repr_packed_Struct<T, U>(val: &Struct<T, U>) { + &val.pinned; + &val.unpinned; +} + +fn main() {} diff --git a/third_party/rust/pin-project/examples/struct-default.rs b/third_party/rust/pin-project/examples/struct-default.rs new file mode 100644 index 0000000000..46808a5827 --- /dev/null +++ b/third_party/rust/pin-project/examples/struct-default.rs @@ -0,0 +1,14 @@ +// See ./struct-default-expanded.rs for generated code. + +#![allow(dead_code)] + +use pin_project::pin_project; + +#[pin_project] +struct Struct<T, U> { + #[pin] + pinned: T, + unpinned: U, +} + +fn main() {} diff --git a/third_party/rust/pin-project/examples/unsafe_unpin-expanded.rs b/third_party/rust/pin-project/examples/unsafe_unpin-expanded.rs new file mode 100644 index 0000000000..acb3ee8316 --- /dev/null +++ b/third_party/rust/pin-project/examples/unsafe_unpin-expanded.rs @@ -0,0 +1,90 @@ +// Original code (./unsafe_unpin.rs): +// +// ```rust +// #![allow(dead_code)] +// +// use pin_project::{pin_project, UnsafeUnpin}; +// +// #[pin_project(UnsafeUnpin)] +// pub struct Foo<T, U> { +// #[pin] +// pinned: T, +// unpinned: U, +// } +// +// unsafe impl<T: Unpin, U> UnsafeUnpin for Foo<T, U> {} +// +// fn main() {} +// ``` + +#![allow(dead_code, unused_imports, unused_parens)] + +use pin_project::{pin_project, UnsafeUnpin}; + +pub struct Foo<T, U> { + // #[pin] + pinned: T, + unpinned: U, +} + +#[allow(clippy::mut_mut)] // This lint warns `&mut &mut <ty>`. +#[allow(dead_code)] // This lint warns unused fields/variants. +pub(crate) struct __FooProjection<'pin, T, U> { + pinned: ::core::pin::Pin<&'pin mut (T)>, + unpinned: &'pin mut (U), +} +#[allow(dead_code)] // This lint warns unused fields/variants. +pub(crate) struct __FooProjectionRef<'pin, T, U> { + pinned: ::core::pin::Pin<&'pin (T)>, + unpinned: &'pin (U), +} + +impl<T, U> Foo<T, U> { + pub(crate) fn project<'pin>( + self: ::core::pin::Pin<&'pin mut Self>, + ) -> __FooProjection<'pin, T, U> { + unsafe { + let Foo { pinned, unpinned } = self.get_unchecked_mut(); + __FooProjection { pinned: ::core::pin::Pin::new_unchecked(pinned), unpinned } + } + } + pub(crate) fn project_ref<'pin>( + self: ::core::pin::Pin<&'pin Self>, + ) -> __FooProjectionRef<'pin, T, U> { + unsafe { + let Foo { pinned, unpinned } = self.get_ref(); + __FooProjectionRef { pinned: ::core::pin::Pin::new_unchecked(pinned), unpinned } + } + } +} + +unsafe impl<T: Unpin, U> UnsafeUnpin for Foo<T, U> {} + +#[allow(single_use_lifetimes)] +impl<'pin, T, U> ::core::marker::Unpin for Foo<T, U> where + ::pin_project::__private::Wrapper<'pin, Self>: ::pin_project::UnsafeUnpin +{ +} + +// Ensure that struct does not implement `Drop`. +// +// See ./struct-default-expanded.rs for details. +trait FooMustNotImplDrop {} +#[allow(clippy::drop_bounds)] +impl<T: ::core::ops::Drop> FooMustNotImplDrop for T {} +#[allow(single_use_lifetimes)] +impl<T, U> FooMustNotImplDrop for Foo<T, U> {} + +// Ensure that it's impossible to use pin projections on a #[repr(packed)] struct. +// +// See ./struct-default-expanded.rs and https://github.com/taiki-e/pin-project/pull/34 +// for details. +#[allow(single_use_lifetimes)] +#[allow(non_snake_case)] +#[deny(safe_packed_borrows)] +fn __pin_project_assert_not_repr_packed_Foo<T, U>(val: &Foo<T, U>) { + &val.pinned; + &val.unpinned; +} + +fn main() {} diff --git a/third_party/rust/pin-project/examples/unsafe_unpin.rs b/third_party/rust/pin-project/examples/unsafe_unpin.rs new file mode 100644 index 0000000000..9056808d6f --- /dev/null +++ b/third_party/rust/pin-project/examples/unsafe_unpin.rs @@ -0,0 +1,16 @@ +// See ./pinned_drop-expanded.rs for generated code. + +#![allow(dead_code)] + +use pin_project::{pin_project, UnsafeUnpin}; + +#[pin_project(UnsafeUnpin)] +pub struct Foo<T, U> { + #[pin] + pinned: T, + unpinned: U, +} + +unsafe impl<T: Unpin, U> UnsafeUnpin for Foo<T, U> {} + +fn main() {} |