| // SPDX-License-Identifier: Apache-2.0 OR MIT | |
| //! This module provides the macros that actually implement the proc-macros `pin_data` and | |
| //! `pinned_drop`. It also contains `__init_internal`, the implementation of the | |
| //! `{try_}{pin_}init!` macros. | |
| //! | |
| //! These macros should never be called directly, since they expect their input to be | |
| //! in a certain format which is internal. If used incorrectly, these macros can lead to UB even in | |
| //! safe code! Use the public facing macros instead. | |
| //! | |
| //! This architecture has been chosen because the kernel does not yet have access to `syn` which | |
| //! would make matters a lot easier for implementing these as proc-macros. | |
| //! | |
| //! Since this library and the kernel implementation should diverge as little as possible, the same | |
| //! approach has been taken here. | |
| //! | |
| //! # Macro expansion example | |
| //! | |
| //! This section is intended for readers trying to understand the macros in this module and the | |
| //! `[try_][pin_]init!` macros from `lib.rs`. | |
| //! | |
| //! We will look at the following example: | |
| //! | |
| //! ```rust,ignore | |
| //! #[pin_data] | |
| //! #[repr(C)] | |
| //! struct Bar<T> { | |
| //! #[pin] | |
| //! t: T, | |
| //! pub x: usize, | |
| //! } | |
| //! | |
| //! impl<T> Bar<T> { | |
| //! fn new(t: T) -> impl PinInit<Self> { | |
| //! pin_init!(Self { t, x: 0 }) | |
| //! } | |
| //! } | |
| //! | |
| //! #[pin_data(PinnedDrop)] | |
| //! struct Foo { | |
| //! a: usize, | |
| //! #[pin] | |
| //! b: Bar<u32>, | |
| //! } | |
| //! | |
| //! #[pinned_drop] | |
| //! impl PinnedDrop for Foo { | |
| //! fn drop(self: Pin<&mut Self>) { | |
| //! println!("{self:p} is getting dropped."); | |
| //! } | |
| //! } | |
| //! | |
| //! let a = 42; | |
| //! let initializer = pin_init!(Foo { | |
| //! a, | |
| //! b <- Bar::new(36), | |
| //! }); | |
| //! ``` | |
| //! | |
| //! This example includes the most common and important features of the pin-init API. | |
| //! | |
| //! Below you can find individual section about the different macro invocations. Here are some | |
| //! general things we need to take into account when designing macros: | |
| //! - use global paths, similarly to file paths, these start with the separator: `::core::panic!()` | |
| //! this ensures that the correct item is used, since users could define their own `mod core {}` | |
| //! and then their own `panic!` inside to execute arbitrary code inside of our macro. | |
| //! - macro `unsafe` hygiene: we need to ensure that we do not expand arbitrary, user-supplied | |
| //! expressions inside of an `unsafe` block in the macro, because this would allow users to do | |
| //! `unsafe` operations without an associated `unsafe` block. | |
| //! | |
| //! ## `#[pin_data]` on `Bar` | |
| //! | |
| //! This macro is used to specify which fields are structurally pinned and which fields are not. It | |
| //! is placed on the struct definition and allows `#[pin]` to be placed on the fields. | |
| //! | |
| //! Here is the definition of `Bar` from our example: | |
| //! | |
| //! ```rust,ignore | |
| //! #[pin_data] | |
| //! #[repr(C)] | |
| //! struct Bar<T> { | |
| //! #[pin] | |
| //! t: T, | |
| //! pub x: usize, | |
| //! } | |
| //! ``` | |
| //! | |
| //! This expands to the following code: | |
| //! | |
| //! ```rust,ignore | |
| //! // Firstly the normal definition of the struct, attributes are preserved: | |
| //! #[repr(C)] | |
| //! struct Bar<T> { | |
| //! t: T, | |
| //! pub x: usize, | |
| //! } | |
| //! // Then an anonymous constant is defined, this is because we do not want any code to access the | |
| //! // types that we define inside: | |
| //! const _: () = { | |
| //! // We define the pin-data carrying struct, it is a ZST and needs to have the same generics, | |
| //! // since we need to implement access functions for each field and thus need to know its | |
| //! // type. | |
| //! struct __ThePinData<T> { | |
| //! __phantom: ::core::marker::PhantomData<fn(Bar<T>) -> Bar<T>>, | |
| //! } | |
| //! // We implement `Copy` for the pin-data struct, since all functions it defines will take | |
| //! // `self` by value. | |
| //! impl<T> ::core::clone::Clone for __ThePinData<T> { | |
| //! fn clone(&self) -> Self { | |
| //! *self | |
| //! } | |
| //! } | |
| //! impl<T> ::core::marker::Copy for __ThePinData<T> {} | |
| //! // For every field of `Bar`, the pin-data struct will define a function with the same name | |
| //! // and accessor (`pub` or `pub(crate)` etc.). This function will take a pointer to the | |
| //! // field (`slot`) and a `PinInit` or `Init` depending on the projection kind of the field | |
| //! // (if pinning is structural for the field, then `PinInit` otherwise `Init`). | |
| //! #[allow(dead_code)] | |
| //! impl<T> __ThePinData<T> { | |
| //! unsafe fn t<E>( | |
| //! self, | |
| //! slot: *mut T, | |
| //! // Since `t` is `#[pin]`, this is `PinInit`. | |
| //! init: impl ::pin_init::PinInit<T, E>, | |
| //! ) -> ::core::result::Result<(), E> { | |
| //! unsafe { ::pin_init::PinInit::__pinned_init(init, slot) } | |
| //! } | |
| //! pub unsafe fn x<E>( | |
| //! self, | |
| //! slot: *mut usize, | |
| //! // Since `x` is not `#[pin]`, this is `Init`. | |
| //! init: impl ::pin_init::Init<usize, E>, | |
| //! ) -> ::core::result::Result<(), E> { | |
| //! unsafe { ::pin_init::Init::__init(init, slot) } | |
| //! } | |
| //! } | |
| //! // Implement the internal `HasPinData` trait that associates `Bar` with the pin-data struct | |
| //! // that we constructed above. | |
| //! unsafe impl<T> ::pin_init::__internal::HasPinData for Bar<T> { | |
| //! type PinData = __ThePinData<T>; | |
| //! unsafe fn __pin_data() -> Self::PinData { | |
| //! __ThePinData { | |
| //! __phantom: ::core::marker::PhantomData, | |
| //! } | |
| //! } | |
| //! } | |
| //! // Implement the internal `PinData` trait that marks the pin-data struct as a pin-data | |
| //! // struct. This is important to ensure that no user can implement a rogue `__pin_data` | |
| //! // function without using `unsafe`. | |
| //! unsafe impl<T> ::pin_init::__internal::PinData for __ThePinData<T> { | |
| //! type Datee = Bar<T>; | |
| //! } | |
| //! // Now we only want to implement `Unpin` for `Bar` when every structurally pinned field is | |
| //! // `Unpin`. In other words, whether `Bar` is `Unpin` only depends on structurally pinned | |
| //! // fields (those marked with `#[pin]`). These fields will be listed in this struct, in our | |
| //! // case no such fields exist, hence this is almost empty. The two phantomdata fields exist | |
| //! // for two reasons: | |
| //! // - `__phantom`: every generic must be used, since we cannot really know which generics | |
| //! // are used, we declare all and then use everything here once. | |
| //! // - `__phantom_pin`: uses the `'__pin` lifetime and ensures that this struct is invariant | |
| //! // over it. The lifetime is needed to work around the limitation that trait bounds must | |
| //! // not be trivial, e.g. the user has a `#[pin] PhantomPinned` field -- this is | |
| //! // unconditionally `!Unpin` and results in an error. The lifetime tricks the compiler | |
| //! // into accepting these bounds regardless. | |
| //! #[allow(dead_code)] | |
| //! struct __Unpin<'__pin, T> { | |
| //! __phantom_pin: ::core::marker::PhantomData<fn(&'__pin ()) -> &'__pin ()>, | |
| //! __phantom: ::core::marker::PhantomData<fn(Bar<T>) -> Bar<T>>, | |
| //! // Our only `#[pin]` field is `t`. | |
| //! t: T, | |
| //! } | |
| //! #[doc(hidden)] | |
| //! impl<'__pin, T> ::core::marker::Unpin for Bar<T> | |
| //! where | |
| //! __Unpin<'__pin, T>: ::core::marker::Unpin, | |
| //! {} | |
| //! // Now we need to ensure that `Bar` does not implement `Drop`, since that would give users | |
| //! // access to `&mut self` inside of `drop` even if the struct was pinned. This could lead to | |
| //! // UB with only safe code, so we disallow this by giving a trait implementation error using | |
| //! // a direct impl and a blanket implementation. | |
| //! trait MustNotImplDrop {} | |
| //! // Normally `Drop` bounds do not have the correct semantics, but for this purpose they do | |
| //! // (normally people want to know if a type has any kind of drop glue at all, here we want | |
| //! // to know if it has any kind of custom drop glue, which is exactly what this bound does). | |
| //! #[expect(drop_bounds)] | |
| //! impl<T: ::core::ops::Drop> MustNotImplDrop for T {} | |
| //! impl<T> MustNotImplDrop for Bar<T> {} | |
| //! // Here comes a convenience check, if one implemented `PinnedDrop`, but forgot to add it to | |
| //! // `#[pin_data]`, then this will error with the same mechanic as above, this is not needed | |
| //! // for safety, but a good sanity check, since no normal code calls `PinnedDrop::drop`. | |
| //! #[expect(non_camel_case_types)] | |
| //! trait UselessPinnedDropImpl_you_need_to_specify_PinnedDrop {} | |
| //! impl< | |
| //! T: ::pin_init::PinnedDrop, | |
| //! > UselessPinnedDropImpl_you_need_to_specify_PinnedDrop for T {} | |
| //! impl<T> UselessPinnedDropImpl_you_need_to_specify_PinnedDrop for Bar<T> {} | |
| //! }; | |
| //! ``` | |
| //! | |
| //! ## `pin_init!` in `impl Bar` | |
| //! | |
| //! This macro creates an pin-initializer for the given struct. It requires that the struct is | |
| //! annotated by `#[pin_data]`. | |
| //! | |
| //! Here is the impl on `Bar` defining the new function: | |
| //! | |
| //! ```rust,ignore | |
| //! impl<T> Bar<T> { | |
| //! fn new(t: T) -> impl PinInit<Self> { | |
| //! pin_init!(Self { t, x: 0 }) | |
| //! } | |
| //! } | |
| //! ``` | |
| //! | |
| //! This expands to the following code: | |
| //! | |
| //! ```rust,ignore | |
| //! impl<T> Bar<T> { | |
| //! fn new(t: T) -> impl PinInit<Self> { | |
| //! { | |
| //! // We do not want to allow arbitrary returns, so we declare this type as the `Ok` | |
| //! // return type and shadow it later when we insert the arbitrary user code. That way | |
| //! // there will be no possibility of returning without `unsafe`. | |
| //! struct __InitOk; | |
| //! // Get the data about fields from the supplied type. | |
| //! // - the function is unsafe, hence the unsafe block | |
| //! // - we `use` the `HasPinData` trait in the block, it is only available in that | |
| //! // scope. | |
| //! let data = unsafe { | |
| //! use ::pin_init::__internal::HasPinData; | |
| //! Self::__pin_data() | |
| //! }; | |
| //! // Ensure that `data` really is of type `PinData` and help with type inference: | |
| //! let init = ::pin_init::__internal::PinData::make_closure::< | |
| //! _, | |
| //! __InitOk, | |
| //! ::core::convert::Infallible, | |
| //! >(data, move |slot| { | |
| //! { | |
| //! // Shadow the structure so it cannot be used to return early. If a user | |
| //! // tries to write `return Ok(__InitOk)`, then they get a type error, | |
| //! // since that will refer to this struct instead of the one defined | |
| //! // above. | |
| //! struct __InitOk; | |
| //! // This is the expansion of `t,`, which is syntactic sugar for `t: t,`. | |
| //! { | |
| //! unsafe { ::core::ptr::write(::core::addr_of_mut!((*slot).t), t) }; | |
| //! } | |
| //! // Since initialization could fail later (not in this case, since the | |
| //! // error type is `Infallible`) we will need to drop this field if there | |
| //! // is an error later. This `DropGuard` will drop the field when it gets | |
| //! // dropped and has not yet been forgotten. | |
| //! let __t_guard = unsafe { | |
| //! ::pin_init::__internal::DropGuard::new(::core::addr_of_mut!((*slot).t)) | |
| //! }; | |
| //! // Expansion of `x: 0,`: | |
| //! // Since this can be an arbitrary expression we cannot place it inside | |
| //! // of the `unsafe` block, so we bind it here. | |
| //! { | |
| //! let x = 0; | |
| //! unsafe { ::core::ptr::write(::core::addr_of_mut!((*slot).x), x) }; | |
| //! } | |
| //! // We again create a `DropGuard`. | |
| //! let __x_guard = unsafe { | |
| //! ::pin_init::__internal::DropGuard::new(::core::addr_of_mut!((*slot).x)) | |
| //! }; | |
| //! // Since initialization has successfully completed, we can now forget | |
| //! // the guards. This is not `mem::forget`, since we only have | |
| //! // `&DropGuard`. | |
| //! ::core::mem::forget(__x_guard); | |
| //! ::core::mem::forget(__t_guard); | |
| //! // Here we use the type checker to ensure that every field has been | |
| //! // initialized exactly once, since this is `if false` it will never get | |
| //! // executed, but still type-checked. | |
| //! // Additionally we abuse `slot` to automatically infer the correct type | |
| //! // for the struct. This is also another check that every field is | |
| //! // accessible from this scope. | |
| //! #[allow(unreachable_code, clippy::diverging_sub_expression)] | |
| //! let _ = || { | |
| //! unsafe { | |
| //! ::core::ptr::write( | |
| //! slot, | |
| //! Self { | |
| //! // We only care about typecheck finding every field | |
| //! // here, the expression does not matter, just conjure | |
| //! // one using `panic!()`: | |
| //! t: ::core::panic!(), | |
| //! x: ::core::panic!(), | |
| //! }, | |
| //! ); | |
| //! }; | |
| //! }; | |
| //! } | |
| //! // We leave the scope above and gain access to the previously shadowed | |
| //! // `__InitOk` that we need to return. | |
| //! Ok(__InitOk) | |
| //! }); | |
| //! // Change the return type from `__InitOk` to `()`. | |
| //! let init = move | | |
| //! slot, | |
| //! | -> ::core::result::Result<(), ::core::convert::Infallible> { | |
| //! init(slot).map(|__InitOk| ()) | |
| //! }; | |
| //! // Construct the initializer. | |
| //! let init = unsafe { | |
| //! ::pin_init::pin_init_from_closure::< | |
| //! _, | |
| //! ::core::convert::Infallible, | |
| //! >(init) | |
| //! }; | |
| //! init | |
| //! } | |
| //! } | |
| //! } | |
| //! ``` | |
| //! | |
| //! ## `#[pin_data]` on `Foo` | |
| //! | |
| //! Since we already took a look at `#[pin_data]` on `Bar`, this section will only explain the | |
| //! differences/new things in the expansion of the `Foo` definition: | |
| //! | |
| //! ```rust,ignore | |
| //! #[pin_data(PinnedDrop)] | |
| //! struct Foo { | |
| //! a: usize, | |
| //! #[pin] | |
| //! b: Bar<u32>, | |
| //! } | |
| //! ``` | |
| //! | |
| //! This expands to the following code: | |
| //! | |
| //! ```rust,ignore | |
| //! struct Foo { | |
| //! a: usize, | |
| //! b: Bar<u32>, | |
| //! } | |
| //! const _: () = { | |
| //! struct __ThePinData { | |
| //! __phantom: ::core::marker::PhantomData<fn(Foo) -> Foo>, | |
| //! } | |
| //! impl ::core::clone::Clone for __ThePinData { | |
| //! fn clone(&self) -> Self { | |
| //! *self | |
| //! } | |
| //! } | |
| //! impl ::core::marker::Copy for __ThePinData {} | |
| //! #[allow(dead_code)] | |
| //! impl __ThePinData { | |
| //! unsafe fn b<E>( | |
| //! self, | |
| //! slot: *mut Bar<u32>, | |
| //! init: impl ::pin_init::PinInit<Bar<u32>, E>, | |
| //! ) -> ::core::result::Result<(), E> { | |
| //! unsafe { ::pin_init::PinInit::__pinned_init(init, slot) } | |
| //! } | |
| //! unsafe fn a<E>( | |
| //! self, | |
| //! slot: *mut usize, | |
| //! init: impl ::pin_init::Init<usize, E>, | |
| //! ) -> ::core::result::Result<(), E> { | |
| //! unsafe { ::pin_init::Init::__init(init, slot) } | |
| //! } | |
| //! } | |
| //! unsafe impl ::pin_init::__internal::HasPinData for Foo { | |
| //! type PinData = __ThePinData; | |
| //! unsafe fn __pin_data() -> Self::PinData { | |
| //! __ThePinData { | |
| //! __phantom: ::core::marker::PhantomData, | |
| //! } | |
| //! } | |
| //! } | |
| //! unsafe impl ::pin_init::__internal::PinData for __ThePinData { | |
| //! type Datee = Foo; | |
| //! } | |
| //! #[allow(dead_code)] | |
| //! struct __Unpin<'__pin> { | |
| //! __phantom_pin: ::core::marker::PhantomData<fn(&'__pin ()) -> &'__pin ()>, | |
| //! __phantom: ::core::marker::PhantomData<fn(Foo) -> Foo>, | |
| //! b: Bar<u32>, | |
| //! } | |
| //! #[doc(hidden)] | |
| //! impl<'__pin> ::core::marker::Unpin for Foo | |
| //! where | |
| //! __Unpin<'__pin>: ::core::marker::Unpin, | |
| //! {} | |
| //! // Since we specified `PinnedDrop` as the argument to `#[pin_data]`, we expect `Foo` to | |
| //! // implement `PinnedDrop`. Thus we do not need to prevent `Drop` implementations like | |
| //! // before, instead we implement `Drop` here and delegate to `PinnedDrop`. | |
| //! impl ::core::ops::Drop for Foo { | |
| //! fn drop(&mut self) { | |
| //! // Since we are getting dropped, no one else has a reference to `self` and thus we | |
| //! // can assume that we never move. | |
| //! let pinned = unsafe { ::core::pin::Pin::new_unchecked(self) }; | |
| //! // Create the unsafe token that proves that we are inside of a destructor, this | |
| //! // type is only allowed to be created in a destructor. | |
| //! let token = unsafe { ::pin_init::__internal::OnlyCallFromDrop::new() }; | |
| //! ::pin_init::PinnedDrop::drop(pinned, token); | |
| //! } | |
| //! } | |
| //! }; | |
| //! ``` | |
| //! | |
| //! ## `#[pinned_drop]` on `impl PinnedDrop for Foo` | |
| //! | |
| //! This macro is used to implement the `PinnedDrop` trait, since that trait is `unsafe` and has an | |
| //! extra parameter that should not be used at all. The macro hides that parameter. | |
| //! | |
| //! Here is the `PinnedDrop` impl for `Foo`: | |
| //! | |
| //! ```rust,ignore | |
| //! #[pinned_drop] | |
| //! impl PinnedDrop for Foo { | |
| //! fn drop(self: Pin<&mut Self>) { | |
| //! println!("{self:p} is getting dropped."); | |
| //! } | |
| //! } | |
| //! ``` | |
| //! | |
| //! This expands to the following code: | |
| //! | |
| //! ```rust,ignore | |
| //! // `unsafe`, full path and the token parameter are added, everything else stays the same. | |
| //! unsafe impl ::pin_init::PinnedDrop for Foo { | |
| //! fn drop(self: Pin<&mut Self>, _: ::pin_init::__internal::OnlyCallFromDrop) { | |
| //! println!("{self:p} is getting dropped."); | |
| //! } | |
| //! } | |
| //! ``` | |
| //! | |
| //! ## `pin_init!` on `Foo` | |
| //! | |
| //! Since we already took a look at `pin_init!` on `Bar`, this section will only show the expansion | |
| //! of `pin_init!` on `Foo`: | |
| //! | |
| //! ```rust,ignore | |
| //! let a = 42; | |
| //! let initializer = pin_init!(Foo { | |
| //! a, | |
| //! b <- Bar::new(36), | |
| //! }); | |
| //! ``` | |
| //! | |
| //! This expands to the following code: | |
| //! | |
| //! ```rust,ignore | |
| //! let a = 42; | |
| //! let initializer = { | |
| //! struct __InitOk; | |
| //! let data = unsafe { | |
| //! use ::pin_init::__internal::HasPinData; | |
| //! Foo::__pin_data() | |
| //! }; | |
| //! let init = ::pin_init::__internal::PinData::make_closure::< | |
| //! _, | |
| //! __InitOk, | |
| //! ::core::convert::Infallible, | |
| //! >(data, move |slot| { | |
| //! { | |
| //! struct __InitOk; | |
| //! { | |
| //! unsafe { ::core::ptr::write(::core::addr_of_mut!((*slot).a), a) }; | |
| //! } | |
| //! let __a_guard = unsafe { | |
| //! ::pin_init::__internal::DropGuard::new(::core::addr_of_mut!((*slot).a)) | |
| //! }; | |
| //! let init = Bar::new(36); | |
| //! unsafe { data.b(::core::addr_of_mut!((*slot).b), b)? }; | |
| //! let __b_guard = unsafe { | |
| //! ::pin_init::__internal::DropGuard::new(::core::addr_of_mut!((*slot).b)) | |
| //! }; | |
| //! ::core::mem::forget(__b_guard); | |
| //! ::core::mem::forget(__a_guard); | |
| //! #[allow(unreachable_code, clippy::diverging_sub_expression)] | |
| //! let _ = || { | |
| //! unsafe { | |
| //! ::core::ptr::write( | |
| //! slot, | |
| //! Foo { | |
| //! a: ::core::panic!(), | |
| //! b: ::core::panic!(), | |
| //! }, | |
| //! ); | |
| //! }; | |
| //! }; | |
| //! } | |
| //! Ok(__InitOk) | |
| //! }); | |
| //! let init = move | | |
| //! slot, | |
| //! | -> ::core::result::Result<(), ::core::convert::Infallible> { | |
| //! init(slot).map(|__InitOk| ()) | |
| //! }; | |
| //! let init = unsafe { | |
| //! ::pin_init::pin_init_from_closure::<_, ::core::convert::Infallible>(init) | |
| //! }; | |
| //! init | |
| //! }; | |
| //! ``` | |
| #[cfg(kernel)] | |
| pub use ::macros::paste; | |
| #[cfg(not(kernel))] | |
| pub use ::paste::paste; | |
| /// Creates a `unsafe impl<...> PinnedDrop for $type` block. | |
| /// | |
| /// See [`PinnedDrop`] for more information. | |
| #[doc(hidden)] | |
| #[macro_export] | |
| macro_rules! __pinned_drop { | |
| ( | |
| @impl_sig($($impl_sig:tt)*), | |
| @impl_body( | |
| $(#[$($attr:tt)*])* | |
| fn drop($($sig:tt)*) { | |
| $($inner:tt)* | |
| } | |
| ), | |
| ) => { | |
| // SAFETY: TODO. | |
| unsafe $($impl_sig)* { | |
| // Inherit all attributes and the type/ident tokens for the signature. | |
| $(#[$($attr)*])* | |
| fn drop($($sig)*, _: $crate::__internal::OnlyCallFromDrop) { | |
| $($inner)* | |
| } | |
| } | |
| } | |
| } | |
| /// This macro first parses the struct definition such that it separates pinned and not pinned | |
| /// fields. Afterwards it declares the struct and implement the `PinData` trait safely. | |
| #[doc(hidden)] | |
| #[macro_export] | |
| macro_rules! __pin_data { | |
| // Proc-macro entry point, this is supplied by the proc-macro pre-parsing. | |
| (parse_input: | |
| @args($($pinned_drop:ident)?), | |
| @sig( | |
| $(#[$($struct_attr:tt)*])* | |
| $vis:vis struct $name:ident | |
| $(where $($whr:tt)*)? | |
| ), | |
| @impl_generics($($impl_generics:tt)*), | |
| @ty_generics($($ty_generics:tt)*), | |
| @decl_generics($($decl_generics:tt)*), | |
| @body({ $($fields:tt)* }), | |
| ) => { | |
| // We now use token munching to iterate through all of the fields. While doing this we | |
| // identify fields marked with `#[pin]`, these fields are the 'pinned fields'. The user | |
| // wants these to be structurally pinned. The rest of the fields are the | |
| // 'not pinned fields'. Additionally we collect all fields, since we need them in the right | |
| // order to declare the struct. | |
| // | |
| // In this call we also put some explaining comments for the parameters. | |
| $crate::__pin_data!(find_pinned_fields: | |
| // Attributes on the struct itself, these will just be propagated to be put onto the | |
| // struct definition. | |
| @struct_attrs($(#[$($struct_attr)*])*), | |
| // The visibility of the struct. | |
| @vis($vis), | |
| // The name of the struct. | |
| @name($name), | |
| // The 'impl generics', the generics that will need to be specified on the struct inside | |
| // of an `impl<$ty_generics>` block. | |
| @impl_generics($($impl_generics)*), | |
| // The 'ty generics', the generics that will need to be specified on the impl blocks. | |
| @ty_generics($($ty_generics)*), | |
| // The 'decl generics', the generics that need to be specified on the struct | |
| // definition. | |
| @decl_generics($($decl_generics)*), | |
| // The where clause of any impl block and the declaration. | |
| @where($($($whr)*)?), | |
| // The remaining fields tokens that need to be processed. | |
| // We add a `,` at the end to ensure correct parsing. | |
| @fields_munch($($fields)* ,), | |
| // The pinned fields. | |
| @pinned(), | |
| // The not pinned fields. | |
| @not_pinned(), | |
| // All fields. | |
| @fields(), | |
| // The accumulator containing all attributes already parsed. | |
| @accum(), | |
| // Contains `yes` or `` to indicate if `#[pin]` was found on the current field. | |
| @is_pinned(), | |
| // The proc-macro argument, this should be `PinnedDrop` or ``. | |
| @pinned_drop($($pinned_drop)?), | |
| ); | |
| }; | |
| (find_pinned_fields: | |
| @struct_attrs($($struct_attrs:tt)*), | |
| @vis($vis:vis), | |
| @name($name:ident), | |
| @impl_generics($($impl_generics:tt)*), | |
| @ty_generics($($ty_generics:tt)*), | |
| @decl_generics($($decl_generics:tt)*), | |
| @where($($whr:tt)*), | |
| // We found a PhantomPinned field, this should generally be pinned! | |
| @fields_munch($field:ident : $($($(::)?core::)?marker::)?PhantomPinned, $($rest:tt)*), | |
| @pinned($($pinned:tt)*), | |
| @not_pinned($($not_pinned:tt)*), | |
| @fields($($fields:tt)*), | |
| @accum($($accum:tt)*), | |
| // This field is not pinned. | |
| @is_pinned(), | |
| @pinned_drop($($pinned_drop:ident)?), | |
| ) => { | |
| ::core::compile_error!(concat!( | |
| "The field `", | |
| stringify!($field), | |
| "` of type `PhantomPinned` only has an effect, if it has the `#[pin]` attribute.", | |
| )); | |
| $crate::__pin_data!(find_pinned_fields: | |
| @struct_attrs($($struct_attrs)*), | |
| @vis($vis), | |
| @name($name), | |
| @impl_generics($($impl_generics)*), | |
| @ty_generics($($ty_generics)*), | |
| @decl_generics($($decl_generics)*), | |
| @where($($whr)*), | |
| @fields_munch($($rest)*), | |
| @pinned($($pinned)* $($accum)* $field: ::core::marker::PhantomPinned,), | |
| @not_pinned($($not_pinned)*), | |
| @fields($($fields)* $($accum)* $field: ::core::marker::PhantomPinned,), | |
| @accum(), | |
| @is_pinned(), | |
| @pinned_drop($($pinned_drop)?), | |
| ); | |
| }; | |
| (find_pinned_fields: | |
| @struct_attrs($($struct_attrs:tt)*), | |
| @vis($vis:vis), | |
| @name($name:ident), | |
| @impl_generics($($impl_generics:tt)*), | |
| @ty_generics($($ty_generics:tt)*), | |
| @decl_generics($($decl_generics:tt)*), | |
| @where($($whr:tt)*), | |
| // We reached the field declaration. | |
| @fields_munch($field:ident : $type:ty, $($rest:tt)*), | |
| @pinned($($pinned:tt)*), | |
| @not_pinned($($not_pinned:tt)*), | |
| @fields($($fields:tt)*), | |
| @accum($($accum:tt)*), | |
| // This field is pinned. | |
| @is_pinned(yes), | |
| @pinned_drop($($pinned_drop:ident)?), | |
| ) => { | |
| $crate::__pin_data!(find_pinned_fields: | |
| @struct_attrs($($struct_attrs)*), | |
| @vis($vis), | |
| @name($name), | |
| @impl_generics($($impl_generics)*), | |
| @ty_generics($($ty_generics)*), | |
| @decl_generics($($decl_generics)*), | |
| @where($($whr)*), | |
| @fields_munch($($rest)*), | |
| @pinned($($pinned)* $($accum)* $field: $type,), | |
| @not_pinned($($not_pinned)*), | |
| @fields($($fields)* $($accum)* $field: $type,), | |
| @accum(), | |
| @is_pinned(), | |
| @pinned_drop($($pinned_drop)?), | |
| ); | |
| }; | |
| (find_pinned_fields: | |
| @struct_attrs($($struct_attrs:tt)*), | |
| @vis($vis:vis), | |
| @name($name:ident), | |
| @impl_generics($($impl_generics:tt)*), | |
| @ty_generics($($ty_generics:tt)*), | |
| @decl_generics($($decl_generics:tt)*), | |
| @where($($whr:tt)*), | |
| // We reached the field declaration. | |
| @fields_munch($field:ident : $type:ty, $($rest:tt)*), | |
| @pinned($($pinned:tt)*), | |
| @not_pinned($($not_pinned:tt)*), | |
| @fields($($fields:tt)*), | |
| @accum($($accum:tt)*), | |
| // This field is not pinned. | |
| @is_pinned(), | |
| @pinned_drop($($pinned_drop:ident)?), | |
| ) => { | |
| $crate::__pin_data!(find_pinned_fields: | |
| @struct_attrs($($struct_attrs)*), | |
| @vis($vis), | |
| @name($name), | |
| @impl_generics($($impl_generics)*), | |
| @ty_generics($($ty_generics)*), | |
| @decl_generics($($decl_generics)*), | |
| @where($($whr)*), | |
| @fields_munch($($rest)*), | |
| @pinned($($pinned)*), | |
| @not_pinned($($not_pinned)* $($accum)* $field: $type,), | |
| @fields($($fields)* $($accum)* $field: $type,), | |
| @accum(), | |
| @is_pinned(), | |
| @pinned_drop($($pinned_drop)?), | |
| ); | |
| }; | |
| (find_pinned_fields: | |
| @struct_attrs($($struct_attrs:tt)*), | |
| @vis($vis:vis), | |
| @name($name:ident), | |
| @impl_generics($($impl_generics:tt)*), | |
| @ty_generics($($ty_generics:tt)*), | |
| @decl_generics($($decl_generics:tt)*), | |
| @where($($whr:tt)*), | |
| // We found the `#[pin]` attr. | |
| @fields_munch(#[pin] $($rest:tt)*), | |
| @pinned($($pinned:tt)*), | |
| @not_pinned($($not_pinned:tt)*), | |
| @fields($($fields:tt)*), | |
| @accum($($accum:tt)*), | |
| @is_pinned($($is_pinned:ident)?), | |
| @pinned_drop($($pinned_drop:ident)?), | |
| ) => { | |
| $crate::__pin_data!(find_pinned_fields: | |
| @struct_attrs($($struct_attrs)*), | |
| @vis($vis), | |
| @name($name), | |
| @impl_generics($($impl_generics)*), | |
| @ty_generics($($ty_generics)*), | |
| @decl_generics($($decl_generics)*), | |
| @where($($whr)*), | |
| @fields_munch($($rest)*), | |
| // We do not include `#[pin]` in the list of attributes, since it is not actually an | |
| // attribute that is defined somewhere. | |
| @pinned($($pinned)*), | |
| @not_pinned($($not_pinned)*), | |
| @fields($($fields)*), | |
| @accum($($accum)*), | |
| // Set this to `yes`. | |
| @is_pinned(yes), | |
| @pinned_drop($($pinned_drop)?), | |
| ); | |
| }; | |
| (find_pinned_fields: | |
| @struct_attrs($($struct_attrs:tt)*), | |
| @vis($vis:vis), | |
| @name($name:ident), | |
| @impl_generics($($impl_generics:tt)*), | |
| @ty_generics($($ty_generics:tt)*), | |
| @decl_generics($($decl_generics:tt)*), | |
| @where($($whr:tt)*), | |
| // We reached the field declaration with visibility, for simplicity we only munch the | |
| // visibility and put it into `$accum`. | |
| @fields_munch($fvis:vis $field:ident $($rest:tt)*), | |
| @pinned($($pinned:tt)*), | |
| @not_pinned($($not_pinned:tt)*), | |
| @fields($($fields:tt)*), | |
| @accum($($accum:tt)*), | |
| @is_pinned($($is_pinned:ident)?), | |
| @pinned_drop($($pinned_drop:ident)?), | |
| ) => { | |
| $crate::__pin_data!(find_pinned_fields: | |
| @struct_attrs($($struct_attrs)*), | |
| @vis($vis), | |
| @name($name), | |
| @impl_generics($($impl_generics)*), | |
| @ty_generics($($ty_generics)*), | |
| @decl_generics($($decl_generics)*), | |
| @where($($whr)*), | |
| @fields_munch($field $($rest)*), | |
| @pinned($($pinned)*), | |
| @not_pinned($($not_pinned)*), | |
| @fields($($fields)*), | |
| @accum($($accum)* $fvis), | |
| @is_pinned($($is_pinned)?), | |
| @pinned_drop($($pinned_drop)?), | |
| ); | |
| }; | |
| (find_pinned_fields: | |
| @struct_attrs($($struct_attrs:tt)*), | |
| @vis($vis:vis), | |
| @name($name:ident), | |
| @impl_generics($($impl_generics:tt)*), | |
| @ty_generics($($ty_generics:tt)*), | |
| @decl_generics($($decl_generics:tt)*), | |
| @where($($whr:tt)*), | |
| // Some other attribute, just put it into `$accum`. | |
| @fields_munch(#[$($attr:tt)*] $($rest:tt)*), | |
| @pinned($($pinned:tt)*), | |
| @not_pinned($($not_pinned:tt)*), | |
| @fields($($fields:tt)*), | |
| @accum($($accum:tt)*), | |
| @is_pinned($($is_pinned:ident)?), | |
| @pinned_drop($($pinned_drop:ident)?), | |
| ) => { | |
| $crate::__pin_data!(find_pinned_fields: | |
| @struct_attrs($($struct_attrs)*), | |
| @vis($vis), | |
| @name($name), | |
| @impl_generics($($impl_generics)*), | |
| @ty_generics($($ty_generics)*), | |
| @decl_generics($($decl_generics)*), | |
| @where($($whr)*), | |
| @fields_munch($($rest)*), | |
| @pinned($($pinned)*), | |
| @not_pinned($($not_pinned)*), | |
| @fields($($fields)*), | |
| @accum($($accum)* #[$($attr)*]), | |
| @is_pinned($($is_pinned)?), | |
| @pinned_drop($($pinned_drop)?), | |
| ); | |
| }; | |
| (find_pinned_fields: | |
| @struct_attrs($($struct_attrs:tt)*), | |
| @vis($vis:vis), | |
| @name($name:ident), | |
| @impl_generics($($impl_generics:tt)*), | |
| @ty_generics($($ty_generics:tt)*), | |
| @decl_generics($($decl_generics:tt)*), | |
| @where($($whr:tt)*), | |
| // We reached the end of the fields, plus an optional additional comma, since we added one | |
| // before and the user is also allowed to put a trailing comma. | |
| @fields_munch($(,)?), | |
| @pinned($($pinned:tt)*), | |
| @not_pinned($($not_pinned:tt)*), | |
| @fields($($fields:tt)*), | |
| @accum(), | |
| @is_pinned(), | |
| @pinned_drop($($pinned_drop:ident)?), | |
| ) => { | |
| // Declare the struct with all fields in the correct order. | |
| $($struct_attrs)* | |
| $vis struct $name <$($decl_generics)*> | |
| where $($whr)* | |
| { | |
| $($fields)* | |
| } | |
| $crate::__pin_data!(make_pin_projections: | |
| @vis($vis), | |
| @name($name), | |
| @impl_generics($($impl_generics)*), | |
| @ty_generics($($ty_generics)*), | |
| @decl_generics($($decl_generics)*), | |
| @where($($whr)*), | |
| @pinned($($pinned)*), | |
| @not_pinned($($not_pinned)*), | |
| ); | |
| // We put the rest into this const item, because it then will not be accessible to anything | |
| // outside. | |
| const _: () = { | |
| // We declare this struct which will host all of the projection function for our type. | |
| // it will be invariant over all generic parameters which are inherited from the | |
| // struct. | |
| $vis struct __ThePinData<$($impl_generics)*> | |
| where $($whr)* | |
| { | |
| __phantom: ::core::marker::PhantomData< | |
| fn($name<$($ty_generics)*>) -> $name<$($ty_generics)*> | |
| >, | |
| } | |
| impl<$($impl_generics)*> ::core::clone::Clone for __ThePinData<$($ty_generics)*> | |
| where $($whr)* | |
| { | |
| fn clone(&self) -> Self { *self } | |
| } | |
| impl<$($impl_generics)*> ::core::marker::Copy for __ThePinData<$($ty_generics)*> | |
| where $($whr)* | |
| {} | |
| // Make all projection functions. | |
| $crate::__pin_data!(make_pin_data: | |
| @pin_data(__ThePinData), | |
| @impl_generics($($impl_generics)*), | |
| @ty_generics($($ty_generics)*), | |
| @where($($whr)*), | |
| @pinned($($pinned)*), | |
| @not_pinned($($not_pinned)*), | |
| ); | |
| // SAFETY: We have added the correct projection functions above to `__ThePinData` and | |
| // we also use the least restrictive generics possible. | |
| unsafe impl<$($impl_generics)*> | |
| $crate::__internal::HasPinData for $name<$($ty_generics)*> | |
| where $($whr)* | |
| { | |
| type PinData = __ThePinData<$($ty_generics)*>; | |
| unsafe fn __pin_data() -> Self::PinData { | |
| __ThePinData { __phantom: ::core::marker::PhantomData } | |
| } | |
| } | |
| // SAFETY: TODO. | |
| unsafe impl<$($impl_generics)*> | |
| $crate::__internal::PinData for __ThePinData<$($ty_generics)*> | |
| where $($whr)* | |
| { | |
| type Datee = $name<$($ty_generics)*>; | |
| } | |
| // This struct will be used for the unpin analysis. Since only structurally pinned | |
| // fields are relevant whether the struct should implement `Unpin`. | |
| #[allow(dead_code)] | |
| struct __Unpin <'__pin, $($impl_generics)*> | |
| where $($whr)* | |
| { | |
| __phantom_pin: ::core::marker::PhantomData<fn(&'__pin ()) -> &'__pin ()>, | |
| __phantom: ::core::marker::PhantomData< | |
| fn($name<$($ty_generics)*>) -> $name<$($ty_generics)*> | |
| >, | |
| // Only the pinned fields. | |
| $($pinned)* | |
| } | |
| #[doc(hidden)] | |
| impl<'__pin, $($impl_generics)*> ::core::marker::Unpin for $name<$($ty_generics)*> | |
| where | |
| __Unpin<'__pin, $($ty_generics)*>: ::core::marker::Unpin, | |
| $($whr)* | |
| {} | |
| // We need to disallow normal `Drop` implementation, the exact behavior depends on | |
| // whether `PinnedDrop` was specified as the parameter. | |
| $crate::__pin_data!(drop_prevention: | |
| @name($name), | |
| @impl_generics($($impl_generics)*), | |
| @ty_generics($($ty_generics)*), | |
| @where($($whr)*), | |
| @pinned_drop($($pinned_drop)?), | |
| ); | |
| }; | |
| }; | |
| // When no `PinnedDrop` was specified, then we have to prevent implementing drop. | |
| (drop_prevention: | |
| @name($name:ident), | |
| @impl_generics($($impl_generics:tt)*), | |
| @ty_generics($($ty_generics:tt)*), | |
| @where($($whr:tt)*), | |
| @pinned_drop(), | |
| ) => { | |
| // We prevent this by creating a trait that will be implemented for all types implementing | |
| // `Drop`. Additionally we will implement this trait for the struct leading to a conflict, | |
| // if it also implements `Drop` | |
| trait MustNotImplDrop {} | |
| #[expect(drop_bounds)] | |
| impl<T: ::core::ops::Drop> MustNotImplDrop for T {} | |
| impl<$($impl_generics)*> MustNotImplDrop for $name<$($ty_generics)*> | |
| where $($whr)* {} | |
| // We also take care to prevent users from writing a useless `PinnedDrop` implementation. | |
| // They might implement `PinnedDrop` correctly for the struct, but forget to give | |
| // `PinnedDrop` as the parameter to `#[pin_data]`. | |
| #[expect(non_camel_case_types)] | |
| trait UselessPinnedDropImpl_you_need_to_specify_PinnedDrop {} | |
| impl<T: $crate::PinnedDrop> | |
| UselessPinnedDropImpl_you_need_to_specify_PinnedDrop for T {} | |
| impl<$($impl_generics)*> | |
| UselessPinnedDropImpl_you_need_to_specify_PinnedDrop for $name<$($ty_generics)*> | |
| where $($whr)* {} | |
| }; | |
| // When `PinnedDrop` was specified we just implement `Drop` and delegate. | |
| (drop_prevention: | |
| @name($name:ident), | |
| @impl_generics($($impl_generics:tt)*), | |
| @ty_generics($($ty_generics:tt)*), | |
| @where($($whr:tt)*), | |
| @pinned_drop(PinnedDrop), | |
| ) => { | |
| impl<$($impl_generics)*> ::core::ops::Drop for $name<$($ty_generics)*> | |
| where $($whr)* | |
| { | |
| fn drop(&mut self) { | |
| // SAFETY: Since this is a destructor, `self` will not move after this function | |
| // terminates, since it is inaccessible. | |
| let pinned = unsafe { ::core::pin::Pin::new_unchecked(self) }; | |
| // SAFETY: Since this is a drop function, we can create this token to call the | |
| // pinned destructor of this type. | |
| let token = unsafe { $crate::__internal::OnlyCallFromDrop::new() }; | |
| $crate::PinnedDrop::drop(pinned, token); | |
| } | |
| } | |
| }; | |
| // If some other parameter was specified, we emit a readable error. | |
| (drop_prevention: | |
| @name($name:ident), | |
| @impl_generics($($impl_generics:tt)*), | |
| @ty_generics($($ty_generics:tt)*), | |
| @where($($whr:tt)*), | |
| @pinned_drop($($rest:tt)*), | |
| ) => { | |
| compile_error!( | |
| "Wrong parameters to `#[pin_data]`, expected nothing or `PinnedDrop`, got '{}'.", | |
| stringify!($($rest)*), | |
| ); | |
| }; | |
| (make_pin_projections: | |
| @vis($vis:vis), | |
| @name($name:ident), | |
| @impl_generics($($impl_generics:tt)*), | |
| @ty_generics($($ty_generics:tt)*), | |
| @decl_generics($($decl_generics:tt)*), | |
| @where($($whr:tt)*), | |
| @pinned($($(#[$($p_attr:tt)*])* $pvis:vis $p_field:ident : $p_type:ty),* $(,)?), | |
| @not_pinned($($(#[$($attr:tt)*])* $fvis:vis $field:ident : $type:ty),* $(,)?), | |
| ) => { | |
| $crate::macros::paste! { | |
| #[doc(hidden)] | |
| $vis struct [< $name Projection >] <'__pin, $($decl_generics)*> { | |
| $($(#[$($p_attr)*])* $pvis $p_field : ::core::pin::Pin<&'__pin mut $p_type>,)* | |
| $($(#[$($attr)*])* $fvis $field : &'__pin mut $type,)* | |
| ___pin_phantom_data: ::core::marker::PhantomData<&'__pin mut ()>, | |
| } | |
| impl<$($impl_generics)*> $name<$($ty_generics)*> | |
| where $($whr)* | |
| { | |
| /// Pin-projects all fields of `Self`. | |
| /// | |
| /// These fields are structurally pinned: | |
| $(#[doc = ::core::concat!(" - `", ::core::stringify!($p_field), "`")])* | |
| /// | |
| /// These fields are **not** structurally pinned: | |
| $(#[doc = ::core::concat!(" - `", ::core::stringify!($field), "`")])* | |
| #[inline] | |
| $vis fn project<'__pin>( | |
| self: ::core::pin::Pin<&'__pin mut Self>, | |
| ) -> [< $name Projection >] <'__pin, $($ty_generics)*> { | |
| // SAFETY: we only give access to `&mut` for fields not structurally pinned. | |
| let this = unsafe { ::core::pin::Pin::get_unchecked_mut(self) }; | |
| [< $name Projection >] { | |
| $( | |
| // SAFETY: `$p_field` is structurally pinned. | |
| $(#[$($p_attr)*])* | |
| $p_field : unsafe { ::core::pin::Pin::new_unchecked(&mut this.$p_field) }, | |
| )* | |
| $( | |
| $(#[$($attr)*])* | |
| $field : &mut this.$field, | |
| )* | |
| ___pin_phantom_data: ::core::marker::PhantomData, | |
| } | |
| } | |
| } | |
| } | |
| }; | |
| (make_pin_data: | |
| @pin_data($pin_data:ident), | |
| @impl_generics($($impl_generics:tt)*), | |
| @ty_generics($($ty_generics:tt)*), | |
| @where($($whr:tt)*), | |
| @pinned($($(#[$($p_attr:tt)*])* $pvis:vis $p_field:ident : $p_type:ty),* $(,)?), | |
| @not_pinned($($(#[$($attr:tt)*])* $fvis:vis $field:ident : $type:ty),* $(,)?), | |
| ) => { | |
| $crate::macros::paste! { | |
| // For every field, we create a projection function according to its projection type. If a | |
| // field is structurally pinned, then it must be initialized via `PinInit`, if it is not | |
| // structurally pinned, then it can be initialized via `Init`. | |
| // | |
| // The functions are `unsafe` to prevent accidentally calling them. | |
| #[allow(dead_code)] | |
| #[expect(clippy::missing_safety_doc)] | |
| impl<$($impl_generics)*> $pin_data<$($ty_generics)*> | |
| where $($whr)* | |
| { | |
| $( | |
| $(#[$($p_attr)*])* | |
| $pvis unsafe fn $p_field<E>( | |
| self, | |
| slot: *mut $p_type, | |
| init: impl $crate::PinInit<$p_type, E>, | |
| ) -> ::core::result::Result<(), E> { | |
| // SAFETY: TODO. | |
| unsafe { $crate::PinInit::__pinned_init(init, slot) } | |
| } | |
| $(#[$($p_attr)*])* | |
| $pvis unsafe fn [<__project_ $p_field>]<'__slot>( | |
| self, | |
| slot: &'__slot mut $p_type, | |
| ) -> ::core::pin::Pin<&'__slot mut $p_type> { | |
| ::core::pin::Pin::new_unchecked(slot) | |
| } | |
| )* | |
| $( | |
| $(#[$($attr)*])* | |
| $fvis unsafe fn $field<E>( | |
| self, | |
| slot: *mut $type, | |
| init: impl $crate::Init<$type, E>, | |
| ) -> ::core::result::Result<(), E> { | |
| // SAFETY: TODO. | |
| unsafe { $crate::Init::__init(init, slot) } | |
| } | |
| $(#[$($attr)*])* | |
| $fvis unsafe fn [<__project_ $field>]<'__slot>( | |
| self, | |
| slot: &'__slot mut $type, | |
| ) -> &'__slot mut $type { | |
| slot | |
| } | |
| )* | |
| } | |
| } | |
| }; | |
| } | |
| /// The internal init macro. Do not call manually! | |
| /// | |
| /// This is called by the `{try_}{pin_}init!` macros with various inputs. | |
| /// | |
| /// This macro has multiple internal call configurations, these are always the very first ident: | |
| /// - nothing: this is the base case and called by the `{try_}{pin_}init!` macros. | |
| /// - `with_update_parsed`: when the `..Zeroable::init_zeroed()` syntax has been handled. | |
| /// - `init_slot`: recursively creates the code that initializes all fields in `slot`. | |
| /// - `make_initializer`: recursively create the struct initializer that guarantees that every | |
| /// field has been initialized exactly once. | |
| #[doc(hidden)] | |
| #[macro_export] | |
| macro_rules! __init_internal { | |
| ( | |
| @this($($this:ident)?), | |
| @typ($t:path), | |
| @fields($($fields:tt)*), | |
| @error($err:ty), | |
| // Either `PinData` or `InitData`, `$use_data` should only be present in the `PinData` | |
| // case. | |
| @data($data:ident, $($use_data:ident)?), | |
| // `HasPinData` or `HasInitData`. | |
| @has_data($has_data:ident, $get_data:ident), | |
| // `pin_init_from_closure` or `init_from_closure`. | |
| @construct_closure($construct_closure:ident), | |
| @munch_fields(), | |
| ) => { | |
| $crate::__init_internal!(with_update_parsed: | |
| @this($($this)?), | |
| @typ($t), | |
| @fields($($fields)*), | |
| @error($err), | |
| @data($data, $($use_data)?), | |
| @has_data($has_data, $get_data), | |
| @construct_closure($construct_closure), | |
| @init_zeroed(), // Nothing means default behavior. | |
| ) | |
| }; | |
| ( | |
| @this($($this:ident)?), | |
| @typ($t:path), | |
| @fields($($fields:tt)*), | |
| @error($err:ty), | |
| // Either `PinData` or `InitData`, `$use_data` should only be present in the `PinData` | |
| // case. | |
| @data($data:ident, $($use_data:ident)?), | |
| // `HasPinData` or `HasInitData`. | |
| @has_data($has_data:ident, $get_data:ident), | |
| // `pin_init_from_closure` or `init_from_closure`. | |
| @construct_closure($construct_closure:ident), | |
| @munch_fields(..Zeroable::init_zeroed()), | |
| ) => { | |
| $crate::__init_internal!(with_update_parsed: | |
| @this($($this)?), | |
| @typ($t), | |
| @fields($($fields)*), | |
| @error($err), | |
| @data($data, $($use_data)?), | |
| @has_data($has_data, $get_data), | |
| @construct_closure($construct_closure), | |
| @init_zeroed(()), // `()` means zero all fields not mentioned. | |
| ) | |
| }; | |
| ( | |
| @this($($this:ident)?), | |
| @typ($t:path), | |
| @fields($($fields:tt)*), | |
| @error($err:ty), | |
| // Either `PinData` or `InitData`, `$use_data` should only be present in the `PinData` | |
| // case. | |
| @data($data:ident, $($use_data:ident)?), | |
| // `HasPinData` or `HasInitData`. | |
| @has_data($has_data:ident, $get_data:ident), | |
| // `pin_init_from_closure` or `init_from_closure`. | |
| @construct_closure($construct_closure:ident), | |
| @munch_fields($ignore:tt $($rest:tt)*), | |
| ) => { | |
| $crate::__init_internal!( | |
| @this($($this)?), | |
| @typ($t), | |
| @fields($($fields)*), | |
| @error($err), | |
| @data($data, $($use_data)?), | |
| @has_data($has_data, $get_data), | |
| @construct_closure($construct_closure), | |
| @munch_fields($($rest)*), | |
| ) | |
| }; | |
| (with_update_parsed: | |
| @this($($this:ident)?), | |
| @typ($t:path), | |
| @fields($($fields:tt)*), | |
| @error($err:ty), | |
| // Either `PinData` or `InitData`, `$use_data` should only be present in the `PinData` | |
| // case. | |
| @data($data:ident, $($use_data:ident)?), | |
| // `HasPinData` or `HasInitData`. | |
| @has_data($has_data:ident, $get_data:ident), | |
| // `pin_init_from_closure` or `init_from_closure`. | |
| @construct_closure($construct_closure:ident), | |
| @init_zeroed($($init_zeroed:expr)?), | |
| ) => {{ | |
| // We do not want to allow arbitrary returns, so we declare this type as the `Ok` return | |
| // type and shadow it later when we insert the arbitrary user code. That way there will be | |
| // no possibility of returning without `unsafe`. | |
| struct __InitOk; | |
| // Get the data about fields from the supplied type. | |
| // | |
| // SAFETY: TODO. | |
| let data = unsafe { | |
| use $crate::__internal::$has_data; | |
| // Here we abuse `paste!` to retokenize `$t`. Declarative macros have some internal | |
| // information that is associated to already parsed fragments, so a path fragment | |
| // cannot be used in this position. Doing the retokenization results in valid rust | |
| // code. | |
| $crate::macros::paste!($t::$get_data()) | |
| }; | |
| // Ensure that `data` really is of type `$data` and help with type inference: | |
| let init = $crate::__internal::$data::make_closure::<_, __InitOk, $err>( | |
| data, | |
| move |slot| { | |
| { | |
| // Shadow the structure so it cannot be used to return early. | |
| struct __InitOk; | |
| // If `$init_zeroed` is present we should zero the slot now and not emit an | |
| // error when fields are missing (since they will be zeroed). We also have to | |
| // check that the type actually implements `Zeroable`. | |
| $({ | |
| fn assert_zeroable<T: $crate::Zeroable>(_: *mut T) {} | |
| // Ensure that the struct is indeed `Zeroable`. | |
| assert_zeroable(slot); | |
| // SAFETY: The type implements `Zeroable` by the check above. | |
| unsafe { ::core::ptr::write_bytes(slot, 0, 1) }; | |
| $init_zeroed // This will be `()` if set. | |
| })? | |
| // Create the `this` so it can be referenced by the user inside of the | |
| // expressions creating the individual fields. | |
| $(let $this = unsafe { ::core::ptr::NonNull::new_unchecked(slot) };)? | |
| // Initialize every field. | |
| $crate::__init_internal!(init_slot($($use_data)?): | |
| @data(data), | |
| @slot(slot), | |
| @guards(), | |
| @munch_fields($($fields)*,), | |
| ); | |
| // We use unreachable code to ensure that all fields have been mentioned exactly | |
| // once, this struct initializer will still be type-checked and complain with a | |
| // very natural error message if a field is forgotten/mentioned more than once. | |
| #[allow(unreachable_code, clippy::diverging_sub_expression)] | |
| let _ = || { | |
| $crate::__init_internal!(make_initializer: | |
| @slot(slot), | |
| @type_name($t), | |
| @munch_fields($($fields)*,), | |
| @acc(), | |
| ); | |
| }; | |
| } | |
| Ok(__InitOk) | |
| } | |
| ); | |
| let init = move |slot| -> ::core::result::Result<(), $err> { | |
| init(slot).map(|__InitOk| ()) | |
| }; | |
| // SAFETY: TODO. | |
| let init = unsafe { $crate::$construct_closure::<_, $err>(init) }; | |
| init | |
| }}; | |
| (init_slot($($use_data:ident)?): | |
| @data($data:ident), | |
| @slot($slot:ident), | |
| @guards($($guards:ident,)*), | |
| @munch_fields($(..Zeroable::init_zeroed())? $(,)?), | |
| ) => { | |
| // Endpoint of munching, no fields are left. If execution reaches this point, all fields | |
| // have been initialized. Therefore we can now dismiss the guards by forgetting them. | |
| $(::core::mem::forget($guards);)* | |
| }; | |
| (init_slot($($use_data:ident)?): | |
| @data($data:ident), | |
| @slot($slot:ident), | |
| @guards($($guards:ident,)*), | |
| // arbitrary code block | |
| @munch_fields(_: { $($code:tt)* }, $($rest:tt)*), | |
| ) => { | |
| { $($code)* } | |
| $crate::__init_internal!(init_slot($($use_data)?): | |
| @data($data), | |
| @slot($slot), | |
| @guards($($guards,)*), | |
| @munch_fields($($rest)*), | |
| ); | |
| }; | |
| (init_slot($use_data:ident): // `use_data` is present, so we use the `data` to init fields. | |
| @data($data:ident), | |
| @slot($slot:ident), | |
| @guards($($guards:ident,)*), | |
| // In-place initialization syntax. | |
| @munch_fields($field:ident <- $val:expr, $($rest:tt)*), | |
| ) => { | |
| let init = $val; | |
| // Call the initializer. | |
| // | |
| // SAFETY: `slot` is valid, because we are inside of an initializer closure, we | |
| // return when an error/panic occurs. | |
| // We also use the `data` to require the correct trait (`Init` or `PinInit`) for `$field`. | |
| unsafe { $data.$field(::core::ptr::addr_of_mut!((*$slot).$field), init)? }; | |
| // NOTE: this ensures that the initialized field is properly aligned. | |
| // Unaligned fields will cause the compiler to emit E0793. We do not support | |
| // unaligned fields since `Init::__init` requires an aligned pointer; the call to | |
| // `ptr::write` below has the same requirement. | |
| // SAFETY: the field has been initialized. | |
| let _ = unsafe { &mut (*$slot).$field }; | |
| // Create the drop guard: | |
| // | |
| // We rely on macro hygiene to make it impossible for users to access this local variable. | |
| // We use `paste!` to create new hygiene for `$field`. | |
| $crate::macros::paste! { | |
| // SAFETY: | |
| // - `addr_of_mut!((*$slot).$field)` is valid. | |
| // - `(*$slot).$field` has been initialized above. | |
| // - We only need the ownership to the pointee back when initialization has | |
| // succeeded, where we `forget` the guard. | |
| let mut [< __ $field _guard >] = unsafe { | |
| $crate::__internal::DropGuard::new(::core::ptr::addr_of_mut!((*$slot).$field)) | |
| }; | |
| // NOTE: The reference is derived from the guard so that it only lives as long as | |
| // the guard does and cannot escape the scope. | |
| #[allow(unused_variables)] | |
| // SAFETY: the project function does the correct field projection. | |
| let $field = unsafe { $data.[< __project_ $field >]([< __ $field _guard >].let_binding()) }; | |
| $crate::__init_internal!(init_slot($use_data): | |
| @data($data), | |
| @slot($slot), | |
| @guards([< __ $field _guard >], $($guards,)*), | |
| @munch_fields($($rest)*), | |
| ); | |
| } | |
| }; | |
| (init_slot(): // No `use_data`, so we use `Init::__init` directly. | |
| @data($data:ident), | |
| @slot($slot:ident), | |
| @guards($($guards:ident,)*), | |
| // In-place initialization syntax. | |
| @munch_fields($field:ident <- $val:expr, $($rest:tt)*), | |
| ) => { | |
| let init = $val; | |
| // Call the initializer. | |
| // | |
| // SAFETY: `slot` is valid, because we are inside of an initializer closure, we | |
| // return when an error/panic occurs. | |
| unsafe { $crate::Init::__init(init, ::core::ptr::addr_of_mut!((*$slot).$field))? }; | |
| // NOTE: this ensures that the initialized field is properly aligned. | |
| // Unaligned fields will cause the compiler to emit E0793. We do not support | |
| // unaligned fields since `Init::__init` requires an aligned pointer; the call to | |
| // `ptr::write` below has the same requirement. | |
| // SAFETY: the field has been initialized. | |
| let _ = unsafe { &mut (*$slot).$field }; | |
| // Create the drop guard: | |
| // | |
| // We rely on macro hygiene to make it impossible for users to access this local variable. | |
| // We use `paste!` to create new hygiene for `$field`. | |
| $crate::macros::paste! { | |
| // SAFETY: | |
| // - `addr_of_mut!((*$slot).$field)` is valid. | |
| // - `(*$slot).$field` has been initialized above. | |
| // - We only need the ownership to the pointee back when initialization has | |
| // succeeded, where we `forget` the guard. | |
| let mut [< __ $field _guard >] = unsafe { | |
| $crate::__internal::DropGuard::new(::core::ptr::addr_of_mut!((*$slot).$field)) | |
| }; | |
| #[allow(unused_variables)] | |
| let $field = [< __ $field _guard >].let_binding(); | |
| $crate::__init_internal!(init_slot(): | |
| @data($data), | |
| @slot($slot), | |
| @guards([< __ $field _guard >], $($guards,)*), | |
| @munch_fields($($rest)*), | |
| ); | |
| } | |
| }; | |
| (init_slot(): // No `use_data`, so all fields are not structurally pinned | |
| @data($data:ident), | |
| @slot($slot:ident), | |
| @guards($($guards:ident,)*), | |
| // Init by-value. | |
| @munch_fields($field:ident $(: $val:expr)?, $($rest:tt)*), | |
| ) => { | |
| { | |
| $(let $field = $val;)? | |
| // Initialize the field. | |
| // | |
| // SAFETY: The memory at `slot` is uninitialized. | |
| unsafe { ::core::ptr::write(::core::ptr::addr_of_mut!((*$slot).$field), $field) }; | |
| } | |
| // NOTE: this ensures that the initialized field is properly aligned. | |
| // Unaligned fields will cause the compiler to emit E0793. We do not support | |
| // unaligned fields since `Init::__init` requires an aligned pointer; the call to | |
| // `ptr::write` below has the same requirement. | |
| // SAFETY: the field has been initialized. | |
| let _ = unsafe { &mut (*$slot).$field }; | |
| // Create the drop guard: | |
| // | |
| // We rely on macro hygiene to make it impossible for users to access this local variable. | |
| // We use `paste!` to create new hygiene for `$field`. | |
| $crate::macros::paste! { | |
| // SAFETY: | |
| // - `addr_of_mut!((*$slot).$field)` is valid. | |
| // - `(*$slot).$field` has been initialized above. | |
| // - We only need the ownership to the pointee back when initialization has | |
| // succeeded, where we `forget` the guard. | |
| let mut [< __ $field _guard >] = unsafe { | |
| $crate::__internal::DropGuard::new(::core::ptr::addr_of_mut!((*$slot).$field)) | |
| }; | |
| #[allow(unused_variables)] | |
| let $field = [< __ $field _guard >].let_binding(); | |
| $crate::__init_internal!(init_slot(): | |
| @data($data), | |
| @slot($slot), | |
| @guards([< __ $field _guard >], $($guards,)*), | |
| @munch_fields($($rest)*), | |
| ); | |
| } | |
| }; | |
| (init_slot($use_data:ident): | |
| @data($data:ident), | |
| @slot($slot:ident), | |
| @guards($($guards:ident,)*), | |
| // Init by-value. | |
| @munch_fields($field:ident $(: $val:expr)?, $($rest:tt)*), | |
| ) => { | |
| { | |
| $(let $field = $val;)? | |
| // Initialize the field. | |
| // | |
| // SAFETY: The memory at `slot` is uninitialized. | |
| unsafe { ::core::ptr::write(::core::ptr::addr_of_mut!((*$slot).$field), $field) }; | |
| } | |
| // NOTE: this ensures that the initialized field is properly aligned. | |
| // Unaligned fields will cause the compiler to emit E0793. We do not support | |
| // unaligned fields since `Init::__init` requires an aligned pointer; the call to | |
| // `ptr::write` below has the same requirement. | |
| // SAFETY: the field has been initialized. | |
| let _ = unsafe { &mut (*$slot).$field }; | |
| // Create the drop guard: | |
| // | |
| // We rely on macro hygiene to make it impossible for users to access this local variable. | |
| // We use `paste!` to create new hygiene for `$field`. | |
| $crate::macros::paste! { | |
| // SAFETY: | |
| // - `addr_of_mut!((*$slot).$field)` is valid. | |
| // - `(*$slot).$field` has been initialized above. | |
| // - We only need the ownership to the pointee back when initialization has | |
| // succeeded, where we `forget` the guard. | |
| let mut [< __ $field _guard >] = unsafe { | |
| $crate::__internal::DropGuard::new(::core::ptr::addr_of_mut!((*$slot).$field)) | |
| }; | |
| // NOTE: The reference is derived from the guard so that it only lives as long as | |
| // the guard does and cannot escape the scope. | |
| #[allow(unused_variables)] | |
| // SAFETY: the project function does the correct field projection. | |
| let $field = unsafe { $data.[< __project_ $field >]([< __ $field _guard >].let_binding()) }; | |
| $crate::__init_internal!(init_slot($use_data): | |
| @data($data), | |
| @slot($slot), | |
| @guards([< __ $field _guard >], $($guards,)*), | |
| @munch_fields($($rest)*), | |
| ); | |
| } | |
| }; | |
| (make_initializer: | |
| @slot($slot:ident), | |
| @type_name($t:path), | |
| @munch_fields(_: { $($code:tt)* }, $($rest:tt)*), | |
| @acc($($acc:tt)*), | |
| ) => { | |
| // code blocks are ignored for the initializer check | |
| $crate::__init_internal!(make_initializer: | |
| @slot($slot), | |
| @type_name($t), | |
| @munch_fields($($rest)*), | |
| @acc($($acc)*), | |
| ); | |
| }; | |
| (make_initializer: | |
| @slot($slot:ident), | |
| @type_name($t:path), | |
| @munch_fields(..Zeroable::init_zeroed() $(,)?), | |
| @acc($($acc:tt)*), | |
| ) => { | |
| // Endpoint, nothing more to munch, create the initializer. Since the users specified | |
| // `..Zeroable::init_zeroed()`, the slot will already have been zeroed and all field that have | |
| // not been overwritten are thus zero and initialized. We still check that all fields are | |
| // actually accessible by using the struct update syntax ourselves. | |
| // We are inside of a closure that is never executed and thus we can abuse `slot` to | |
| // get the correct type inference here: | |
| #[allow(unused_assignments)] | |
| unsafe { | |
| let mut zeroed = ::core::mem::zeroed(); | |
| // We have to use type inference here to make zeroed have the correct type. This does | |
| // not get executed, so it has no effect. | |
| ::core::ptr::write($slot, zeroed); | |
| zeroed = ::core::mem::zeroed(); | |
| // Here we abuse `paste!` to retokenize `$t`. Declarative macros have some internal | |
| // information that is associated to already parsed fragments, so a path fragment | |
| // cannot be used in this position. Doing the retokenization results in valid rust | |
| // code. | |
| $crate::macros::paste!( | |
| ::core::ptr::write($slot, $t { | |
| $($acc)* | |
| ..zeroed | |
| }); | |
| ); | |
| } | |
| }; | |
| (make_initializer: | |
| @slot($slot:ident), | |
| @type_name($t:path), | |
| @munch_fields($(,)?), | |
| @acc($($acc:tt)*), | |
| ) => { | |
| // Endpoint, nothing more to munch, create the initializer. | |
| // Since we are in the closure that is never called, this will never get executed. | |
| // We abuse `slot` to get the correct type inference here: | |
| // | |
| // SAFETY: TODO. | |
| unsafe { | |
| // Here we abuse `paste!` to retokenize `$t`. Declarative macros have some internal | |
| // information that is associated to already parsed fragments, so a path fragment | |
| // cannot be used in this position. Doing the retokenization results in valid rust | |
| // code. | |
| $crate::macros::paste!( | |
| ::core::ptr::write($slot, $t { | |
| $($acc)* | |
| }); | |
| ); | |
| } | |
| }; | |
| (make_initializer: | |
| @slot($slot:ident), | |
| @type_name($t:path), | |
| @munch_fields($field:ident <- $val:expr, $($rest:tt)*), | |
| @acc($($acc:tt)*), | |
| ) => { | |
| $crate::__init_internal!(make_initializer: | |
| @slot($slot), | |
| @type_name($t), | |
| @munch_fields($($rest)*), | |
| @acc($($acc)* $field: ::core::panic!(),), | |
| ); | |
| }; | |
| (make_initializer: | |
| @slot($slot:ident), | |
| @type_name($t:path), | |
| @munch_fields($field:ident $(: $val:expr)?, $($rest:tt)*), | |
| @acc($($acc:tt)*), | |
| ) => { | |
| $crate::__init_internal!(make_initializer: | |
| @slot($slot), | |
| @type_name($t), | |
| @munch_fields($($rest)*), | |
| @acc($($acc)* $field: ::core::panic!(),), | |
| ); | |
| }; | |
| } | |
| #[doc(hidden)] | |
| #[macro_export] | |
| macro_rules! __derive_zeroable { | |
| (parse_input: | |
| @sig( | |
| $(#[$($struct_attr:tt)*])* | |
| $vis:vis struct $name:ident | |
| $(where $($whr:tt)*)? | |
| ), | |
| @impl_generics($($impl_generics:tt)*), | |
| @ty_generics($($ty_generics:tt)*), | |
| @body({ | |
| $( | |
| $(#[$($field_attr:tt)*])* | |
| $field_vis:vis $field:ident : $field_ty:ty | |
| ),* $(,)? | |
| }), | |
| ) => { | |
| // SAFETY: Every field type implements `Zeroable` and padding bytes may be zero. | |
| #[automatically_derived] | |
| unsafe impl<$($impl_generics)*> $crate::Zeroable for $name<$($ty_generics)*> | |
| where | |
| $($($whr)*)? | |
| {} | |
| const _: () = { | |
| fn assert_zeroable<T: ?::core::marker::Sized + $crate::Zeroable>() {} | |
| fn ensure_zeroable<$($impl_generics)*>() | |
| where $($($whr)*)? | |
| { | |
| $(assert_zeroable::<$field_ty>();)* | |
| } | |
| }; | |
| }; | |
| (parse_input: | |
| @sig( | |
| $(#[$($struct_attr:tt)*])* | |
| $vis:vis union $name:ident | |
| $(where $($whr:tt)*)? | |
| ), | |
| @impl_generics($($impl_generics:tt)*), | |
| @ty_generics($($ty_generics:tt)*), | |
| @body({ | |
| $( | |
| $(#[$($field_attr:tt)*])* | |
| $field_vis:vis $field:ident : $field_ty:ty | |
| ),* $(,)? | |
| }), | |
| ) => { | |
| // SAFETY: Every field type implements `Zeroable` and padding bytes may be zero. | |
| #[automatically_derived] | |
| unsafe impl<$($impl_generics)*> $crate::Zeroable for $name<$($ty_generics)*> | |
| where | |
| $($($whr)*)? | |
| {} | |
| const _: () = { | |
| fn assert_zeroable<T: ?::core::marker::Sized + $crate::Zeroable>() {} | |
| fn ensure_zeroable<$($impl_generics)*>() | |
| where $($($whr)*)? | |
| { | |
| $(assert_zeroable::<$field_ty>();)* | |
| } | |
| }; | |
| }; | |
| } | |
| #[doc(hidden)] | |
| #[macro_export] | |
| macro_rules! __maybe_derive_zeroable { | |
| (parse_input: | |
| @sig( | |
| $(#[$($struct_attr:tt)*])* | |
| $vis:vis struct $name:ident | |
| $(where $($whr:tt)*)? | |
| ), | |
| @impl_generics($($impl_generics:tt)*), | |
| @ty_generics($($ty_generics:tt)*), | |
| @body({ | |
| $( | |
| $(#[$($field_attr:tt)*])* | |
| $field_vis:vis $field:ident : $field_ty:ty | |
| ),* $(,)? | |
| }), | |
| ) => { | |
| // SAFETY: Every field type implements `Zeroable` and padding bytes may be zero. | |
| #[automatically_derived] | |
| unsafe impl<$($impl_generics)*> $crate::Zeroable for $name<$($ty_generics)*> | |
| where | |
| $( | |
| // the `for<'__dummy>` HRTB makes this not error without the `trivial_bounds` | |
| // feature <https://github.com/rust-lang/rust/issues/48214#issuecomment-2557829956>. | |
| $field_ty: for<'__dummy> $crate::Zeroable, | |
| )* | |
| $($($whr)*)? | |
| {} | |
| }; | |
| (parse_input: | |
| @sig( | |
| $(#[$($struct_attr:tt)*])* | |
| $vis:vis union $name:ident | |
| $(where $($whr:tt)*)? | |
| ), | |
| @impl_generics($($impl_generics:tt)*), | |
| @ty_generics($($ty_generics:tt)*), | |
| @body({ | |
| $( | |
| $(#[$($field_attr:tt)*])* | |
| $field_vis:vis $field:ident : $field_ty:ty | |
| ),* $(,)? | |
| }), | |
| ) => { | |
| // SAFETY: Every field type implements `Zeroable` and padding bytes may be zero. | |
| #[automatically_derived] | |
| unsafe impl<$($impl_generics)*> $crate::Zeroable for $name<$($ty_generics)*> | |
| where | |
| $( | |
| // the `for<'__dummy>` HRTB makes this not error without the `trivial_bounds` | |
| // feature <https://github.com/rust-lang/rust/issues/48214#issuecomment-2557829956>. | |
| $field_ty: for<'__dummy> $crate::Zeroable, | |
| )* | |
| $($($whr)*)? | |
| {} | |
| }; | |
| } |