rust/kernel/init/macros.rs

   1 // SPDX-License-Identifier: Apache-2.0 OR MIT
   2
   3 //! This module provides the macros that actually implement the proc-macros `pin_data` and
   4 //! `pinned_drop`.
   5 //!
   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.
   8 //!
   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.
  11 //!
  12 //! # Macro expansion example
  13 //!
  14 //! This section is intended for readers trying to understand the macros in this module and the
  15 //! `pin_init!` macros from `init.rs`.
  16 //!
  17 //! We will look at the following example:
  18 //!
  19 //! ```rust
  20 //! # use kernel::init::*;
  21 //! #[pin_data]
  22 //! #[repr(C)]
  23 //! struct Bar<T> {
  24 //!     #[pin]
  25 //!     t: T,
  26 //!     pub x: usize,
  27 //! }
  28 //!
  29 //! impl<T> Bar<T> {
  30 //!     fn new(t: T) -> impl PinInit<Self> {
  31 //!         pin_init!(Self { t, x: 0 })
  32 //!     }
  33 //! }
  34 //!
  35 //! #[pin_data(PinnedDrop)]
  36 //! struct Foo {
  37 //!     a: usize,
  38 //!     #[pin]
  39 //!     b: Bar<u32>,
  40 //! }
  41 //!
  42 //! #[pinned_drop]
  43 //! impl PinnedDrop for Foo {
  44 //!     fn drop(self: Pin<&mut Self>) {
  45 //!         println!("{self:p} is getting dropped.");
  46 //!     }
  47 //! }
  48 //!
  49 //! let a = 42;
  50 //! let initializer = pin_init!(Foo {
  51 //!     a,
  52 //!     b <- Bar::new(36),
  53 //! });
  54 //! ```
  55 //!
  56 //! This example includes the most common and important features of the pin-init API.
  57 //!
  58 //! Below you can find individual section about the different macro invocations. Here are some
  59 //! general things we need to take into account when designing macros:
  60 //! - use global paths, similarly to file paths, these start with the separator: `::core::panic!()`
  61 //!   this ensures that the correct item is used, since users could define their own `mod core {}`
  62 //!   and then their own `panic!` inside to execute arbitrary code inside of our macro.
  63 //! - macro `unsafe` hygiene: we need to ensure that we do not expand arbitrary, user-supplied
  64 //!   expressions inside of an `unsafe` block in the macro, because this would allow users to do
  65 //!   `unsafe` operations without an associated `unsafe` block.
  66 //!
  67 //! ## `#[pin_data]` on `Bar`
  68 //!
  69 //! This macro is used to specify which fields are structurally pinned and which fields are not. It
  70 //! is placed on the struct definition and allows `#[pin]` to be placed on the fields.
  71 //!
  72 //! Here is the definition of `Bar` from our example:
  73 //!
  74 //! ```rust
  75 //! # use kernel::init::*;
  76 //! #[pin_data]
  77 //! #[repr(C)]
  78 //! struct Bar<T> {
  79 //!     t: T,
  80 //!     pub x: usize,
  81 //! }
  82 //! ```
  83 //!
  84 //! This expands to the following code:
  85 //!
  86 //! ```rust
  87 //! // Firstly the normal definition of the struct, attributes are preserved:
  88 //! #[repr(C)]
  89 //! struct Bar<T> {
  90 //!     t: T,
  91 //!     pub x: usize,
  92 //! }
  93 //! // Then an anonymous constant is defined, this is because we do not want any code to access the
  94 //! // types that we define inside:
  95 //! const _: () = {
  96 //!     // We define the pin-data carrying struct, it is a ZST and needs to have the same generics,
  97 //!     // since we need to implement access functions for each field and thus need to know its
  98 //!     // type.
  99 //!     struct __ThePinData<T> {
 100 //!         __phantom: ::core::marker::PhantomData<fn(Bar<T>) -> Bar<T>>,
 101 //!     }
 102 //!     // We implement `Copy` for the pin-data struct, since all functions it defines will take
 103 //!     // `self` by value.
 104 //!     impl<T> ::core::clone::Clone for __ThePinData<T> {
 105 //!         fn clone(&self) -> Self {
 106 //!             *self
 107 //!         }
 108 //!     }
 109 //!     impl<T> ::core::marker::Copy for __ThePinData<T> {}
 110 //!     // For every field of `Bar`, the pin-data struct will define a function with the same name
 111 //!     // and accessor (`pub` or `pub(crate)` etc.). This function will take a pointer to the
 112 //!     // field (`slot`) and a `PinInit` or `Init` depending on the projection kind of the field
 113 //!     // (if pinning is structural for the field, then `PinInit` otherwise `Init`).
 114 //!     #[allow(dead_code)]
 115 //!     impl<T> __ThePinData<T> {
 116 //!         unsafe fn t<E>(
 117 //!             self,
 118 //!             slot: *mut T,
 119 //!             init: impl ::kernel::init::Init<T, E>,
 120 //!         ) -> ::core::result::Result<(), E> {
 121 //!             unsafe { ::kernel::init::Init::__init(init, slot) }
 122 //!         }
 123 //!         pub unsafe fn x<E>(
 124 //!             self,
 125 //!             slot: *mut usize,
 126 //!             init: impl ::kernel::init::Init<usize, E>,
 127 //!         ) -> ::core::result::Result<(), E> {
 128 //!             unsafe { ::kernel::init::Init::__init(init, slot) }
 129 //!         }
 130 //!     }
 131 //!     // Implement the internal `HasPinData` trait that associates `Bar` with the pin-data struct
 132 //!     // that we constructed beforehand.
 133 //!     unsafe impl<T> ::kernel::init::__internal::HasPinData for Bar<T> {
 134 //!         type PinData = __ThePinData<T>;
 135 //!         unsafe fn __pin_data() -> Self::PinData {
 136 //!             __ThePinData {
 137 //!                 __phantom: ::core::marker::PhantomData,
 138 //!             }
 139 //!         }
 140 //!     }
 141 //!     // Implement the internal `PinData` trait that marks the pin-data struct as a pin-data
 142 //!     // struct. This is important to ensure that no user can implement a rouge `__pin_data`
 143 //!     // function without using `unsafe`.
 144 //!     unsafe impl<T> ::kernel::init::__internal::PinData for __ThePinData<T> {
 145 //!         type Datee = Bar<T>;
 146 //!     }
 147 //!     // Now we only want to implement `Unpin` for `Bar` when every structurally pinned field is
 148 //!     // `Unpin`. In other words, whether `Bar` is `Unpin` only depends on structurally pinned
 149 //!     // fields (those marked with `#[pin]`). These fields will be listed in this struct, in our
 150 //!     // case no such fields exist, hence this is almost empty. The two phantomdata fields exist
 151 //!     // for two reasons:
 152 //!     // - `__phantom`: every generic must be used, since we cannot really know which generics
 153 //!     //   are used, we declere all and then use everything here once.
 154 //!     // - `__phantom_pin`: uses the `'__pin` lifetime and ensures that this struct is invariant
 155 //!     //   over it. The lifetime is needed to work around the limitation that trait bounds must
 156 //!     //   not be trivial, e.g. the user has a `#[pin] PhantomPinned` field -- this is
 157 //!     //   unconditionally `!Unpin` and results in an error. The lifetime tricks the compiler
 158 //!     //   into accepting these bounds regardless.
 159 //!     #[allow(dead_code)]
 160 //!     struct __Unpin<'__pin, T> {
 161 //!         __phantom_pin: ::core::marker::PhantomData<fn(&'__pin ()) -> &'__pin ()>,
 162 //!         __phantom: ::core::marker::PhantomData<fn(Bar<T>) -> Bar<T>>,
 163 //!     }
 164 //!     #[doc(hidden)]
 165 //!     impl<'__pin, T>
 166 //!         ::core::marker::Unpin for Bar<T> where __Unpin<'__pin, T>: ::core::marker::Unpin {}
 167 //!     // Now we need to ensure that `Bar` does not implement `Drop`, since that would give users
 168 //!     // access to `&mut self` inside of `drop` even if the struct was pinned. This could lead to
 169 //!     // UB with only safe code, so we disallow this by giving a trait implementation error using
 170 //!     // a direct impl and a blanket implementation.
 171 //!     trait MustNotImplDrop {}
 172 //!     // Normally `Drop` bounds do not have the correct semantics, but for this purpose they do
 173 //!     // (normally people want to know if a type has any kind of drop glue at all, here we want
 174 //!     // to know if it has any kind of custom drop glue, which is exactly what this bound does).
 175 //!     #[allow(drop_bounds)]
 176 //!     impl<T: ::core::ops::Drop> MustNotImplDrop for T {}
 177 //!     impl<T> MustNotImplDrop for Bar<T> {}
 178 //!     // Here comes a convenience check, if one implemented `PinnedDrop`, but forgot to add it to
 179 //!     // `#[pin_data]`, then this will error with the same mechanic as above, this is not needed
 180 //!     // for safety, but a good sanity check, since no normal code calls `PinnedDrop::drop`.
 181 //!     #[allow(non_camel_case_types)]
 182 //!     trait UselessPinnedDropImpl_you_need_to_specify_PinnedDrop {}
 183 //!     impl<T: ::kernel::init::PinnedDrop>
 184 //!         UselessPinnedDropImpl_you_need_to_specify_PinnedDrop for T {}
 185 //!     impl<T> UselessPinnedDropImpl_you_need_to_specify_PinnedDrop for Bar<T> {}
 186 //! };
 187 //! ```
 188 //!
 189 //! ## `pin_init!` in `impl Bar`
 190 //!
 191 //! This macro creates an pin-initializer for the given struct. It requires that the struct is
 192 //! annotated by `#[pin_data]`.
 193 //!
 194 //! Here is the impl on `Bar` defining the new function:
 195 //!
 196 //! ```rust
 197 //! impl<T> Bar<T> {
 198 //!     fn new(t: T) -> impl PinInit<Self> {
 199 //!         pin_init!(Self { t, x: 0 })
 200 //!     }
 201 //! }
 202 //! ```
 203 //!
 204 //! This expands to the following code:
 205 //!
 206 //! ```rust
 207 //! impl<T> Bar<T> {
 208 //!     fn new(t: T) -> impl PinInit<Self> {
 209 //!         {
 210 //!             // We do not want to allow arbitrary returns, so we declare this type as the `Ok`
 211 //!             // return type and shadow it later when we insert the arbitrary user code. That way
 212 //!             // there will be no possibility of returning without `unsafe`.
 213 //!             struct __InitOk;
 214 //!             // Get the pin-data type from the initialized type.
 215 //!             // - the function is unsafe, hence the unsafe block
 216 //!             // - we `use` the `HasPinData` trait in the block, it is only available in that
 217 //!             //   scope.
 218 //!             let data = unsafe {
 219 //!                 use ::kernel::init::__internal::HasPinData;
 220 //!                 Self::__pin_data()
 221 //!             };
 222 //!             // Use `data` to help with type inference, the closure supplied will have the type
 223 //!             // `FnOnce(*mut Self) -> Result<__InitOk, Infallible>`.
 224 //!             let init = ::kernel::init::__internal::PinData::make_closure::<
 225 //!                 _,
 226 //!                 __InitOk,
 227 //!                 ::core::convert::Infallible,
 228 //!             >(data, move |slot| {
 229 //!                 {
 230 //!                     // Shadow the structure so it cannot be used to return early. If a user
 231 //!                     // tries to write `return Ok(__InitOk)`, then they get a type error, since
 232 //!                     // that will refer to this struct instead of the one defined above.
 233 //!                     struct __InitOk;
 234 //!                     // This is the expansion of `t,`, which is syntactic sugar for `t: t,`.
 235 //!                     unsafe { ::core::ptr::write(&raw mut (*slot).t, t) };
 236 //!                     // Since initialization could fail later (not in this case, since the error
 237 //!                     // type is `Infallible`) we will need to drop this field if it fails. This
 238 //!                     // `DropGuard` will drop the field when it gets dropped and has not yet
 239 //!                     // been forgotten. We make a reference to it, so users cannot `mem::forget`
 240 //!                     // it from the initializer, since the name is the same as the field.
 241 //!                     let t = &unsafe {
 242 //!                         ::kernel::init::__internal::DropGuard::new(&raw mut (*slot).t)
 243 //!                     };
 244 //!                     // Expansion of `x: 0,`:
 245 //!                     // Since this can be an arbitrary expression we cannot place it inside of
 246 //!                     // the `unsafe` block, so we bind it here.
 247 //!                     let x = 0;
 248 //!                     unsafe { ::core::ptr::write(&raw mut (*slot).x, x) };
 249 //!                     let x = &unsafe {
 250 //!                         ::kernel::init::__internal::DropGuard::new(&raw mut (*slot).x)
 251 //!                     };
 252 //!
 253 //!                     // Here we use the type checker to ensuer that every field has been
 254 //!                     // initialized exactly once, since this is `if false` it will never get
 255 //!                     // executed, but still type-checked.
 256 //!                     // Additionally we abuse `slot` to automatically infer the correct type for
 257 //!                     // the struct. This is also another check that every field is accessible
 258 //!                     // from this scope.
 259 //!                     #[allow(unreachable_code, clippy::diverging_sub_expression)]
 260 //!                     if false {
 261 //!                         unsafe {
 262 //!                             ::core::ptr::write(
 263 //!                                 slot,
 264 //!                                 Self {
 265 //!                                     // We only care about typecheck finding every field here,
 266 //!                                     // the expression does not matter, just conjure one using
 267 //!                                     // `panic!()`:
 268 //!                                     t: ::core::panic!(),
 269 //!                                     x: ::core::panic!(),
 270 //!                                 },
 271 //!                             );
 272 //!                         };
 273 //!                     }
 274 //!                     // Since initialization has successfully completed, we can now forget the
 275 //!                     // guards.
 276 //!                     unsafe { ::kernel::init::__internal::DropGuard::forget(t) };
 277 //!                     unsafe { ::kernel::init::__internal::DropGuard::forget(x) };
 278 //!                 }
 279 //!                 // We leave the scope above and gain access to the previously shadowed
 280 //!                 // `__InitOk` that we need to return.
 281 //!                 Ok(__InitOk)
 282 //!             });
 283 //!             // Change the return type of the closure.
 284 //!             let init = move |slot| -> ::core::result::Result<(), ::core::convert::Infallible> {
 285 //!                 init(slot).map(|__InitOk| ())
 286 //!             };
 287 //!             // Construct the initializer.
 288 //!             let init = unsafe {
 289 //!                 ::kernel::init::pin_init_from_closure::<_, ::core::convert::Infallible>(init)
 290 //!             };
 291 //!             init
 292 //!         }
 293 //!     }
 294 //! }
 295 //! ```
 296 //!
 297 //! ## `#[pin_data]` on `Foo`
 298 //!
 299 //! Since we already took a look at `#[pin_data]` on `Bar`, this section will only explain the
 300 //! differences/new things in the expansion of the `Foo` definition:
 301 //!
 302 //! ```rust
 303 //! #[pin_data(PinnedDrop)]
 304 //! struct Foo {
 305 //!     a: usize,
 306 //!     #[pin]
 307 //!     b: Bar<u32>,
 308 //! }
 309 //! ```
 310 //!
 311 //! This expands to the following code:
 312 //!
 313 //! ```rust
 314 //! struct Foo {
 315 //!     a: usize,
 316 //!     b: Bar<u32>,
 317 //! }
 318 //! const _: () = {
 319 //!     struct __ThePinData {
 320 //!         __phantom: ::core::marker::PhantomData<fn(Foo) -> Foo>,
 321 //!     }
 322 //!     impl ::core::clone::Clone for __ThePinData {
 323 //!         fn clone(&self) -> Self {
 324 //!             *self
 325 //!         }
 326 //!     }
 327 //!     impl ::core::marker::Copy for __ThePinData {}
 328 //!     #[allow(dead_code)]
 329 //!     impl __ThePinData {
 330 //!         unsafe fn b<E>(
 331 //!             self,
 332 //!             slot: *mut Bar<u32>,
 333 //!             // Note that this is `PinInit` instead of `Init`, this is because `b` is
 334 //!             // structurally pinned, as marked by the `#[pin]` attribute.
 335 //!             init: impl ::kernel::init::PinInit<Bar<u32>, E>,
 336 //!         ) -> ::core::result::Result<(), E> {
 337 //!             unsafe { ::kernel::init::PinInit::__pinned_init(init, slot) }
 338 //!         }
 339 //!         unsafe fn a<E>(
 340 //!             self,
 341 //!             slot: *mut usize,
 342 //!             init: impl ::kernel::init::Init<usize, E>,
 343 //!         ) -> ::core::result::Result<(), E> {
 344 //!             unsafe { ::kernel::init::Init::__init(init, slot) }
 345 //!         }
 346 //!     }
 347 //!     unsafe impl ::kernel::init::__internal::HasPinData for Foo {
 348 //!         type PinData = __ThePinData;
 349 //!         unsafe fn __pin_data() -> Self::PinData {
 350 //!             __ThePinData {
 351 //!                 __phantom: ::core::marker::PhantomData,
 352 //!             }
 353 //!         }
 354 //!     }
 355 //!     unsafe impl ::kernel::init::__internal::PinData for __ThePinData {
 356 //!         type Datee = Foo;
 357 //!     }
 358 //!     #[allow(dead_code)]
 359 //!     struct __Unpin<'__pin> {
 360 //!         __phantom_pin: ::core::marker::PhantomData<fn(&'__pin ()) -> &'__pin ()>,
 361 //!         __phantom: ::core::marker::PhantomData<fn(Foo) -> Foo>,
 362 //!         // Since this field is `#[pin]`, it is listed here.
 363 //!         b: Bar<u32>,
 364 //!     }
 365 //!     #[doc(hidden)]
 366 //!     impl<'__pin> ::core::marker::Unpin for Foo where __Unpin<'__pin>: ::core::marker::Unpin {}
 367 //!     // Since we specified `PinnedDrop` as the argument to `#[pin_data]`, we expect `Foo` to
 368 //!     // implement `PinnedDrop`. Thus we do not need to prevent `Drop` implementations like
 369 //!     // before, instead we implement it here and delegate to `PinnedDrop`.
 370 //!     impl ::core::ops::Drop for Foo {
 371 //!         fn drop(&mut self) {
 372 //!             // Since we are getting dropped, no one else has a reference to `self` and thus we
 373 //!             // can assume that we never move.
 374 //!             let pinned = unsafe { ::core::pin::Pin::new_unchecked(self) };
 375 //!             // Create the unsafe token that proves that we are inside of a destructor, this
 376 //!             // type is only allowed to be created in a destructor.
 377 //!             let token = unsafe { ::kernel::init::__internal::OnlyCallFromDrop::new() };
 378 //!             ::kernel::init::PinnedDrop::drop(pinned, token);
 379 //!         }
 380 //!     }
 381 //! };
 382 //! ```
 383 //!
 384 //! ## `#[pinned_drop]` on `impl PinnedDrop for Foo`
 385 //!
 386 //! This macro is used to implement the `PinnedDrop` trait, since that trait is `unsafe` and has an
 387 //! extra parameter that should not be used at all. The macro hides that parameter.
 388 //!
 389 //! Here is the `PinnedDrop` impl for `Foo`:
 390 //!
 391 //! ```rust
 392 //! #[pinned_drop]
 393 //! impl PinnedDrop for Foo {
 394 //!     fn drop(self: Pin<&mut Self>) {
 395 //!         println!("{self:p} is getting dropped.");
 396 //!     }
 397 //! }
 398 //! ```
 399 //!
 400 //! This expands to the following code:
 401 //!
 402 //! ```rust
 403 //! // `unsafe`, full path and the token parameter are added, everything else stays the same.
 404 //! unsafe impl ::kernel::init::PinnedDrop for Foo {
 405 //!     fn drop(self: Pin<&mut Self>, _: ::kernel::init::__internal::OnlyCallFromDrop) {
 406 //!         println!("{self:p} is getting dropped.");
 407 //!     }
 408 //! }
 409 //! ```
 410 //!
 411 //! ## `pin_init!` on `Foo`
 412 //!
 413 //! Since we already took a look at `pin_init!` on `Bar`, this section will only explain the
 414 //! differences/new things in the expansion of `pin_init!` on `Foo`:
 415 //!
 416 //! ```rust
 417 //! let a = 42;
 418 //! let initializer = pin_init!(Foo {
 419 //!     a,
 420 //!     b <- Bar::new(36),
 421 //! });
 422 //! ```
 423 //!
 424 //! This expands to the following code:
 425 //!
 426 //! ```rust
 427 //! let a = 42;
 428 //! let initializer = {
 429 //!     struct __InitOk;
 430 //!     let data = unsafe {
 431 //!         use ::kernel::init::__internal::HasPinData;
 432 //!         Foo::__pin_data()
 433 //!     };
 434 //!     let init = ::kernel::init::__internal::PinData::make_closure::<
 435 //!         _,
 436 //!         __InitOk,
 437 //!         ::core::convert::Infallible,
 438 //!     >(data, move |slot| {
 439 //!         {
 440 //!             struct __InitOk;
 441 //!             unsafe { ::core::ptr::write(&raw mut (*slot).a, a) };
 442 //!             let a = &unsafe { ::kernel::init::__internal::DropGuard::new(&raw mut (*slot).a) };
 443 //!             let b = Bar::new(36);
 444 //!             // Here we use `data` to access the correct field and require that `b` is of type
 445 //!             // `PinInit<Bar<u32>, Infallible>`.
 446 //!             unsafe { data.b(&raw mut (*slot).b, b)? };
 447 //!             let b = &unsafe { ::kernel::init::__internal::DropGuard::new(&raw mut (*slot).b) };
 448 //!
 449 //!             #[allow(unreachable_code, clippy::diverging_sub_expression)]
 450 //!             if false {
 451 //!                 unsafe {
 452 //!                     ::core::ptr::write(
 453 //!                         slot,
 454 //!                         Foo {
 455 //!                             a: ::core::panic!(),
 456 //!                             b: ::core::panic!(),
 457 //!                         },
 458 //!                     );
 459 //!                 };
 460 //!             }
 461 //!             unsafe { ::kernel::init::__internal::DropGuard::forget(a) };
 462 //!             unsafe { ::kernel::init::__internal::DropGuard::forget(b) };
 463 //!         }
 464 //!         Ok(__InitOk)
 465 //!     });
 466 //!     let init = move |slot| -> ::core::result::Result<(), ::core::convert::Infallible> {
 467 //!         init(slot).map(|__InitOk| ())
 468 //!     };
 469 //!     let init = unsafe {
 470 //!         ::kernel::init::pin_init_from_closure::<_, ::core::convert::Infallible>(init)
 471 //!     };
 472 //!     init
 473 //! };
 474 //! ```
 475
 476 /// Creates a `unsafe impl<...> PinnedDrop for $type` block.
 477 ///
 478 /// See [`PinnedDrop`] for more information.
 479 #[doc(hidden)]
 480 #[macro_export]
 481 macro_rules! __pinned_drop {
 482     (
 483         @impl_sig($($impl_sig:tt)*),
 484         @impl_body(
 485             $(#[$($attr:tt)*])*
 486             fn drop($($sig:tt)*) {
 487                 $($inner:tt)*
 488             }
 489         ),
 490     ) => {
 491         unsafe $($impl_sig)* {
 492             // Inherit all attributes and the type/ident tokens for the signature.
 493             $(#[$($attr)*])*
 494             fn drop($($sig)*, _: $crate::init::__internal::OnlyCallFromDrop) {
 495                 $($inner)*
 496             }
 497         }
 498     }
 499 }
 500
 501 /// This macro first parses the struct definition such that it separates pinned and not pinned
 502 /// fields. Afterwards it declares the struct and implement the `PinData` trait safely.
 503 #[doc(hidden)]
 504 #[macro_export]
 505 macro_rules! __pin_data {
 506     // Proc-macro entry point, this is supplied by the proc-macro pre-parsing.
 507     (parse_input:
 508         @args($($pinned_drop:ident)?),
 509         @sig(
 510             $(#[$($struct_attr:tt)*])*
 511             $vis:vis struct $name:ident
 512             $(where $($whr:tt)*)?
 513         ),
 514         @impl_generics($($impl_generics:tt)*),
 515         @ty_generics($($ty_generics:tt)*),
 516         @body({ $($fields:tt)* }),
 517     ) => {
 518         // We now use token munching to iterate through all of the fields. While doing this we
 519         // identify fields marked with `#[pin]`, these fields are the 'pinned fields'. The user
 520         // wants these to be structurally pinned. The rest of the fields are the
 521         // 'not pinned fields'. Additionally we collect all fields, since we need them in the right
 522         // order to declare the struct.
 523         //
 524         // In this call we also put some explaining comments for the parameters.
 525         $crate::__pin_data!(find_pinned_fields:
 526             // Attributes on the struct itself, these will just be propagated to be put onto the
 527             // struct definition.
 528             @struct_attrs($(#[$($struct_attr)*])*),
 529             // The visibility of the struct.
 530             @vis($vis),
 531             // The name of the struct.
 532             @name($name),
 533             // The 'impl generics', the generics that will need to be specified on the struct inside
 534             // of an `impl<$ty_generics>` block.
 535             @impl_generics($($impl_generics)*),
 536             // The 'ty generics', the generics that will need to be specified on the impl blocks.
 537             @ty_generics($($ty_generics)*),
 538             // The where clause of any impl block and the declaration.
 539             @where($($($whr)*)?),
 540             // The remaining fields tokens that need to be processed.
 541             // We add a `,` at the end to ensure correct parsing.
 542             @fields_munch($($fields)* ,),
 543             // The pinned fields.
 544             @pinned(),
 545             // The not pinned fields.
 546             @not_pinned(),
 547             // All fields.
 548             @fields(),
 549             // The accumulator containing all attributes already parsed.
 550             @accum(),
 551             // Contains `yes` or `` to indicate if `#[pin]` was found on the current field.
 552             @is_pinned(),
 553             // The proc-macro argument, this should be `PinnedDrop` or ``.
 554             @pinned_drop($($pinned_drop)?),
 555         );
 556     };
 557     (find_pinned_fields:
 558         @struct_attrs($($struct_attrs:tt)*),
 559         @vis($vis:vis),
 560         @name($name:ident),
 561         @impl_generics($($impl_generics:tt)*),
 562         @ty_generics($($ty_generics:tt)*),
 563         @where($($whr:tt)*),
 564         // We found a PhantomPinned field, this should generally be pinned!
 565         @fields_munch($field:ident : $($($(::)?core::)?marker::)?PhantomPinned, $($rest:tt)*),
 566         @pinned($($pinned:tt)*),
 567         @not_pinned($($not_pinned:tt)*),
 568         @fields($($fields:tt)*),
 569         @accum($($accum:tt)*),
 570         // This field is not pinned.
 571         @is_pinned(),
 572         @pinned_drop($($pinned_drop:ident)?),
 573     ) => {
 574         ::core::compile_error!(concat!(
 575             "The field `",
 576             stringify!($field),
 577             "` of type `PhantomPinned` only has an effect, if it has the `#[pin]` attribute.",
 578         ));
 579         $crate::__pin_data!(find_pinned_fields:
 580             @struct_attrs($($struct_attrs)*),
 581             @vis($vis),
 582             @name($name),
 583             @impl_generics($($impl_generics)*),
 584             @ty_generics($($ty_generics)*),
 585             @where($($whr)*),
 586             @fields_munch($($rest)*),
 587             @pinned($($pinned)* $($accum)* $field: ::core::marker::PhantomPinned,),
 588             @not_pinned($($not_pinned)*),
 589             @fields($($fields)* $($accum)* $field: ::core::marker::PhantomPinned,),
 590             @accum(),
 591             @is_pinned(),
 592             @pinned_drop($($pinned_drop)?),
 593         );
 594     };
 595     (find_pinned_fields:
 596         @struct_attrs($($struct_attrs:tt)*),
 597         @vis($vis:vis),
 598         @name($name:ident),
 599         @impl_generics($($impl_generics:tt)*),
 600         @ty_generics($($ty_generics:tt)*),
 601         @where($($whr:tt)*),
 602         // We reached the field declaration.
 603         @fields_munch($field:ident : $type:ty, $($rest:tt)*),
 604         @pinned($($pinned:tt)*),
 605         @not_pinned($($not_pinned:tt)*),
 606         @fields($($fields:tt)*),
 607         @accum($($accum:tt)*),
 608         // This field is pinned.
 609         @is_pinned(yes),
 610         @pinned_drop($($pinned_drop:ident)?),
 611     ) => {
 612         $crate::__pin_data!(find_pinned_fields:
 613             @struct_attrs($($struct_attrs)*),
 614             @vis($vis),
 615             @name($name),
 616             @impl_generics($($impl_generics)*),
 617             @ty_generics($($ty_generics)*),
 618             @where($($whr)*),
 619             @fields_munch($($rest)*),
 620             @pinned($($pinned)* $($accum)* $field: $type,),
 621             @not_pinned($($not_pinned)*),
 622             @fields($($fields)* $($accum)* $field: $type,),
 623             @accum(),
 624             @is_pinned(),
 625             @pinned_drop($($pinned_drop)?),
 626         );
 627     };
 628     (find_pinned_fields:
 629         @struct_attrs($($struct_attrs:tt)*),
 630         @vis($vis:vis),
 631         @name($name:ident),
 632         @impl_generics($($impl_generics:tt)*),
 633         @ty_generics($($ty_generics:tt)*),
 634         @where($($whr:tt)*),
 635         // We reached the field declaration.
 636         @fields_munch($field:ident : $type:ty, $($rest:tt)*),
 637         @pinned($($pinned:tt)*),
 638         @not_pinned($($not_pinned:tt)*),
 639         @fields($($fields:tt)*),
 640         @accum($($accum:tt)*),
 641         // This field is not pinned.
 642         @is_pinned(),
 643         @pinned_drop($($pinned_drop:ident)?),
 644     ) => {
 645         $crate::__pin_data!(find_pinned_fields:
 646             @struct_attrs($($struct_attrs)*),
 647             @vis($vis),
 648             @name($name),
 649             @impl_generics($($impl_generics)*),
 650             @ty_generics($($ty_generics)*),
 651             @where($($whr)*),
 652             @fields_munch($($rest)*),
 653             @pinned($($pinned)*),
 654             @not_pinned($($not_pinned)* $($accum)* $field: $type,),
 655             @fields($($fields)* $($accum)* $field: $type,),
 656             @accum(),
 657             @is_pinned(),
 658             @pinned_drop($($pinned_drop)?),
 659         );
 660     };
 661     (find_pinned_fields:
 662         @struct_attrs($($struct_attrs:tt)*),
 663         @vis($vis:vis),
 664         @name($name:ident),
 665         @impl_generics($($impl_generics:tt)*),
 666         @ty_generics($($ty_generics:tt)*),
 667         @where($($whr:tt)*),
 668         // We found the `#[pin]` attr.
 669         @fields_munch(#[pin] $($rest:tt)*),
 670         @pinned($($pinned:tt)*),
 671         @not_pinned($($not_pinned:tt)*),
 672         @fields($($fields:tt)*),
 673         @accum($($accum:tt)*),
 674         @is_pinned($($is_pinned:ident)?),
 675         @pinned_drop($($pinned_drop:ident)?),
 676     ) => {
 677         $crate::__pin_data!(find_pinned_fields:
 678             @struct_attrs($($struct_attrs)*),
 679             @vis($vis),
 680             @name($name),
 681             @impl_generics($($impl_generics)*),
 682             @ty_generics($($ty_generics)*),
 683             @where($($whr)*),
 684             @fields_munch($($rest)*),
 685             // We do not include `#[pin]` in the list of attributes, since it is not actually an
 686             // attribute that is defined somewhere.
 687             @pinned($($pinned)*),
 688             @not_pinned($($not_pinned)*),
 689             @fields($($fields)*),
 690             @accum($($accum)*),
 691             // Set this to `yes`.
 692             @is_pinned(yes),
 693             @pinned_drop($($pinned_drop)?),
 694         );
 695     };
 696     (find_pinned_fields:
 697         @struct_attrs($($struct_attrs:tt)*),
 698         @vis($vis:vis),
 699         @name($name:ident),
 700         @impl_generics($($impl_generics:tt)*),
 701         @ty_generics($($ty_generics:tt)*),
 702         @where($($whr:tt)*),
 703         // We reached the field declaration with visibility, for simplicity we only munch the
 704         // visibility and put it into `$accum`.
 705         @fields_munch($fvis:vis $field:ident $($rest:tt)*),
 706         @pinned($($pinned:tt)*),
 707         @not_pinned($($not_pinned:tt)*),
 708         @fields($($fields:tt)*),
 709         @accum($($accum:tt)*),
 710         @is_pinned($($is_pinned:ident)?),
 711         @pinned_drop($($pinned_drop:ident)?),
 712     ) => {
 713         $crate::__pin_data!(find_pinned_fields:
 714             @struct_attrs($($struct_attrs)*),
 715             @vis($vis),
 716             @name($name),
 717             @impl_generics($($impl_generics)*),
 718             @ty_generics($($ty_generics)*),
 719             @where($($whr)*),
 720             @fields_munch($field $($rest)*),
 721             @pinned($($pinned)*),
 722             @not_pinned($($not_pinned)*),
 723             @fields($($fields)*),
 724             @accum($($accum)* $fvis),
 725             @is_pinned($($is_pinned)?),
 726             @pinned_drop($($pinned_drop)?),
 727         );
 728     };
 729     (find_pinned_fields:
 730         @struct_attrs($($struct_attrs:tt)*),
 731         @vis($vis:vis),
 732         @name($name:ident),
 733         @impl_generics($($impl_generics:tt)*),
 734         @ty_generics($($ty_generics:tt)*),
 735         @where($($whr:tt)*),
 736         // Some other attribute, just put it into `$accum`.
 737         @fields_munch(#[$($attr:tt)*] $($rest:tt)*),
 738         @pinned($($pinned:tt)*),
 739         @not_pinned($($not_pinned:tt)*),
 740         @fields($($fields:tt)*),
 741         @accum($($accum:tt)*),
 742         @is_pinned($($is_pinned:ident)?),
 743         @pinned_drop($($pinned_drop:ident)?),
 744     ) => {
 745         $crate::__pin_data!(find_pinned_fields:
 746             @struct_attrs($($struct_attrs)*),
 747             @vis($vis),
 748             @name($name),
 749             @impl_generics($($impl_generics)*),
 750             @ty_generics($($ty_generics)*),
 751             @where($($whr)*),
 752             @fields_munch($($rest)*),
 753             @pinned($($pinned)*),
 754             @not_pinned($($not_pinned)*),
 755             @fields($($fields)*),
 756             @accum($($accum)* #[$($attr)*]),
 757             @is_pinned($($is_pinned)?),
 758             @pinned_drop($($pinned_drop)?),
 759         );
 760     };
 761     (find_pinned_fields:
 762         @struct_attrs($($struct_attrs:tt)*),
 763         @vis($vis:vis),
 764         @name($name:ident),
 765         @impl_generics($($impl_generics:tt)*),
 766         @ty_generics($($ty_generics:tt)*),
 767         @where($($whr:tt)*),
 768         // We reached the end of the fields, plus an optional additional comma, since we added one
 769         // before and the user is also allowed to put a trailing comma.
 770         @fields_munch($(,)?),
 771         @pinned($($pinned:tt)*),
 772         @not_pinned($($not_pinned:tt)*),
 773         @fields($($fields:tt)*),
 774         @accum(),
 775         @is_pinned(),
 776         @pinned_drop($($pinned_drop:ident)?),
 777     ) => {
 778         // Declare the struct with all fields in the correct order.
 779         $($struct_attrs)*
 780         $vis struct $name <$($impl_generics)*>
 781         where $($whr)*
 782         {
 783             $($fields)*
 784         }
 785
 786         // We put the rest into this const item, because it then will not be accessible to anything
 787         // outside.
 788         const _: () = {
 789             // We declare this struct which will host all of the projection function for our type.
 790             // it will be invariant over all generic parameters which are inherited from the
 791             // struct.
 792             $vis struct __ThePinData<$($impl_generics)*>
 793             where $($whr)*
 794             {
 795                 __phantom: ::core::marker::PhantomData<
 796                     fn($name<$($ty_generics)*>) -> $name<$($ty_generics)*>
 797                 >,
 798             }
 799
 800             impl<$($impl_generics)*> ::core::clone::Clone for __ThePinData<$($ty_generics)*>
 801             where $($whr)*
 802             {
 803                 fn clone(&self) -> Self { *self }
 804             }
 805
 806             impl<$($impl_generics)*> ::core::marker::Copy for __ThePinData<$($ty_generics)*>
 807             where $($whr)*
 808             {}
 809
 810             // Make all projection functions.
 811             $crate::__pin_data!(make_pin_data:
 812                 @pin_data(__ThePinData),
 813                 @impl_generics($($impl_generics)*),
 814                 @ty_generics($($ty_generics)*),
 815                 @where($($whr)*),
 816                 @pinned($($pinned)*),
 817                 @not_pinned($($not_pinned)*),
 818             );
 819
 820             // SAFETY: We have added the correct projection functions above to `__ThePinData` and
 821             // we also use the least restrictive generics possible.
 822             unsafe impl<$($impl_generics)*>
 823                 $crate::init::__internal::HasPinData for $name<$($ty_generics)*>
 824             where $($whr)*
 825             {
 826                 type PinData = __ThePinData<$($ty_generics)*>;
 827
 828                 unsafe fn __pin_data() -> Self::PinData {
 829                     __ThePinData { __phantom: ::core::marker::PhantomData }
 830                 }
 831             }
 832
 833             unsafe impl<$($impl_generics)*>
 834                 $crate::init::__internal::PinData for __ThePinData<$($ty_generics)*>
 835             where $($whr)*
 836             {
 837                 type Datee = $name<$($ty_generics)*>;
 838             }
 839
 840             // This struct will be used for the unpin analysis. Since only structurally pinned
 841             // fields are relevant whether the struct should implement `Unpin`.
 842             #[allow(dead_code)]
 843             struct __Unpin <'__pin, $($impl_generics)*>
 844             where $($whr)*
 845             {
 846                 __phantom_pin: ::core::marker::PhantomData<fn(&'__pin ()) -> &'__pin ()>,
 847                 __phantom: ::core::marker::PhantomData<
 848                     fn($name<$($ty_generics)*>) -> $name<$($ty_generics)*>
 849                 >,
 850                 // Only the pinned fields.
 851                 $($pinned)*
 852             }
 853
 854             #[doc(hidden)]
 855             impl<'__pin, $($impl_generics)*> ::core::marker::Unpin for $name<$($ty_generics)*>
 856             where
 857                 __Unpin<'__pin, $($ty_generics)*>: ::core::marker::Unpin,
 858                 $($whr)*
 859             {}
 860
 861             // We need to disallow normal `Drop` implementation, the exact behavior depends on
 862             // whether `PinnedDrop` was specified as the parameter.
 863             $crate::__pin_data!(drop_prevention:
 864                 @name($name),
 865                 @impl_generics($($impl_generics)*),
 866                 @ty_generics($($ty_generics)*),
 867                 @where($($whr)*),
 868                 @pinned_drop($($pinned_drop)?),
 869             );
 870         };
 871     };
 872     // When no `PinnedDrop` was specified, then we have to prevent implementing drop.
 873     (drop_prevention:
 874         @name($name:ident),
 875         @impl_generics($($impl_generics:tt)*),
 876         @ty_generics($($ty_generics:tt)*),
 877         @where($($whr:tt)*),
 878         @pinned_drop(),
 879     ) => {
 880         // We prevent this by creating a trait that will be implemented for all types implementing
 881         // `Drop`. Additionally we will implement this trait for the struct leading to a conflict,
 882         // if it also implements `Drop`
 883         trait MustNotImplDrop {}
 884         #[allow(drop_bounds)]
 885         impl<T: ::core::ops::Drop> MustNotImplDrop for T {}
 886         impl<$($impl_generics)*> MustNotImplDrop for $name<$($ty_generics)*>
 887         where $($whr)* {}
 888         // We also take care to prevent users from writing a useless `PinnedDrop` implementation.
 889         // They might implement `PinnedDrop` correctly for the struct, but forget to give
 890         // `PinnedDrop` as the parameter to `#[pin_data]`.
 891         #[allow(non_camel_case_types)]
 892         trait UselessPinnedDropImpl_you_need_to_specify_PinnedDrop {}
 893         impl<T: $crate::init::PinnedDrop>
 894             UselessPinnedDropImpl_you_need_to_specify_PinnedDrop for T {}
 895         impl<$($impl_generics)*>
 896             UselessPinnedDropImpl_you_need_to_specify_PinnedDrop for $name<$($ty_generics)*>
 897         where $($whr)* {}
 898     };
 899     // When `PinnedDrop` was specified we just implement `Drop` and delegate.
 900     (drop_prevention:
 901         @name($name:ident),
 902         @impl_generics($($impl_generics:tt)*),
 903         @ty_generics($($ty_generics:tt)*),
 904         @where($($whr:tt)*),
 905         @pinned_drop(PinnedDrop),
 906     ) => {
 907         impl<$($impl_generics)*> ::core::ops::Drop for $name<$($ty_generics)*>
 908         where $($whr)*
 909         {
 910             fn drop(&mut self) {
 911                 // SAFETY: Since this is a destructor, `self` will not move after this function
 912                 // terminates, since it is inaccessible.
 913                 let pinned = unsafe { ::core::pin::Pin::new_unchecked(self) };
 914                 // SAFETY: Since this is a drop function, we can create this token to call the
 915                 // pinned destructor of this type.
 916                 let token = unsafe { $crate::init::__internal::OnlyCallFromDrop::new() };
 917                 $crate::init::PinnedDrop::drop(pinned, token);
 918             }
 919         }
 920     };
 921     // If some other parameter was specified, we emit a readable error.
 922     (drop_prevention:
 923         @name($name:ident),
 924         @impl_generics($($impl_generics:tt)*),
 925         @ty_generics($($ty_generics:tt)*),
 926         @where($($whr:tt)*),
 927         @pinned_drop($($rest:tt)*),
 928     ) => {
 929         compile_error!(
 930             "Wrong parameters to `#[pin_data]`, expected nothing or `PinnedDrop`, got '{}'.",
 931             stringify!($($rest)*),
 932         );
 933     };
 934     (make_pin_data:
 935         @pin_data($pin_data:ident),
 936         @impl_generics($($impl_generics:tt)*),
 937         @ty_generics($($ty_generics:tt)*),
 938         @where($($whr:tt)*),
 939         @pinned($($(#[$($p_attr:tt)*])* $pvis:vis $p_field:ident : $p_type:ty),* $(,)?),
 940         @not_pinned($($(#[$($attr:tt)*])* $fvis:vis $field:ident : $type:ty),* $(,)?),
 941     ) => {
 942         // For every field, we create a projection function according to its projection type. If a
 943         // field is structurally pinned, then it must be initialized via `PinInit`, if it is not
 944         // structurally pinned, then it can be initialized via `Init`.
 945         //
 946         // The functions are `unsafe` to prevent accidentally calling them.
 947         #[allow(dead_code)]
 948         impl<$($impl_generics)*> $pin_data<$($ty_generics)*>
 949         where $($whr)*
 950         {
 951             $(
 952                 $pvis unsafe fn $p_field<E>(
 953                     self,
 954                     slot: *mut $p_type,
 955                     init: impl $crate::init::PinInit<$p_type, E>,
 956                 ) -> ::core::result::Result<(), E> {
 957                     unsafe { $crate::init::PinInit::__pinned_init(init, slot) }
 958                 }
 959             )*
 960             $(
 961                 $fvis unsafe fn $field<E>(
 962                     self,
 963                     slot: *mut $type,
 964                     init: impl $crate::init::Init<$type, E>,
 965                 ) -> ::core::result::Result<(), E> {
 966                     unsafe { $crate::init::Init::__init(init, slot) }
 967                 }
 968             )*
 969         }
 970     };
 971 }