1 // SPDX-License-Identifier: Apache-2.0 OR MIT
3 //! This module provides the macros that actually implement the proc-macros `pin_data` and
6 //! These macros should never be called directly, since they expect their input to be
7 //! in a certain format which is internal. Use the proc-macros instead.
9 //! This architecture has been chosen because the kernel does not yet have access to `syn` which
10 //! would make matters a lot easier for implementing these as proc-macros.
12 //! # Macro expansion example
14 //! This section is intended for readers trying to understand the macros in this module and the
15 //! `pin_init!` macros from `init.rs`.
17 //! We will look at the following example:
20 //! # use kernel::init::*;
21 //! # use core::pin::Pin;
31 //! fn new(t: T) -> impl PinInit<Self> {
32 //! pin_init!(Self { t, x: 0 })
36 //! #[pin_data(PinnedDrop)]
44 //! impl PinnedDrop for Foo {
45 //! fn drop(self: Pin<&mut Self>) {
46 //! println!("{self:p} is getting dropped.");
51 //! let initializer = pin_init!(Foo {
53 //! b <- Bar::new(36),
57 //! This example includes the most common and important features of the pin-init API.
59 //! Below you can find individual section about the different macro invocations. Here are some
60 //! general things we need to take into account when designing macros:
61 //! - use global paths, similarly to file paths, these start with the separator: `::core::panic!()`
62 //! this ensures that the correct item is used, since users could define their own `mod core {}`
63 //! and then their own `panic!` inside to execute arbitrary code inside of our macro.
64 //! - macro `unsafe` hygiene: we need to ensure that we do not expand arbitrary, user-supplied
65 //! expressions inside of an `unsafe` block in the macro, because this would allow users to do
66 //! `unsafe` operations without an associated `unsafe` block.
68 //! ## `#[pin_data]` on `Bar`
70 //! This macro is used to specify which fields are structurally pinned and which fields are not. It
71 //! is placed on the struct definition and allows `#[pin]` to be placed on the fields.
73 //! Here is the definition of `Bar` from our example:
76 //! # use kernel::init::*;
86 //! This expands to the following code:
89 //! // Firstly the normal definition of the struct, attributes are preserved:
95 //! // Then an anonymous constant is defined, this is because we do not want any code to access the
96 //! // types that we define inside:
98 //! // We define the pin-data carrying struct, it is a ZST and needs to have the same generics,
99 //! // since we need to implement access functions for each field and thus need to know its
101 //! struct __ThePinData<T> {
102 //! __phantom: ::core::marker::PhantomData<fn(Bar<T>) -> Bar<T>>,
104 //! // We implement `Copy` for the pin-data struct, since all functions it defines will take
105 //! // `self` by value.
106 //! impl<T> ::core::clone::Clone for __ThePinData<T> {
107 //! fn clone(&self) -> Self {
111 //! impl<T> ::core::marker::Copy for __ThePinData<T> {}
112 //! // For every field of `Bar`, the pin-data struct will define a function with the same name
113 //! // and accessor (`pub` or `pub(crate)` etc.). This function will take a pointer to the
114 //! // field (`slot`) and a `PinInit` or `Init` depending on the projection kind of the field
115 //! // (if pinning is structural for the field, then `PinInit` otherwise `Init`).
116 //! #[allow(dead_code)]
117 //! impl<T> __ThePinData<T> {
121 //! // Since `t` is `#[pin]`, this is `PinInit`.
122 //! init: impl ::kernel::init::PinInit<T, E>,
123 //! ) -> ::core::result::Result<(), E> {
124 //! unsafe { ::kernel::init::PinInit::__pinned_init(init, slot) }
126 //! pub unsafe fn x<E>(
128 //! slot: *mut usize,
129 //! // Since `x` is not `#[pin]`, this is `Init`.
130 //! init: impl ::kernel::init::Init<usize, E>,
131 //! ) -> ::core::result::Result<(), E> {
132 //! unsafe { ::kernel::init::Init::__init(init, slot) }
135 //! // Implement the internal `HasPinData` trait that associates `Bar` with the pin-data struct
136 //! // that we constructed above.
137 //! unsafe impl<T> ::kernel::init::__internal::HasPinData for Bar<T> {
138 //! type PinData = __ThePinData<T>;
139 //! unsafe fn __pin_data() -> Self::PinData {
141 //! __phantom: ::core::marker::PhantomData,
145 //! // Implement the internal `PinData` trait that marks the pin-data struct as a pin-data
146 //! // struct. This is important to ensure that no user can implement a rouge `__pin_data`
147 //! // function without using `unsafe`.
148 //! unsafe impl<T> ::kernel::init::__internal::PinData for __ThePinData<T> {
149 //! type Datee = Bar<T>;
151 //! // Now we only want to implement `Unpin` for `Bar` when every structurally pinned field is
152 //! // `Unpin`. In other words, whether `Bar` is `Unpin` only depends on structurally pinned
153 //! // fields (those marked with `#[pin]`). These fields will be listed in this struct, in our
154 //! // case no such fields exist, hence this is almost empty. The two phantomdata fields exist
155 //! // for two reasons:
156 //! // - `__phantom`: every generic must be used, since we cannot really know which generics
157 //! // are used, we declere all and then use everything here once.
158 //! // - `__phantom_pin`: uses the `'__pin` lifetime and ensures that this struct is invariant
159 //! // over it. The lifetime is needed to work around the limitation that trait bounds must
160 //! // not be trivial, e.g. the user has a `#[pin] PhantomPinned` field -- this is
161 //! // unconditionally `!Unpin` and results in an error. The lifetime tricks the compiler
162 //! // into accepting these bounds regardless.
163 //! #[allow(dead_code)]
164 //! struct __Unpin<'__pin, T> {
165 //! __phantom_pin: ::core::marker::PhantomData<fn(&'__pin ()) -> &'__pin ()>,
166 //! __phantom: ::core::marker::PhantomData<fn(Bar<T>) -> Bar<T>>,
167 //! // Our only `#[pin]` field is `t`.
172 //! ::core::marker::Unpin for Bar<T> where __Unpin<'__pin, T>: ::core::marker::Unpin {}
173 //! // Now we need to ensure that `Bar` does not implement `Drop`, since that would give users
174 //! // access to `&mut self` inside of `drop` even if the struct was pinned. This could lead to
175 //! // UB with only safe code, so we disallow this by giving a trait implementation error using
176 //! // a direct impl and a blanket implementation.
177 //! trait MustNotImplDrop {}
178 //! // Normally `Drop` bounds do not have the correct semantics, but for this purpose they do
179 //! // (normally people want to know if a type has any kind of drop glue at all, here we want
180 //! // to know if it has any kind of custom drop glue, which is exactly what this bound does).
181 //! #[allow(drop_bounds)]
182 //! impl<T: ::core::ops::Drop> MustNotImplDrop for T {}
183 //! impl<T> MustNotImplDrop for Bar<T> {}
184 //! // Here comes a convenience check, if one implemented `PinnedDrop`, but forgot to add it to
185 //! // `#[pin_data]`, then this will error with the same mechanic as above, this is not needed
186 //! // for safety, but a good sanity check, since no normal code calls `PinnedDrop::drop`.
187 //! #[allow(non_camel_case_types)]
188 //! trait UselessPinnedDropImpl_you_need_to_specify_PinnedDrop {}
189 //! impl<T: ::kernel::init::PinnedDrop>
190 //! UselessPinnedDropImpl_you_need_to_specify_PinnedDrop for T {}
191 //! impl<T> UselessPinnedDropImpl_you_need_to_specify_PinnedDrop for Bar<T> {}
195 //! ## `pin_init!` in `impl Bar`
197 //! This macro creates an pin-initializer for the given struct. It requires that the struct is
198 //! annotated by `#[pin_data]`.
200 //! Here is the impl on `Bar` defining the new function:
204 //! fn new(t: T) -> impl PinInit<Self> {
205 //! pin_init!(Self { t, x: 0 })
210 //! This expands to the following code:
214 //! fn new(t: T) -> impl PinInit<Self> {
216 //! // We do not want to allow arbitrary returns, so we declare this type as the `Ok`
217 //! // return type and shadow it later when we insert the arbitrary user code. That way
218 //! // there will be no possibility of returning without `unsafe`.
220 //! // Get the pin-data type from the initialized type.
221 //! // - the function is unsafe, hence the unsafe block
222 //! // - we `use` the `HasPinData` trait in the block, it is only available in that
224 //! let data = unsafe {
225 //! use ::kernel::init::__internal::HasPinData;
226 //! Self::__pin_data()
228 //! // Use `data` to help with type inference, the closure supplied will have the type
229 //! // `FnOnce(*mut Self) -> Result<__InitOk, Infallible>`.
230 //! let init = ::kernel::init::__internal::PinData::make_closure::<
233 //! ::core::convert::Infallible,
234 //! >(data, move |slot| {
236 //! // Shadow the structure so it cannot be used to return early. If a user
237 //! // tries to write `return Ok(__InitOk)`, then they get a type error, since
238 //! // that will refer to this struct instead of the one defined above.
240 //! // This is the expansion of `t,`, which is syntactic sugar for `t: t,`.
241 //! unsafe { ::core::ptr::write(::core::addr_of_mut!((*slot).t), t) };
242 //! // Since initialization could fail later (not in this case, since the error
243 //! // type is `Infallible`) we will need to drop this field if there is an
244 //! // error later. This `DropGuard` will drop the field when it gets dropped
245 //! // and has not yet been forgotten. We make a reference to it, so users
246 //! // cannot `mem::forget` it from the initializer, since the name is the same
247 //! // as the field (including hygiene).
248 //! let t = &unsafe {
249 //! ::kernel::init::__internal::DropGuard::new(
250 //! ::core::addr_of_mut!((*slot).t),
253 //! // Expansion of `x: 0,`:
254 //! // Since this can be an arbitrary expression we cannot place it inside of
255 //! // the `unsafe` block, so we bind it here.
257 //! unsafe { ::core::ptr::write(::core::addr_of_mut!((*slot).x), x) };
258 //! // We again create a `DropGuard`.
259 //! let x = &unsafe {
260 //! ::kernel::init::__internal::DropGuard::new(
261 //! ::core::addr_of_mut!((*slot).x),
265 //! // Here we use the type checker to ensure that every field has been
266 //! // initialized exactly once, since this is `if false` it will never get
267 //! // executed, but still type-checked.
268 //! // Additionally we abuse `slot` to automatically infer the correct type for
269 //! // the struct. This is also another check that every field is accessible
270 //! // from this scope.
271 //! #[allow(unreachable_code, clippy::diverging_sub_expression)]
274 //! ::core::ptr::write(
277 //! // We only care about typecheck finding every field here,
278 //! // the expression does not matter, just conjure one using
280 //! t: ::core::panic!(),
281 //! x: ::core::panic!(),
286 //! // Since initialization has successfully completed, we can now forget the
287 //! // guards. This is not `mem::forget`, since we only have `&DropGuard`.
288 //! unsafe { ::kernel::init::__internal::DropGuard::forget(t) };
289 //! unsafe { ::kernel::init::__internal::DropGuard::forget(x) };
291 //! // We leave the scope above and gain access to the previously shadowed
292 //! // `__InitOk` that we need to return.
295 //! // Change the return type from `__InitOk` to `()`.
296 //! let init = move |slot| -> ::core::result::Result<(), ::core::convert::Infallible> {
297 //! init(slot).map(|__InitOk| ())
299 //! // Construct the initializer.
300 //! let init = unsafe {
301 //! ::kernel::init::pin_init_from_closure::<_, ::core::convert::Infallible>(init)
309 //! ## `#[pin_data]` on `Foo`
311 //! Since we already took a look at `#[pin_data]` on `Bar`, this section will only explain the
312 //! differences/new things in the expansion of the `Foo` definition:
315 //! #[pin_data(PinnedDrop)]
323 //! This expands to the following code:
331 //! struct __ThePinData {
332 //! __phantom: ::core::marker::PhantomData<fn(Foo) -> Foo>,
334 //! impl ::core::clone::Clone for __ThePinData {
335 //! fn clone(&self) -> Self {
339 //! impl ::core::marker::Copy for __ThePinData {}
340 //! #[allow(dead_code)]
341 //! impl __ThePinData {
344 //! slot: *mut Bar<u32>,
345 //! init: impl ::kernel::init::PinInit<Bar<u32>, E>,
346 //! ) -> ::core::result::Result<(), E> {
347 //! unsafe { ::kernel::init::PinInit::__pinned_init(init, slot) }
351 //! slot: *mut usize,
352 //! init: impl ::kernel::init::Init<usize, E>,
353 //! ) -> ::core::result::Result<(), E> {
354 //! unsafe { ::kernel::init::Init::__init(init, slot) }
357 //! unsafe impl ::kernel::init::__internal::HasPinData for Foo {
358 //! type PinData = __ThePinData;
359 //! unsafe fn __pin_data() -> Self::PinData {
361 //! __phantom: ::core::marker::PhantomData,
365 //! unsafe impl ::kernel::init::__internal::PinData for __ThePinData {
366 //! type Datee = Foo;
368 //! #[allow(dead_code)]
369 //! struct __Unpin<'__pin> {
370 //! __phantom_pin: ::core::marker::PhantomData<fn(&'__pin ()) -> &'__pin ()>,
371 //! __phantom: ::core::marker::PhantomData<fn(Foo) -> Foo>,
375 //! impl<'__pin> ::core::marker::Unpin for Foo where __Unpin<'__pin>: ::core::marker::Unpin {}
376 //! // Since we specified `PinnedDrop` as the argument to `#[pin_data]`, we expect `Foo` to
377 //! // implement `PinnedDrop`. Thus we do not need to prevent `Drop` implementations like
378 //! // before, instead we implement `Drop` here and delegate to `PinnedDrop`.
379 //! impl ::core::ops::Drop for Foo {
380 //! fn drop(&mut self) {
381 //! // Since we are getting dropped, no one else has a reference to `self` and thus we
382 //! // can assume that we never move.
383 //! let pinned = unsafe { ::core::pin::Pin::new_unchecked(self) };
384 //! // Create the unsafe token that proves that we are inside of a destructor, this
385 //! // type is only allowed to be created in a destructor.
386 //! let token = unsafe { ::kernel::init::__internal::OnlyCallFromDrop::new() };
387 //! ::kernel::init::PinnedDrop::drop(pinned, token);
393 //! ## `#[pinned_drop]` on `impl PinnedDrop for Foo`
395 //! This macro is used to implement the `PinnedDrop` trait, since that trait is `unsafe` and has an
396 //! extra parameter that should not be used at all. The macro hides that parameter.
398 //! Here is the `PinnedDrop` impl for `Foo`:
402 //! impl PinnedDrop for Foo {
403 //! fn drop(self: Pin<&mut Self>) {
404 //! println!("{self:p} is getting dropped.");
409 //! This expands to the following code:
412 //! // `unsafe`, full path and the token parameter are added, everything else stays the same.
413 //! unsafe impl ::kernel::init::PinnedDrop for Foo {
414 //! fn drop(self: Pin<&mut Self>, _: ::kernel::init::__internal::OnlyCallFromDrop) {
415 //! println!("{self:p} is getting dropped.");
420 //! ## `pin_init!` on `Foo`
422 //! Since we already took a look at `pin_init!` on `Bar`, this section will only show the expansion
423 //! of `pin_init!` on `Foo`:
427 //! let initializer = pin_init!(Foo {
429 //! b <- Bar::new(36),
433 //! This expands to the following code:
437 //! let initializer = {
439 //! let data = unsafe {
440 //! use ::kernel::init::__internal::HasPinData;
441 //! Foo::__pin_data()
443 //! let init = ::kernel::init::__internal::PinData::make_closure::<
446 //! ::core::convert::Infallible,
447 //! >(data, move |slot| {
450 //! unsafe { ::core::ptr::write(::core::addr_of_mut!((*slot).a), a) };
451 //! let a = &unsafe {
452 //! ::kernel::init::__internal::DropGuard::new(::core::addr_of_mut!((*slot).a))
454 //! let b = Bar::new(36);
455 //! unsafe { data.b(::core::addr_of_mut!((*slot).b), b)? };
456 //! let b = &unsafe {
457 //! ::kernel::init::__internal::DropGuard::new(::core::addr_of_mut!((*slot).b))
460 //! #[allow(unreachable_code, clippy::diverging_sub_expression)]
463 //! ::core::ptr::write(
466 //! a: ::core::panic!(),
467 //! b: ::core::panic!(),
472 //! unsafe { ::kernel::init::__internal::DropGuard::forget(a) };
473 //! unsafe { ::kernel::init::__internal::DropGuard::forget(b) };
477 //! let init = move |slot| -> ::core::result::Result<(), ::core::convert::Infallible> {
478 //! init(slot).map(|__InitOk| ())
480 //! let init = unsafe {
481 //! ::kernel::init::pin_init_from_closure::<_, ::core::convert::Infallible>(init)
487 /// Creates a `unsafe impl<...> PinnedDrop for $type` block.
489 /// See [`PinnedDrop`] for more information.
492 macro_rules! __pinned_drop {
494 @impl_sig($($impl_sig:tt)*),
497 fn drop($($sig:tt)*) {
502 unsafe $($impl_sig)* {
503 // Inherit all attributes and the type/ident tokens for the signature.
505 fn drop($($sig)*, _: $crate::init::__internal::OnlyCallFromDrop) {
512 /// This macro first parses the struct definition such that it separates pinned and not pinned
513 /// fields. Afterwards it declares the struct and implement the `PinData` trait safely.
516 macro_rules! __pin_data {
517 // Proc-macro entry point, this is supplied by the proc-macro pre-parsing.
519 @args($($pinned_drop:ident)?),
521 $(#[$($struct_attr:tt)*])*
522 $vis:vis struct $name:ident
523 $(where $($whr:tt)*)?
525 @impl_generics($($impl_generics:tt)*),
526 @ty_generics($($ty_generics:tt)*),
527 @body({ $($fields:tt)* }),
529 // We now use token munching to iterate through all of the fields. While doing this we
530 // identify fields marked with `#[pin]`, these fields are the 'pinned fields'. The user
531 // wants these to be structurally pinned. The rest of the fields are the
532 // 'not pinned fields'. Additionally we collect all fields, since we need them in the right
533 // order to declare the struct.
535 // In this call we also put some explaining comments for the parameters.
536 $crate::__pin_data!(find_pinned_fields:
537 // Attributes on the struct itself, these will just be propagated to be put onto the
538 // struct definition.
539 @struct_attrs($(#[$($struct_attr)*])*),
540 // The visibility of the struct.
542 // The name of the struct.
544 // The 'impl generics', the generics that will need to be specified on the struct inside
545 // of an `impl<$ty_generics>` block.
546 @impl_generics($($impl_generics)*),
547 // The 'ty generics', the generics that will need to be specified on the impl blocks.
548 @ty_generics($($ty_generics)*),
549 // The where clause of any impl block and the declaration.
550 @where($($($whr)*)?),
551 // The remaining fields tokens that need to be processed.
552 // We add a `,` at the end to ensure correct parsing.
553 @fields_munch($($fields)* ,),
554 // The pinned fields.
556 // The not pinned fields.
560 // The accumulator containing all attributes already parsed.
562 // Contains `yes` or `` to indicate if `#[pin]` was found on the current field.
564 // The proc-macro argument, this should be `PinnedDrop` or ``.
565 @pinned_drop($($pinned_drop)?),
569 @struct_attrs($($struct_attrs:tt)*),
572 @impl_generics($($impl_generics:tt)*),
573 @ty_generics($($ty_generics:tt)*),
575 // We found a PhantomPinned field, this should generally be pinned!
576 @fields_munch($field:ident : $($($(::)?core::)?marker::)?PhantomPinned, $($rest:tt)*),
577 @pinned($($pinned:tt)*),
578 @not_pinned($($not_pinned:tt)*),
579 @fields($($fields:tt)*),
580 @accum($($accum:tt)*),
581 // This field is not pinned.
583 @pinned_drop($($pinned_drop:ident)?),
585 ::core::compile_error!(concat!(
588 "` of type `PhantomPinned` only has an effect, if it has the `#[pin]` attribute.",
590 $crate::__pin_data!(find_pinned_fields:
591 @struct_attrs($($struct_attrs)*),
594 @impl_generics($($impl_generics)*),
595 @ty_generics($($ty_generics)*),
597 @fields_munch($($rest)*),
598 @pinned($($pinned)* $($accum)* $field: ::core::marker::PhantomPinned,),
599 @not_pinned($($not_pinned)*),
600 @fields($($fields)* $($accum)* $field: ::core::marker::PhantomPinned,),
603 @pinned_drop($($pinned_drop)?),
607 @struct_attrs($($struct_attrs:tt)*),
610 @impl_generics($($impl_generics:tt)*),
611 @ty_generics($($ty_generics:tt)*),
613 // We reached the field declaration.
614 @fields_munch($field:ident : $type:ty, $($rest:tt)*),
615 @pinned($($pinned:tt)*),
616 @not_pinned($($not_pinned:tt)*),
617 @fields($($fields:tt)*),
618 @accum($($accum:tt)*),
619 // This field is pinned.
621 @pinned_drop($($pinned_drop:ident)?),
623 $crate::__pin_data!(find_pinned_fields:
624 @struct_attrs($($struct_attrs)*),
627 @impl_generics($($impl_generics)*),
628 @ty_generics($($ty_generics)*),
630 @fields_munch($($rest)*),
631 @pinned($($pinned)* $($accum)* $field: $type,),
632 @not_pinned($($not_pinned)*),
633 @fields($($fields)* $($accum)* $field: $type,),
636 @pinned_drop($($pinned_drop)?),
640 @struct_attrs($($struct_attrs:tt)*),
643 @impl_generics($($impl_generics:tt)*),
644 @ty_generics($($ty_generics:tt)*),
646 // We reached the field declaration.
647 @fields_munch($field:ident : $type:ty, $($rest:tt)*),
648 @pinned($($pinned:tt)*),
649 @not_pinned($($not_pinned:tt)*),
650 @fields($($fields:tt)*),
651 @accum($($accum:tt)*),
652 // This field is not pinned.
654 @pinned_drop($($pinned_drop:ident)?),
656 $crate::__pin_data!(find_pinned_fields:
657 @struct_attrs($($struct_attrs)*),
660 @impl_generics($($impl_generics)*),
661 @ty_generics($($ty_generics)*),
663 @fields_munch($($rest)*),
664 @pinned($($pinned)*),
665 @not_pinned($($not_pinned)* $($accum)* $field: $type,),
666 @fields($($fields)* $($accum)* $field: $type,),
669 @pinned_drop($($pinned_drop)?),
673 @struct_attrs($($struct_attrs:tt)*),
676 @impl_generics($($impl_generics:tt)*),
677 @ty_generics($($ty_generics:tt)*),
679 // We found the `#[pin]` attr.
680 @fields_munch(#[pin] $($rest:tt)*),
681 @pinned($($pinned:tt)*),
682 @not_pinned($($not_pinned:tt)*),
683 @fields($($fields:tt)*),
684 @accum($($accum:tt)*),
685 @is_pinned($($is_pinned:ident)?),
686 @pinned_drop($($pinned_drop:ident)?),
688 $crate::__pin_data!(find_pinned_fields:
689 @struct_attrs($($struct_attrs)*),
692 @impl_generics($($impl_generics)*),
693 @ty_generics($($ty_generics)*),
695 @fields_munch($($rest)*),
696 // We do not include `#[pin]` in the list of attributes, since it is not actually an
697 // attribute that is defined somewhere.
698 @pinned($($pinned)*),
699 @not_pinned($($not_pinned)*),
700 @fields($($fields)*),
702 // Set this to `yes`.
704 @pinned_drop($($pinned_drop)?),
708 @struct_attrs($($struct_attrs:tt)*),
711 @impl_generics($($impl_generics:tt)*),
712 @ty_generics($($ty_generics:tt)*),
714 // We reached the field declaration with visibility, for simplicity we only munch the
715 // visibility and put it into `$accum`.
716 @fields_munch($fvis:vis $field:ident $($rest:tt)*),
717 @pinned($($pinned:tt)*),
718 @not_pinned($($not_pinned:tt)*),
719 @fields($($fields:tt)*),
720 @accum($($accum:tt)*),
721 @is_pinned($($is_pinned:ident)?),
722 @pinned_drop($($pinned_drop:ident)?),
724 $crate::__pin_data!(find_pinned_fields:
725 @struct_attrs($($struct_attrs)*),
728 @impl_generics($($impl_generics)*),
729 @ty_generics($($ty_generics)*),
731 @fields_munch($field $($rest)*),
732 @pinned($($pinned)*),
733 @not_pinned($($not_pinned)*),
734 @fields($($fields)*),
735 @accum($($accum)* $fvis),
736 @is_pinned($($is_pinned)?),
737 @pinned_drop($($pinned_drop)?),
741 @struct_attrs($($struct_attrs:tt)*),
744 @impl_generics($($impl_generics:tt)*),
745 @ty_generics($($ty_generics:tt)*),
747 // Some other attribute, just put it into `$accum`.
748 @fields_munch(#[$($attr:tt)*] $($rest:tt)*),
749 @pinned($($pinned:tt)*),
750 @not_pinned($($not_pinned:tt)*),
751 @fields($($fields:tt)*),
752 @accum($($accum:tt)*),
753 @is_pinned($($is_pinned:ident)?),
754 @pinned_drop($($pinned_drop:ident)?),
756 $crate::__pin_data!(find_pinned_fields:
757 @struct_attrs($($struct_attrs)*),
760 @impl_generics($($impl_generics)*),
761 @ty_generics($($ty_generics)*),
763 @fields_munch($($rest)*),
764 @pinned($($pinned)*),
765 @not_pinned($($not_pinned)*),
766 @fields($($fields)*),
767 @accum($($accum)* #[$($attr)*]),
768 @is_pinned($($is_pinned)?),
769 @pinned_drop($($pinned_drop)?),
773 @struct_attrs($($struct_attrs:tt)*),
776 @impl_generics($($impl_generics:tt)*),
777 @ty_generics($($ty_generics:tt)*),
779 // We reached the end of the fields, plus an optional additional comma, since we added one
780 // before and the user is also allowed to put a trailing comma.
781 @fields_munch($(,)?),
782 @pinned($($pinned:tt)*),
783 @not_pinned($($not_pinned:tt)*),
784 @fields($($fields:tt)*),
787 @pinned_drop($($pinned_drop:ident)?),
789 // Declare the struct with all fields in the correct order.
791 $vis struct $name <$($impl_generics)*>
797 // We put the rest into this const item, because it then will not be accessible to anything
800 // We declare this struct which will host all of the projection function for our type.
801 // it will be invariant over all generic parameters which are inherited from the
803 $vis struct __ThePinData<$($impl_generics)*>
806 __phantom: ::core::marker::PhantomData<
807 fn($name<$($ty_generics)*>) -> $name<$($ty_generics)*>
811 impl<$($impl_generics)*> ::core::clone::Clone for __ThePinData<$($ty_generics)*>
814 fn clone(&self) -> Self { *self }
817 impl<$($impl_generics)*> ::core::marker::Copy for __ThePinData<$($ty_generics)*>
821 // Make all projection functions.
822 $crate::__pin_data!(make_pin_data:
823 @pin_data(__ThePinData),
824 @impl_generics($($impl_generics)*),
825 @ty_generics($($ty_generics)*),
827 @pinned($($pinned)*),
828 @not_pinned($($not_pinned)*),
831 // SAFETY: We have added the correct projection functions above to `__ThePinData` and
832 // we also use the least restrictive generics possible.
833 unsafe impl<$($impl_generics)*>
834 $crate::init::__internal::HasPinData for $name<$($ty_generics)*>
837 type PinData = __ThePinData<$($ty_generics)*>;
839 unsafe fn __pin_data() -> Self::PinData {
840 __ThePinData { __phantom: ::core::marker::PhantomData }
844 unsafe impl<$($impl_generics)*>
845 $crate::init::__internal::PinData for __ThePinData<$($ty_generics)*>
848 type Datee = $name<$($ty_generics)*>;
851 // This struct will be used for the unpin analysis. Since only structurally pinned
852 // fields are relevant whether the struct should implement `Unpin`.
854 struct __Unpin <'__pin, $($impl_generics)*>
857 __phantom_pin: ::core::marker::PhantomData<fn(&'__pin ()) -> &'__pin ()>,
858 __phantom: ::core::marker::PhantomData<
859 fn($name<$($ty_generics)*>) -> $name<$($ty_generics)*>
861 // Only the pinned fields.
866 impl<'__pin, $($impl_generics)*> ::core::marker::Unpin for $name<$($ty_generics)*>
868 __Unpin<'__pin, $($ty_generics)*>: ::core::marker::Unpin,
872 // We need to disallow normal `Drop` implementation, the exact behavior depends on
873 // whether `PinnedDrop` was specified as the parameter.
874 $crate::__pin_data!(drop_prevention:
876 @impl_generics($($impl_generics)*),
877 @ty_generics($($ty_generics)*),
879 @pinned_drop($($pinned_drop)?),
883 // When no `PinnedDrop` was specified, then we have to prevent implementing drop.
886 @impl_generics($($impl_generics:tt)*),
887 @ty_generics($($ty_generics:tt)*),
891 // We prevent this by creating a trait that will be implemented for all types implementing
892 // `Drop`. Additionally we will implement this trait for the struct leading to a conflict,
893 // if it also implements `Drop`
894 trait MustNotImplDrop {}
895 #[allow(drop_bounds)]
896 impl<T: ::core::ops::Drop> MustNotImplDrop for T {}
897 impl<$($impl_generics)*> MustNotImplDrop for $name<$($ty_generics)*>
899 // We also take care to prevent users from writing a useless `PinnedDrop` implementation.
900 // They might implement `PinnedDrop` correctly for the struct, but forget to give
901 // `PinnedDrop` as the parameter to `#[pin_data]`.
902 #[allow(non_camel_case_types)]
903 trait UselessPinnedDropImpl_you_need_to_specify_PinnedDrop {}
904 impl<T: $crate::init::PinnedDrop>
905 UselessPinnedDropImpl_you_need_to_specify_PinnedDrop for T {}
906 impl<$($impl_generics)*>
907 UselessPinnedDropImpl_you_need_to_specify_PinnedDrop for $name<$($ty_generics)*>
910 // When `PinnedDrop` was specified we just implement `Drop` and delegate.
913 @impl_generics($($impl_generics:tt)*),
914 @ty_generics($($ty_generics:tt)*),
916 @pinned_drop(PinnedDrop),
918 impl<$($impl_generics)*> ::core::ops::Drop for $name<$($ty_generics)*>
922 // SAFETY: Since this is a destructor, `self` will not move after this function
923 // terminates, since it is inaccessible.
924 let pinned = unsafe { ::core::pin::Pin::new_unchecked(self) };
925 // SAFETY: Since this is a drop function, we can create this token to call the
926 // pinned destructor of this type.
927 let token = unsafe { $crate::init::__internal::OnlyCallFromDrop::new() };
928 $crate::init::PinnedDrop::drop(pinned, token);
932 // If some other parameter was specified, we emit a readable error.
935 @impl_generics($($impl_generics:tt)*),
936 @ty_generics($($ty_generics:tt)*),
938 @pinned_drop($($rest:tt)*),
941 "Wrong parameters to `#[pin_data]`, expected nothing or `PinnedDrop`, got '{}'.",
942 stringify!($($rest)*),
946 @pin_data($pin_data:ident),
947 @impl_generics($($impl_generics:tt)*),
948 @ty_generics($($ty_generics:tt)*),
950 @pinned($($(#[$($p_attr:tt)*])* $pvis:vis $p_field:ident : $p_type:ty),* $(,)?),
951 @not_pinned($($(#[$($attr:tt)*])* $fvis:vis $field:ident : $type:ty),* $(,)?),
953 // For every field, we create a projection function according to its projection type. If a
954 // field is structurally pinned, then it must be initialized via `PinInit`, if it is not
955 // structurally pinned, then it can be initialized via `Init`.
957 // The functions are `unsafe` to prevent accidentally calling them.
959 impl<$($impl_generics)*> $pin_data<$($ty_generics)*>
963 $pvis unsafe fn $p_field<E>(
966 init: impl $crate::init::PinInit<$p_type, E>,
967 ) -> ::core::result::Result<(), E> {
968 unsafe { $crate::init::PinInit::__pinned_init(init, slot) }
972 $fvis unsafe fn $field<E>(
975 init: impl $crate::init::Init<$type, E>,
976 ) -> ::core::result::Result<(), E> {
977 unsafe { $crate::init::Init::__init(init, slot) }