1 /*! 2 <!-- tidy:crate-doc:start --> 3 A lightweight version of [pin-project] written with declarative macros. 4 5 ## Usage 6 7 Add this to your `Cargo.toml`: 8 9 ```toml 10 [dependencies] 11 pin-project-lite = "0.2" 12 ``` 13 14 *Compiler support: requires rustc 1.37+* 15 16 ## Examples 17 18 [`pin_project!`] macro creates a projection type covering all the fields of 19 struct. 20 21 ```rust 22 use std::pin::Pin; 23 24 use pin_project_lite::pin_project; 25 26 pin_project! { 27 struct Struct<T, U> { 28 #[pin] 29 pinned: T, 30 unpinned: U, 31 } 32 } 33 34 impl<T, U> Struct<T, U> { 35 fn method(self: Pin<&mut Self>) { 36 let this = self.project(); 37 let _: Pin<&mut T> = this.pinned; // Pinned reference to the field 38 let _: &mut U = this.unpinned; // Normal reference to the field 39 } 40 } 41 ``` 42 43 To use [`pin_project!`] on enums, you need to name the projection type 44 returned from the method. 45 46 ```rust 47 use std::pin::Pin; 48 49 use pin_project_lite::pin_project; 50 51 pin_project! { 52 #[project = EnumProj] 53 enum Enum<T, U> { 54 Variant { #[pin] pinned: T, unpinned: U }, 55 } 56 } 57 58 impl<T, U> Enum<T, U> { 59 fn method(self: Pin<&mut Self>) { 60 match self.project() { 61 EnumProj::Variant { pinned, unpinned } => { 62 let _: Pin<&mut T> = pinned; 63 let _: &mut U = unpinned; 64 } 65 } 66 } 67 } 68 ``` 69 70 ## [pin-project] vs pin-project-lite 71 72 Here are some similarities and differences compared to [pin-project]. 73 74 ### Similar: Safety 75 76 pin-project-lite guarantees safety in much the same way as [pin-project]. 77 Both are completely safe unless you write other unsafe code. 78 79 ### Different: Minimal design 80 81 This library does not tackle as expansive of a range of use cases as 82 [pin-project] does. If your use case is not already covered, please use 83 [pin-project]. 84 85 ### Different: No proc-macro related dependencies 86 87 This is the **only** reason to use this crate. However, **if you already 88 have proc-macro related dependencies in your crate's dependency graph, there 89 is no benefit from using this crate.** (Note: There is almost no difference 90 in the amount of code generated between [pin-project] and pin-project-lite.) 91 92 ### Different: No useful error messages 93 94 This macro does not handle any invalid input. So error messages are not to 95 be useful in most cases. If you do need useful error messages, then upon 96 error you can pass the same input to [pin-project] to receive a helpful 97 description of the compile error. 98 99 ### Different: No support for custom Unpin implementation 100 101 pin-project supports this by [`UnsafeUnpin`][unsafe-unpin]. (`!Unpin` is supported by both [pin-project][not-unpin] and [pin-project-lite][not-unpin-lite].) 102 103 ### Different: No support for tuple structs and tuple variants 104 105 pin-project supports this. 106 107 [not-unpin]: https://docs.rs/pin-project/1/pin_project/attr.pin_project.html#unpin 108 [not-unpin-lite]: https://docs.rs/pin-project-lite/0.2/pin_project_lite/macro.pin_project.html#unpin 109 [pin-project]: https://github.com/taiki-e/pin-project 110 [unsafe-unpin]: https://docs.rs/pin-project/1/pin_project/attr.pin_project.html#unsafeunpin 111 112 <!-- tidy:crate-doc:end --> 113 */ 114 115 #![no_std] 116 #![doc(test( 117 no_crate_inject, 118 attr( 119 deny(warnings, rust_2018_idioms, single_use_lifetimes), 120 allow(dead_code, unused_variables) 121 ) 122 ))] 123 #![warn(rust_2018_idioms, single_use_lifetimes, unreachable_pub)] 124 #![warn( 125 clippy::pedantic, 126 // lints for public library 127 clippy::alloc_instead_of_core, 128 clippy::exhaustive_enums, 129 clippy::exhaustive_structs, 130 clippy::std_instead_of_alloc, 131 clippy::std_instead_of_core, 132 // lints that help writing unsafe code 133 clippy::as_ptr_cast_mut, 134 clippy::default_union_representation, 135 clippy::trailing_empty_array, 136 clippy::transmute_undefined_repr, 137 clippy::undocumented_unsafe_blocks, 138 )] 139 140 // ANDROID: Use std to allow building as a dylib. 141 #[cfg(android_dylib)] 142 extern crate std; 143 144 /// A macro that creates a projection type covering all the fields of struct. 145 /// 146 /// This macro creates a projection type according to the following rules: 147 /// 148 /// - For the field that uses `#[pin]` attribute, makes the pinned reference to the field. 149 /// - For the other fields, makes the unpinned reference to the field. 150 /// 151 /// And the following methods are implemented on the original type: 152 /// 153 /// ```rust 154 /// # use std::pin::Pin; 155 /// # type Projection<'a> = &'a (); 156 /// # type ProjectionRef<'a> = &'a (); 157 /// # trait Dox { 158 /// fn project(self: Pin<&mut Self>) -> Projection<'_>; 159 /// fn project_ref(self: Pin<&Self>) -> ProjectionRef<'_>; 160 /// # } 161 /// ``` 162 /// 163 /// By passing an attribute with the same name as the method to the macro, 164 /// you can name the projection type returned from the method. This allows you 165 /// to use pattern matching on the projected types. 166 /// 167 /// ```rust 168 /// # use pin_project_lite::pin_project; 169 /// # use std::pin::Pin; 170 /// pin_project! { 171 /// #[project = EnumProj] 172 /// enum Enum<T> { 173 /// Variant { #[pin] field: T }, 174 /// } 175 /// } 176 /// 177 /// impl<T> Enum<T> { 178 /// fn method(self: Pin<&mut Self>) { 179 /// let this: EnumProj<'_, T> = self.project(); 180 /// match this { 181 /// EnumProj::Variant { field } => { 182 /// let _: Pin<&mut T> = field; 183 /// } 184 /// } 185 /// } 186 /// } 187 /// ``` 188 /// 189 /// By passing the `#[project_replace = MyProjReplace]` attribute you may create an additional 190 /// method which allows the contents of `Pin<&mut Self>` to be replaced while simultaneously moving 191 /// out all unpinned fields in `Self`. 192 /// 193 /// ```rust 194 /// # use std::pin::Pin; 195 /// # type MyProjReplace = (); 196 /// # trait Dox { 197 /// fn project_replace(self: Pin<&mut Self>, replacement: Self) -> MyProjReplace; 198 /// # } 199 /// ``` 200 /// 201 /// Also, note that the projection types returned by `project` and `project_ref` have 202 /// an additional lifetime at the beginning of generics. 203 /// 204 /// ```text 205 /// let this: EnumProj<'_, T> = self.project(); 206 /// ^^ 207 /// ``` 208 /// 209 /// The visibility of the projected types and projection methods is based on the 210 /// original type. However, if the visibility of the original type is `pub`, the 211 /// visibility of the projected types and the projection methods is downgraded 212 /// to `pub(crate)`. 213 /// 214 /// # Safety 215 /// 216 /// `pin_project!` macro guarantees safety in much the same way as [pin-project] crate. 217 /// Both are completely safe unless you write other unsafe code. 218 /// 219 /// See [pin-project] crate for more details. 220 /// 221 /// # Examples 222 /// 223 /// ```rust 224 /// use std::pin::Pin; 225 /// 226 /// use pin_project_lite::pin_project; 227 /// 228 /// pin_project! { 229 /// struct Struct<T, U> { 230 /// #[pin] 231 /// pinned: T, 232 /// unpinned: U, 233 /// } 234 /// } 235 /// 236 /// impl<T, U> Struct<T, U> { 237 /// fn method(self: Pin<&mut Self>) { 238 /// let this = self.project(); 239 /// let _: Pin<&mut T> = this.pinned; // Pinned reference to the field 240 /// let _: &mut U = this.unpinned; // Normal reference to the field 241 /// } 242 /// } 243 /// ``` 244 /// 245 /// To use `pin_project!` on enums, you need to name the projection type 246 /// returned from the method. 247 /// 248 /// ```rust 249 /// use std::pin::Pin; 250 /// 251 /// use pin_project_lite::pin_project; 252 /// 253 /// pin_project! { 254 /// #[project = EnumProj] 255 /// enum Enum<T> { 256 /// Struct { 257 /// #[pin] 258 /// field: T, 259 /// }, 260 /// Unit, 261 /// } 262 /// } 263 /// 264 /// impl<T> Enum<T> { 265 /// fn method(self: Pin<&mut Self>) { 266 /// match self.project() { 267 /// EnumProj::Struct { field } => { 268 /// let _: Pin<&mut T> = field; 269 /// } 270 /// EnumProj::Unit => {} 271 /// } 272 /// } 273 /// } 274 /// ``` 275 /// 276 /// If you want to call the `project()` method multiple times or later use the 277 /// original [`Pin`] type, it needs to use [`.as_mut()`][`Pin::as_mut`] to avoid 278 /// consuming the [`Pin`]. 279 /// 280 /// ```rust 281 /// use std::pin::Pin; 282 /// 283 /// use pin_project_lite::pin_project; 284 /// 285 /// pin_project! { 286 /// struct Struct<T> { 287 /// #[pin] 288 /// field: T, 289 /// } 290 /// } 291 /// 292 /// impl<T> Struct<T> { 293 /// fn call_project_twice(mut self: Pin<&mut Self>) { 294 /// // `project` consumes `self`, so reborrow the `Pin<&mut Self>` via `as_mut`. 295 /// self.as_mut().project(); 296 /// self.as_mut().project(); 297 /// } 298 /// } 299 /// ``` 300 /// 301 /// # `!Unpin` 302 /// 303 /// If you want to make sure `Unpin` is not implemented, use the `#[project(!Unpin)]` 304 /// attribute. 305 /// 306 /// ``` 307 /// use pin_project_lite::pin_project; 308 /// 309 /// pin_project! { 310 /// #[project(!Unpin)] 311 /// struct Struct<T> { 312 /// #[pin] 313 /// field: T, 314 /// } 315 /// } 316 /// ``` 317 /// 318 /// This is equivalent to using `#[pin]` attribute for a [`PhantomPinned`] field. 319 /// 320 /// ```rust 321 /// use std::marker::PhantomPinned; 322 /// 323 /// use pin_project_lite::pin_project; 324 /// 325 /// pin_project! { 326 /// struct Struct<T> { 327 /// field: T, 328 /// #[pin] 329 /// _pin: PhantomPinned, 330 /// } 331 /// } 332 /// ``` 333 /// 334 /// Note that using [`PhantomPinned`] without `#[pin]` or `#[project(!Unpin)]` 335 /// attribute has no effect. 336 /// 337 /// [`PhantomPinned`]: core::marker::PhantomPinned 338 /// [`Pin::as_mut`]: core::pin::Pin::as_mut 339 /// [`Pin`]: core::pin::Pin 340 /// [pin-project]: https://github.com/taiki-e/pin-project 341 #[macro_export] 342 macro_rules! pin_project { 343 ($($tt:tt)*) => { 344 $crate::__pin_project_internal! { 345 [][][][][] 346 $($tt)* 347 } 348 }; 349 } 350 351 // limitations: 352 // - no support for tuple structs and tuple variant (wontfix). 353 // - no support for multiple trait/lifetime bounds. 354 // - no support for `Self` in where clauses. (wontfix) 355 // - no support for overlapping lifetime names. (wontfix) 356 // - no interoperability with other field attributes. 357 // - no useful error messages. (wontfix) 358 // etc... 359 360 #[doc(hidden)] 361 #[macro_export] 362 macro_rules! __pin_project_expand { 363 ( 364 [$($proj_mut_ident:ident)?] 365 [$($proj_ref_ident:ident)?] 366 [$($proj_replace_ident:ident)?] 367 [$($proj_not_unpin_mark:ident)?] 368 [$proj_vis:vis] 369 [$(#[$attrs:meta])* $vis:vis $struct_ty_ident:ident $ident:ident] 370 [$($def_generics:tt)*] 371 [$($impl_generics:tt)*] [$($ty_generics:tt)*] [$(where $($where_clause:tt)*)?] 372 { 373 $($body_data:tt)* 374 } 375 $($(#[$drop_impl_attrs:meta])* impl $($pinned_drop:tt)*)? 376 ) => { 377 $crate::__pin_project_reconstruct! { 378 [$(#[$attrs])* $vis $struct_ty_ident $ident] 379 [$($def_generics)*] [$($impl_generics)*] 380 [$($ty_generics)*] [$(where $($where_clause)*)?] 381 { 382 $($body_data)* 383 } 384 } 385 386 $crate::__pin_project_make_proj_ty! { 387 [$($proj_mut_ident)?] 388 [$proj_vis $struct_ty_ident $ident] 389 [__pin_project_make_proj_field_mut] 390 [$($impl_generics)*] [$($ty_generics)*] [$(where $($where_clause)*)?] 391 { 392 $($body_data)* 393 } 394 } 395 $crate::__pin_project_make_proj_ty! { 396 [$($proj_ref_ident)?] 397 [$proj_vis $struct_ty_ident $ident] 398 [__pin_project_make_proj_field_ref] 399 [$($impl_generics)*] [$($ty_generics)*] [$(where $($where_clause)*)?] 400 { 401 $($body_data)* 402 } 403 } 404 $crate::__pin_project_make_proj_replace_ty! { 405 [$($proj_replace_ident)?] 406 [$proj_vis $struct_ty_ident] 407 [__pin_project_make_proj_field_replace] 408 [$($impl_generics)*] [$($ty_generics)*] [$(where $($where_clause)*)?] 409 { 410 $($body_data)* 411 } 412 } 413 414 $crate::__pin_project_constant! { 415 [$(#[$attrs])* $vis $struct_ty_ident $ident] 416 [$($proj_mut_ident)?] [$($proj_ref_ident)?] [$($proj_replace_ident)?] 417 [$($proj_not_unpin_mark)?] 418 [$proj_vis] 419 [$($def_generics)*] [$($impl_generics)*] 420 [$($ty_generics)*] [$(where $($where_clause)*)?] 421 { 422 $($body_data)* 423 } 424 $($(#[$drop_impl_attrs])* impl $($pinned_drop)*)? 425 } 426 }; 427 } 428 429 #[doc(hidden)] 430 #[macro_export] 431 macro_rules! __pin_project_constant { 432 ( 433 [$(#[$attrs:meta])* $vis:vis struct $ident:ident] 434 [$($proj_mut_ident:ident)?] [$($proj_ref_ident:ident)?] [$($proj_replace_ident:ident)?] 435 [$($proj_not_unpin_mark:ident)?] 436 [$proj_vis:vis] 437 [$($def_generics:tt)*] 438 [$($impl_generics:tt)*] [$($ty_generics:tt)*] [$(where $($where_clause:tt)*)?] 439 { 440 $( 441 $(#[$pin:ident])? 442 $field_vis:vis $field:ident: $field_ty:ty 443 ),+ $(,)? 444 } 445 $($(#[$drop_impl_attrs:meta])* impl $($pinned_drop:tt)*)? 446 ) => { 447 #[allow(explicit_outlives_requirements)] // https://github.com/rust-lang/rust/issues/60993 448 #[allow(single_use_lifetimes)] // https://github.com/rust-lang/rust/issues/55058 449 // This lint warns of `clippy::*` generated by external macros. 450 // We allow this lint for compatibility with older compilers. 451 #[allow(clippy::unknown_clippy_lints)] 452 #[allow(clippy::redundant_pub_crate)] // This lint warns `pub(crate)` field in private struct. 453 #[allow(clippy::used_underscore_binding)] 454 const _: () = { 455 $crate::__pin_project_make_proj_ty! { 456 [$($proj_mut_ident)? Projection] 457 [$proj_vis struct $ident] 458 [__pin_project_make_proj_field_mut] 459 [$($impl_generics)*] [$($ty_generics)*] [$(where $($where_clause)*)?] 460 { 461 $( 462 $(#[$pin])? 463 $field_vis $field: $field_ty 464 ),+ 465 } 466 } 467 $crate::__pin_project_make_proj_ty! { 468 [$($proj_ref_ident)? ProjectionRef] 469 [$proj_vis struct $ident] 470 [__pin_project_make_proj_field_ref] 471 [$($impl_generics)*] [$($ty_generics)*] [$(where $($where_clause)*)?] 472 { 473 $( 474 $(#[$pin])? 475 $field_vis $field: $field_ty 476 ),+ 477 } 478 } 479 480 impl <$($impl_generics)*> $ident <$($ty_generics)*> 481 $(where 482 $($where_clause)*)? 483 { 484 $crate::__pin_project_struct_make_proj_method! { 485 [$($proj_mut_ident)? Projection] 486 [$proj_vis] 487 [project get_unchecked_mut mut] 488 [$($ty_generics)*] 489 { 490 $( 491 $(#[$pin])? 492 $field_vis $field 493 ),+ 494 } 495 } 496 $crate::__pin_project_struct_make_proj_method! { 497 [$($proj_ref_ident)? ProjectionRef] 498 [$proj_vis] 499 [project_ref get_ref] 500 [$($ty_generics)*] 501 { 502 $( 503 $(#[$pin])? 504 $field_vis $field 505 ),+ 506 } 507 } 508 $crate::__pin_project_struct_make_proj_replace_method! { 509 [$($proj_replace_ident)?] 510 [$proj_vis] 511 [ProjectionReplace] 512 [$($ty_generics)*] 513 { 514 $( 515 $(#[$pin])? 516 $field_vis $field 517 ),+ 518 } 519 } 520 } 521 522 $crate::__pin_project_make_unpin_impl! { 523 [$($proj_not_unpin_mark)?] 524 [$vis $ident] 525 [$($impl_generics)*] [$($ty_generics)*] [$(where $($where_clause)*)?] 526 $( 527 $field: $crate::__pin_project_make_unpin_bound!( 528 $(#[$pin])? $field_ty 529 ) 530 ),+ 531 } 532 533 $crate::__pin_project_make_drop_impl! { 534 [$ident] 535 [$($impl_generics)*] [$($ty_generics)*] [$(where $($where_clause)*)?] 536 $($(#[$drop_impl_attrs])* impl $($pinned_drop)*)? 537 } 538 539 // Ensure that it's impossible to use pin projections on a #[repr(packed)] struct. 540 // 541 // Taking a reference to a packed field is UB, and applying 542 // `#[forbid(unaligned_references)]` makes sure that doing this is a hard error. 543 // 544 // If the struct ends up having #[repr(packed)] applied somehow, 545 // this will generate an (unfriendly) error message. Under all reasonable 546 // circumstances, we'll detect the #[repr(packed)] attribute, and generate 547 // a much nicer error above. 548 // 549 // See https://github.com/taiki-e/pin-project/pull/34 for more details. 550 // 551 // Note: 552 // - Lint-based tricks aren't perfect, but they're much better than nothing: 553 // https://github.com/taiki-e/pin-project-lite/issues/26 554 // 555 // - Enable both unaligned_references and safe_packed_borrows lints 556 // because unaligned_references lint does not exist in older compilers: 557 // https://github.com/taiki-e/pin-project-lite/pull/55 558 // https://github.com/rust-lang/rust/pull/82525 559 #[forbid(unaligned_references, safe_packed_borrows)] 560 fn __assert_not_repr_packed <$($impl_generics)*> (this: &$ident <$($ty_generics)*>) 561 $(where 562 $($where_clause)*)? 563 { 564 $( 565 let _ = &this.$field; 566 )+ 567 } 568 }; 569 }; 570 ( 571 [$(#[$attrs:meta])* $vis:vis enum $ident:ident] 572 [$($proj_mut_ident:ident)?] [$($proj_ref_ident:ident)?] [$($proj_replace_ident:ident)?] 573 [$($proj_not_unpin_mark:ident)?] 574 [$proj_vis:vis] 575 [$($def_generics:tt)*] 576 [$($impl_generics:tt)*] [$($ty_generics:tt)*] [$(where $($where_clause:tt)*)?] 577 { 578 $( 579 $(#[$variant_attrs:meta])* 580 $variant:ident $({ 581 $( 582 $(#[$pin:ident])? 583 $field:ident: $field_ty:ty 584 ),+ $(,)? 585 })? 586 ),+ $(,)? 587 } 588 $($(#[$drop_impl_attrs:meta])* impl $($pinned_drop:tt)*)? 589 ) => { 590 #[allow(single_use_lifetimes)] // https://github.com/rust-lang/rust/issues/55058 591 // This lint warns of `clippy::*` generated by external macros. 592 // We allow this lint for compatibility with older compilers. 593 #[allow(clippy::unknown_clippy_lints)] 594 #[allow(clippy::used_underscore_binding)] 595 const _: () = { 596 impl <$($impl_generics)*> $ident <$($ty_generics)*> 597 $(where 598 $($where_clause)*)? 599 { 600 $crate::__pin_project_enum_make_proj_method! { 601 [$($proj_mut_ident)?] 602 [$proj_vis] 603 [project get_unchecked_mut mut] 604 [$($ty_generics)*] 605 { 606 $( 607 $variant $({ 608 $( 609 $(#[$pin])? 610 $field 611 ),+ 612 })? 613 ),+ 614 } 615 } 616 $crate::__pin_project_enum_make_proj_method! { 617 [$($proj_ref_ident)?] 618 [$proj_vis] 619 [project_ref get_ref] 620 [$($ty_generics)*] 621 { 622 $( 623 $variant $({ 624 $( 625 $(#[$pin])? 626 $field 627 ),+ 628 })? 629 ),+ 630 } 631 } 632 $crate::__pin_project_enum_make_proj_replace_method! { 633 [$($proj_replace_ident)?] 634 [$proj_vis] 635 [$($ty_generics)*] 636 { 637 $( 638 $variant $({ 639 $( 640 $(#[$pin])? 641 $field 642 ),+ 643 })? 644 ),+ 645 } 646 } 647 } 648 649 $crate::__pin_project_make_unpin_impl! { 650 [$($proj_not_unpin_mark)?] 651 [$vis $ident] 652 [$($impl_generics)*] [$($ty_generics)*] [$(where $($where_clause)*)?] 653 $( 654 $variant: ($( 655 $( 656 $crate::__pin_project_make_unpin_bound!( 657 $(#[$pin])? $field_ty 658 ) 659 ),+ 660 )?) 661 ),+ 662 } 663 664 $crate::__pin_project_make_drop_impl! { 665 [$ident] 666 [$($impl_generics)*] [$($ty_generics)*] [$(where $($where_clause)*)?] 667 $($(#[$drop_impl_attrs])* impl $($pinned_drop)*)? 668 } 669 670 // We don't need to check for '#[repr(packed)]', 671 // since it does not apply to enums. 672 }; 673 }; 674 } 675 676 #[doc(hidden)] 677 #[macro_export] 678 macro_rules! __pin_project_reconstruct { 679 ( 680 [$(#[$attrs:meta])* $vis:vis struct $ident:ident] 681 [$($def_generics:tt)*] [$($impl_generics:tt)*] 682 [$($ty_generics:tt)*] [$(where $($where_clause:tt)*)?] 683 { 684 $( 685 $(#[$pin:ident])? 686 $field_vis:vis $field:ident: $field_ty:ty 687 ),+ $(,)? 688 } 689 ) => { 690 $(#[$attrs])* 691 $vis struct $ident $($def_generics)* 692 $(where 693 $($where_clause)*)? 694 { 695 $( 696 $field_vis $field: $field_ty 697 ),+ 698 } 699 }; 700 ( 701 [$(#[$attrs:meta])* $vis:vis enum $ident:ident] 702 [$($def_generics:tt)*] [$($impl_generics:tt)*] 703 [$($ty_generics:tt)*] [$(where $($where_clause:tt)*)?] 704 { 705 $( 706 $(#[$variant_attrs:meta])* 707 $variant:ident $({ 708 $( 709 $(#[$pin:ident])? 710 $field:ident: $field_ty:ty 711 ),+ $(,)? 712 })? 713 ),+ $(,)? 714 } 715 ) => { 716 $(#[$attrs])* 717 $vis enum $ident $($def_generics)* 718 $(where 719 $($where_clause)*)? 720 { 721 $( 722 $(#[$variant_attrs])* 723 $variant $({ 724 $( 725 $field: $field_ty 726 ),+ 727 })? 728 ),+ 729 } 730 }; 731 } 732 733 #[doc(hidden)] 734 #[macro_export] 735 macro_rules! __pin_project_make_proj_ty { 736 ([] $($field:tt)*) => {}; 737 ( 738 [$proj_ty_ident:ident $default_ident:ident] 739 [$proj_vis:vis struct $ident:ident] 740 $($field:tt)* 741 ) => {}; 742 ( 743 [$proj_ty_ident:ident] 744 [$proj_vis:vis struct $ident:ident] 745 [$__pin_project_make_proj_field:ident] 746 [$($impl_generics:tt)*] [$($ty_generics:tt)*] [$(where $($where_clause:tt)*)?] 747 { 748 $( 749 $(#[$pin:ident])? 750 $field_vis:vis $field:ident: $field_ty:ty 751 ),+ $(,)? 752 } 753 ) => { 754 $crate::__pin_project_make_proj_ty_body! { 755 [$proj_ty_ident] 756 [$proj_vis struct $ident] 757 [$($impl_generics)*] [$($ty_generics)*] [$(where $($where_clause)*)?] 758 [ 759 $( 760 $field_vis $field: $crate::$__pin_project_make_proj_field!( 761 $(#[$pin])? $field_ty 762 ) 763 ),+ 764 ] 765 } 766 }; 767 ( 768 [$proj_ty_ident:ident] 769 [$proj_vis:vis enum $ident:ident] 770 [$__pin_project_make_proj_field:ident] 771 [$($impl_generics:tt)*] [$($ty_generics:tt)*] [$(where $($where_clause:tt)*)?] 772 { 773 $( 774 $(#[$variant_attrs:meta])* 775 $variant:ident $({ 776 $( 777 $(#[$pin:ident])? 778 $field:ident: $field_ty:ty 779 ),+ $(,)? 780 })? 781 ),+ $(,)? 782 } 783 ) => { 784 $crate::__pin_project_make_proj_ty_body! { 785 [$proj_ty_ident] 786 [$proj_vis enum $ident] 787 [$($impl_generics)*] [$($ty_generics)*] [$(where $($where_clause)*)?] 788 [ 789 $( 790 $variant $({ 791 $( 792 $field: $crate::$__pin_project_make_proj_field!( 793 $(#[$pin])? $field_ty 794 ) 795 ),+ 796 })? 797 ),+ 798 ] 799 } 800 }; 801 } 802 803 #[doc(hidden)] 804 #[macro_export] 805 macro_rules! __pin_project_make_proj_ty_body { 806 ( 807 [$proj_ty_ident:ident] 808 [$proj_vis:vis $struct_ty_ident:ident $ident:ident] 809 [$($impl_generics:tt)*] [$($ty_generics:tt)*] [$(where $($where_clause:tt)*)?] 810 [$($body_data:tt)+] 811 ) => { 812 #[doc(hidden)] // Workaround for rustc bug: see https://github.com/taiki-e/pin-project-lite/issues/77#issuecomment-1671540180 for more. 813 #[allow(dead_code)] // This lint warns unused fields/variants. 814 #[allow(single_use_lifetimes)] // https://github.com/rust-lang/rust/issues/55058 815 // This lint warns of `clippy::*` generated by external macros. 816 // We allow this lint for compatibility with older compilers. 817 #[allow(clippy::unknown_clippy_lints)] 818 #[allow(clippy::mut_mut)] // This lint warns `&mut &mut <ty>`. (only needed for project) 819 #[allow(clippy::redundant_pub_crate)] // This lint warns `pub(crate)` field in private struct. 820 #[allow(clippy::ref_option_ref)] // This lint warns `&Option<&<ty>>`. (only needed for project_ref) 821 #[allow(clippy::type_repetition_in_bounds)] // https://github.com/rust-lang/rust-clippy/issues/4326 822 $proj_vis $struct_ty_ident $proj_ty_ident <'__pin, $($impl_generics)*> 823 where 824 $ident <$($ty_generics)*>: '__pin 825 $(, $($where_clause)*)? 826 { 827 $($body_data)+ 828 } 829 }; 830 } 831 832 #[doc(hidden)] 833 #[macro_export] 834 macro_rules! __pin_project_make_proj_replace_ty { 835 ([] $($field:tt)*) => {}; 836 ( 837 [$proj_ty_ident:ident] 838 [$proj_vis:vis struct] 839 [$__pin_project_make_proj_field:ident] 840 [$($impl_generics:tt)*] [$($ty_generics:tt)*] [$(where $($where_clause:tt)*)?] 841 { 842 $( 843 $(#[$pin:ident])? 844 $field_vis:vis $field:ident: $field_ty:ty 845 ),+ $(,)? 846 } 847 ) => { 848 $crate::__pin_project_make_proj_replace_ty_body! { 849 [$proj_ty_ident] 850 [$proj_vis struct] 851 [$($impl_generics)*] [$($ty_generics)*] [$(where $($where_clause)*)?] 852 [ 853 $( 854 $field_vis $field: $crate::$__pin_project_make_proj_field!( 855 $(#[$pin])? $field_ty 856 ) 857 ),+ 858 ] 859 } 860 }; 861 ( 862 [$proj_ty_ident:ident] 863 [$proj_vis:vis enum] 864 [$__pin_project_make_proj_field:ident] 865 [$($impl_generics:tt)*] [$($ty_generics:tt)*] [$(where $($where_clause:tt)*)?] 866 { 867 $( 868 $(#[$variant_attrs:meta])* 869 $variant:ident $({ 870 $( 871 $(#[$pin:ident])? 872 $field:ident: $field_ty:ty 873 ),+ $(,)? 874 })? 875 ),+ $(,)? 876 } 877 ) => { 878 $crate::__pin_project_make_proj_replace_ty_body! { 879 [$proj_ty_ident] 880 [$proj_vis enum] 881 [$($impl_generics)*] [$($ty_generics)*] [$(where $($where_clause)*)?] 882 [ 883 $( 884 $variant $({ 885 $( 886 $field: $crate::$__pin_project_make_proj_field!( 887 $(#[$pin])? $field_ty 888 ) 889 ),+ 890 })? 891 ),+ 892 ] 893 } 894 }; 895 } 896 897 #[doc(hidden)] 898 #[macro_export] 899 macro_rules! __pin_project_make_proj_replace_ty_body { 900 ( 901 [$proj_ty_ident:ident] 902 [$proj_vis:vis $struct_ty_ident:ident] 903 [$($impl_generics:tt)*] [$($ty_generics:tt)*] [$(where $($where_clause:tt)*)?] 904 [$($body_data:tt)+] 905 ) => { 906 #[doc(hidden)] // Workaround for rustc bug: see https://github.com/taiki-e/pin-project-lite/issues/77#issuecomment-1671540180 for more. 907 #[allow(dead_code)] // This lint warns unused fields/variants. 908 #[allow(single_use_lifetimes)] // https://github.com/rust-lang/rust/issues/55058 909 #[allow(clippy::mut_mut)] // This lint warns `&mut &mut <ty>`. (only needed for project) 910 #[allow(clippy::redundant_pub_crate)] // This lint warns `pub(crate)` field in private struct. 911 #[allow(clippy::type_repetition_in_bounds)] // https://github.com/rust-lang/rust-clippy/issues/4326 912 $proj_vis $struct_ty_ident $proj_ty_ident <$($impl_generics)*> 913 where 914 $($($where_clause)*)? 915 { 916 $($body_data)+ 917 } 918 }; 919 } 920 921 #[doc(hidden)] 922 #[macro_export] 923 macro_rules! __pin_project_make_proj_replace_block { 924 ( 925 [$($proj_path:tt)+] 926 { 927 $( 928 $(#[$pin:ident])? 929 $field_vis:vis $field:ident 930 ),+ 931 } 932 ) => { 933 let result = $($proj_path)* { 934 $( 935 $field: $crate::__pin_project_make_replace_field_proj!( 936 $(#[$pin])? $field 937 ) 938 ),+ 939 }; 940 941 { 942 ( $( 943 $crate::__pin_project_make_unsafe_drop_in_place_guard!( 944 $(#[$pin])? $field 945 ), 946 )* ); 947 } 948 949 result 950 }; 951 ([$($proj_path:tt)+]) => { $($proj_path)* }; 952 } 953 954 #[doc(hidden)] 955 #[macro_export] 956 macro_rules! __pin_project_struct_make_proj_method { 957 ([] $($variant:tt)*) => {}; 958 ( 959 [$proj_ty_ident:ident $_ignored_default_arg:ident] 960 [$proj_vis:vis] 961 [$method_ident:ident $get_method:ident $($mut:ident)?] 962 [$($ty_generics:tt)*] 963 $($variant:tt)* 964 ) => { 965 $crate::__pin_project_struct_make_proj_method! { 966 [$proj_ty_ident] 967 [$proj_vis] 968 [$method_ident $get_method $($mut)?] 969 [$($ty_generics)*] 970 $($variant)* 971 } 972 }; 973 ( 974 [$proj_ty_ident:ident] 975 [$proj_vis:vis] 976 [$method_ident:ident $get_method:ident $($mut:ident)?] 977 [$($ty_generics:tt)*] 978 { 979 $( 980 $(#[$pin:ident])? 981 $field_vis:vis $field:ident 982 ),+ 983 } 984 ) => { 985 #[doc(hidden)] // Workaround for rustc bug: see https://github.com/taiki-e/pin-project-lite/issues/77#issuecomment-1671540180 for more. 986 #[inline] 987 $proj_vis fn $method_ident<'__pin>( 988 self: $crate::__private::Pin<&'__pin $($mut)? Self>, 989 ) -> $proj_ty_ident <'__pin, $($ty_generics)*> { 990 unsafe { 991 let Self { $($field),* } = self.$get_method(); 992 $proj_ty_ident { 993 $( 994 $field: $crate::__pin_project_make_unsafe_field_proj!( 995 $(#[$pin])? $field 996 ) 997 ),+ 998 } 999 } 1000 } 1001 }; 1002 } 1003 1004 #[doc(hidden)] 1005 #[macro_export] 1006 macro_rules! __pin_project_struct_make_proj_replace_method { 1007 ([] $($field:tt)*) => {}; 1008 ( 1009 [$proj_ty_ident:ident] 1010 [$proj_vis:vis] 1011 [$_proj_ty_ident:ident] 1012 [$($ty_generics:tt)*] 1013 { 1014 $( 1015 $(#[$pin:ident])? 1016 $field_vis:vis $field:ident 1017 ),+ 1018 } 1019 ) => { 1020 #[doc(hidden)] // Workaround for rustc bug: see https://github.com/taiki-e/pin-project-lite/issues/77#issuecomment-1671540180 for more. 1021 #[inline] 1022 $proj_vis fn project_replace( 1023 self: $crate::__private::Pin<&mut Self>, 1024 replacement: Self, 1025 ) -> $proj_ty_ident <$($ty_generics)*> { 1026 unsafe { 1027 let __self_ptr: *mut Self = self.get_unchecked_mut(); 1028 1029 // Destructors will run in reverse order, so next create a guard to overwrite 1030 // `self` with the replacement value without calling destructors. 1031 let __guard = $crate::__private::UnsafeOverwriteGuard::new(__self_ptr, replacement); 1032 1033 let Self { $($field),* } = &mut *__self_ptr; 1034 1035 $crate::__pin_project_make_proj_replace_block! { 1036 [$proj_ty_ident] 1037 { 1038 $( 1039 $(#[$pin])? 1040 $field 1041 ),+ 1042 } 1043 } 1044 } 1045 } 1046 }; 1047 } 1048 1049 #[doc(hidden)] 1050 #[macro_export] 1051 macro_rules! __pin_project_enum_make_proj_method { 1052 ([] $($variant:tt)*) => {}; 1053 ( 1054 [$proj_ty_ident:ident] 1055 [$proj_vis:vis] 1056 [$method_ident:ident $get_method:ident $($mut:ident)?] 1057 [$($ty_generics:tt)*] 1058 { 1059 $( 1060 $variant:ident $({ 1061 $( 1062 $(#[$pin:ident])? 1063 $field:ident 1064 ),+ 1065 })? 1066 ),+ 1067 } 1068 ) => { 1069 #[doc(hidden)] // Workaround for rustc bug: see https://github.com/taiki-e/pin-project-lite/issues/77#issuecomment-1671540180 for more. 1070 #[inline] 1071 $proj_vis fn $method_ident<'__pin>( 1072 self: $crate::__private::Pin<&'__pin $($mut)? Self>, 1073 ) -> $proj_ty_ident <'__pin, $($ty_generics)*> { 1074 unsafe { 1075 match self.$get_method() { 1076 $( 1077 Self::$variant $({ 1078 $($field),+ 1079 })? => { 1080 $proj_ty_ident::$variant $({ 1081 $( 1082 $field: $crate::__pin_project_make_unsafe_field_proj!( 1083 $(#[$pin])? $field 1084 ) 1085 ),+ 1086 })? 1087 } 1088 ),+ 1089 } 1090 } 1091 } 1092 }; 1093 } 1094 1095 #[doc(hidden)] 1096 #[macro_export] 1097 macro_rules! __pin_project_enum_make_proj_replace_method { 1098 ([] $($field:tt)*) => {}; 1099 ( 1100 [$proj_ty_ident:ident] 1101 [$proj_vis:vis] 1102 [$($ty_generics:tt)*] 1103 { 1104 $( 1105 $variant:ident $({ 1106 $( 1107 $(#[$pin:ident])? 1108 $field:ident 1109 ),+ 1110 })? 1111 ),+ 1112 } 1113 ) => { 1114 #[doc(hidden)] // Workaround for rustc bug: see https://github.com/taiki-e/pin-project-lite/issues/77#issuecomment-1671540180 for more. 1115 #[inline] 1116 $proj_vis fn project_replace( 1117 self: $crate::__private::Pin<&mut Self>, 1118 replacement: Self, 1119 ) -> $proj_ty_ident <$($ty_generics)*> { 1120 unsafe { 1121 let __self_ptr: *mut Self = self.get_unchecked_mut(); 1122 1123 // Destructors will run in reverse order, so next create a guard to overwrite 1124 // `self` with the replacement value without calling destructors. 1125 let __guard = $crate::__private::UnsafeOverwriteGuard::new(__self_ptr, replacement); 1126 1127 match &mut *__self_ptr { 1128 $( 1129 Self::$variant $({ 1130 $($field),+ 1131 })? => { 1132 $crate::__pin_project_make_proj_replace_block! { 1133 [$proj_ty_ident :: $variant] 1134 $({ 1135 $( 1136 $(#[$pin])? 1137 $field 1138 ),+ 1139 })? 1140 } 1141 } 1142 ),+ 1143 } 1144 } 1145 } 1146 }; 1147 } 1148 1149 #[doc(hidden)] 1150 #[macro_export] 1151 macro_rules! __pin_project_make_unpin_impl { 1152 ( 1153 [] 1154 [$vis:vis $ident:ident] 1155 [$($impl_generics:tt)*] [$($ty_generics:tt)*] [$(where $($where_clause:tt)*)?] 1156 $($field:tt)* 1157 ) => { 1158 // Automatically create the appropriate conditional `Unpin` implementation. 1159 // 1160 // Basically this is equivalent to the following code: 1161 // ```rust 1162 // impl<T, U> Unpin for Struct<T, U> where T: Unpin {} 1163 // ``` 1164 // 1165 // However, if struct is public and there is a private type field, 1166 // this would cause an E0446 (private type in public interface). 1167 // 1168 // When RFC 2145 is implemented (rust-lang/rust#48054), 1169 // this will become a lint, rather then a hard error. 1170 // 1171 // As a workaround for this, we generate a new struct, containing all of the pinned 1172 // fields from our #[pin_project] type. This struct is declared within 1173 // a function, which makes it impossible to be named by user code. 1174 // This guarantees that it will use the default auto-trait impl for Unpin - 1175 // that is, it will implement Unpin iff all of its fields implement Unpin. 1176 // This type can be safely declared as 'public', satisfying the privacy 1177 // checker without actually allowing user code to access it. 1178 // 1179 // This allows users to apply the #[pin_project] attribute to types 1180 // regardless of the privacy of the types of their fields. 1181 // 1182 // See also https://github.com/taiki-e/pin-project/pull/53. 1183 #[allow(non_snake_case)] 1184 $vis struct __Origin <'__pin, $($impl_generics)*> 1185 $(where 1186 $($where_clause)*)? 1187 { 1188 __dummy_lifetime: $crate::__private::PhantomData<&'__pin ()>, 1189 $($field)* 1190 } 1191 impl <'__pin, $($impl_generics)*> $crate::__private::Unpin for $ident <$($ty_generics)*> 1192 where 1193 __Origin <'__pin, $($ty_generics)*>: $crate::__private::Unpin 1194 $(, $($where_clause)*)? 1195 { 1196 } 1197 }; 1198 ( 1199 [$proj_not_unpin_mark:ident] 1200 [$vis:vis $ident:ident] 1201 [$($impl_generics:tt)*] [$($ty_generics:tt)*] [$(where $($where_clause:tt)*)?] 1202 $($field:tt)* 1203 ) => { 1204 #[doc(hidden)] 1205 impl <'__pin, $($impl_generics)*> $crate::__private::Unpin for $ident <$($ty_generics)*> 1206 where 1207 ( 1208 ::core::marker::PhantomData<&'__pin ()>, 1209 ::core::marker::PhantomPinned, 1210 ): $crate::__private::Unpin 1211 $(, $($where_clause)*)? 1212 { 1213 } 1214 } 1215 } 1216 1217 #[doc(hidden)] 1218 #[macro_export] 1219 macro_rules! __pin_project_make_drop_impl { 1220 ( 1221 [$_ident:ident] 1222 [$($_impl_generics:tt)*] [$($_ty_generics:tt)*] [$(where $($_where_clause:tt)*)?] 1223 $(#[$drop_impl_attrs:meta])* 1224 impl $(< 1225 $( $lifetime:lifetime $(: $lifetime_bound:lifetime)? ),* $(,)? 1226 $( $generics:ident 1227 $(: $generics_bound:path)? 1228 $(: ?$generics_unsized_bound:path)? 1229 $(: $generics_lifetime_bound:lifetime)? 1230 ),* 1231 >)? PinnedDrop for $self_ty:ty 1232 $(where 1233 $( $where_clause_ty:ty 1234 $(: $where_clause_bound:path)? 1235 $(: ?$where_clause_unsized_bound:path)? 1236 $(: $where_clause_lifetime_bound:lifetime)? 1237 ),* $(,)? 1238 )? 1239 { 1240 $(#[$drop_fn_attrs:meta])* 1241 fn drop($($arg:ident)+: Pin<&mut Self>) { 1242 $($tt:tt)* 1243 } 1244 } 1245 ) => { 1246 $(#[$drop_impl_attrs])* 1247 impl $(< 1248 $( $lifetime $(: $lifetime_bound)? ,)* 1249 $( $generics 1250 $(: $generics_bound)? 1251 $(: ?$generics_unsized_bound)? 1252 $(: $generics_lifetime_bound)? 1253 ),* 1254 >)? $crate::__private::Drop for $self_ty 1255 $(where 1256 $( $where_clause_ty 1257 $(: $where_clause_bound)? 1258 $(: ?$where_clause_unsized_bound)? 1259 $(: $where_clause_lifetime_bound)? 1260 ),* 1261 )? 1262 { 1263 $(#[$drop_fn_attrs])* 1264 fn drop(&mut self) { 1265 // Implementing `__DropInner::__drop_inner` is safe, but calling it is not safe. 1266 // This is because destructors can be called multiple times in safe code and 1267 // [double dropping is unsound](https://github.com/rust-lang/rust/pull/62360). 1268 // 1269 // `__drop_inner` is defined as a safe method, but this is fine since 1270 // `__drop_inner` is not accessible by the users and we call `__drop_inner` only 1271 // once. 1272 // 1273 // Users can implement [`Drop`] safely using `pin_project!` and can drop a 1274 // type that implements `PinnedDrop` using the [`drop`] function safely. 1275 fn __drop_inner $(< 1276 $( $lifetime $(: $lifetime_bound)? ,)* 1277 $( $generics 1278 $(: $generics_bound)? 1279 $(: ?$generics_unsized_bound)? 1280 $(: $generics_lifetime_bound)? 1281 ),* 1282 >)? ( 1283 $($arg)+: $crate::__private::Pin<&mut $self_ty>, 1284 ) 1285 $(where 1286 $( $where_clause_ty 1287 $(: $where_clause_bound)? 1288 $(: ?$where_clause_unsized_bound)? 1289 $(: $where_clause_lifetime_bound)? 1290 ),* 1291 )? 1292 { 1293 // A dummy `__drop_inner` function to prevent users call outer `__drop_inner`. 1294 fn __drop_inner() {} 1295 $($tt)* 1296 } 1297 1298 // Safety - we're in 'drop', so we know that 'self' will 1299 // never move again. 1300 let pinned_self: $crate::__private::Pin<&mut Self> 1301 = unsafe { $crate::__private::Pin::new_unchecked(self) }; 1302 // We call `__drop_inner` only once. Since `__DropInner::__drop_inner` 1303 // is not accessible by the users, it is never called again. 1304 __drop_inner(pinned_self); 1305 } 1306 } 1307 }; 1308 ( 1309 [$ident:ident] 1310 [$($impl_generics:tt)*] [$($ty_generics:tt)*] [$(where $($where_clause:tt)*)?] 1311 ) => { 1312 // Ensure that struct does not implement `Drop`. 1313 // 1314 // There are two possible cases: 1315 // 1. The user type does not implement Drop. In this case, 1316 // the first blanked impl will not apply to it. This code 1317 // will compile, as there is only one impl of MustNotImplDrop for the user type 1318 // 2. The user type does impl Drop. This will make the blanket impl applicable, 1319 // which will then conflict with the explicit MustNotImplDrop impl below. 1320 // This will result in a compilation error, which is exactly what we want. 1321 trait MustNotImplDrop {} 1322 #[allow(clippy::drop_bounds, drop_bounds)] 1323 impl<T: $crate::__private::Drop> MustNotImplDrop for T {} 1324 impl <$($impl_generics)*> MustNotImplDrop for $ident <$($ty_generics)*> 1325 $(where 1326 $($where_clause)*)? 1327 { 1328 } 1329 }; 1330 } 1331 1332 #[doc(hidden)] 1333 #[macro_export] 1334 macro_rules! __pin_project_make_unpin_bound { 1335 (#[pin] $field_ty:ty) => { 1336 $field_ty 1337 }; 1338 ($field_ty:ty) => { 1339 $crate::__private::AlwaysUnpin<$field_ty> 1340 }; 1341 } 1342 1343 #[doc(hidden)] 1344 #[macro_export] 1345 macro_rules! __pin_project_make_unsafe_field_proj { 1346 (#[pin] $field:ident) => { 1347 $crate::__private::Pin::new_unchecked($field) 1348 }; 1349 ($field:ident) => { 1350 $field 1351 }; 1352 } 1353 1354 #[doc(hidden)] 1355 #[macro_export] 1356 macro_rules! __pin_project_make_replace_field_proj { 1357 (#[pin] $field:ident) => { 1358 $crate::__private::PhantomData 1359 }; 1360 ($field:ident) => { 1361 $crate::__private::ptr::read($field) 1362 }; 1363 } 1364 1365 #[doc(hidden)] 1366 #[macro_export] 1367 macro_rules! __pin_project_make_unsafe_drop_in_place_guard { 1368 (#[pin] $field:ident) => { 1369 $crate::__private::UnsafeDropInPlaceGuard::new($field) 1370 }; 1371 ($field:ident) => { 1372 () 1373 }; 1374 } 1375 1376 #[doc(hidden)] 1377 #[macro_export] 1378 macro_rules! __pin_project_make_proj_field_mut { 1379 (#[pin] $field_ty:ty) => { 1380 $crate::__private::Pin<&'__pin mut ($field_ty)> 1381 }; 1382 ($field_ty:ty) => { 1383 &'__pin mut ($field_ty) 1384 }; 1385 } 1386 1387 #[doc(hidden)] 1388 #[macro_export] 1389 macro_rules! __pin_project_make_proj_field_ref { 1390 (#[pin] $field_ty:ty) => { 1391 $crate::__private::Pin<&'__pin ($field_ty)> 1392 }; 1393 ($field_ty:ty) => { 1394 &'__pin ($field_ty) 1395 }; 1396 } 1397 1398 #[doc(hidden)] 1399 #[macro_export] 1400 macro_rules! __pin_project_make_proj_field_replace { 1401 (#[pin] $field_ty:ty) => { 1402 $crate::__private::PhantomData<$field_ty> 1403 }; 1404 ($field_ty:ty) => { 1405 $field_ty 1406 }; 1407 } 1408 1409 #[doc(hidden)] 1410 #[macro_export] 1411 macro_rules! __pin_project_internal { 1412 // parsing proj_mut_ident 1413 ( 1414 [] 1415 [$($proj_ref_ident:ident)?] 1416 [$($proj_replace_ident:ident)?] 1417 [$( ! $proj_not_unpin_mark:ident)?] 1418 [$($attrs:tt)*] 1419 1420 #[project = $proj_mut_ident:ident] 1421 $($tt:tt)* 1422 ) => { 1423 $crate::__pin_project_internal! { 1424 [$proj_mut_ident] 1425 [$($proj_ref_ident)?] 1426 [$($proj_replace_ident)?] 1427 [$( ! $proj_not_unpin_mark)?] 1428 [$($attrs)*] 1429 $($tt)* 1430 } 1431 }; 1432 // parsing proj_ref_ident 1433 ( 1434 [$($proj_mut_ident:ident)?] 1435 [] 1436 [$($proj_replace_ident:ident)?] 1437 [$( ! $proj_not_unpin_mark:ident)?] 1438 [$($attrs:tt)*] 1439 1440 #[project_ref = $proj_ref_ident:ident] 1441 $($tt:tt)* 1442 ) => { 1443 $crate::__pin_project_internal! { 1444 [$($proj_mut_ident)?] 1445 [$proj_ref_ident] 1446 [$($proj_replace_ident)?] 1447 [$( ! $proj_not_unpin_mark)?] 1448 [$($attrs)*] 1449 $($tt)* 1450 } 1451 }; 1452 // parsing proj_replace_ident 1453 ( 1454 [$($proj_mut_ident:ident)?] 1455 [$($proj_ref_ident:ident)?] 1456 [] 1457 [$( ! $proj_not_unpin_mark:ident)?] 1458 [$($attrs:tt)*] 1459 1460 #[project_replace = $proj_replace_ident:ident] 1461 $($tt:tt)* 1462 ) => { 1463 $crate::__pin_project_internal! { 1464 [$($proj_mut_ident)?] 1465 [$($proj_ref_ident)?] 1466 [$proj_replace_ident] 1467 [$( ! $proj_not_unpin_mark)?] 1468 [$($attrs)*] 1469 $($tt)* 1470 } 1471 }; 1472 // parsing !Unpin 1473 ( 1474 [$($proj_mut_ident:ident)?] 1475 [$($proj_ref_ident:ident)?] 1476 [$($proj_replace_ident:ident)?] 1477 [] 1478 [$($attrs:tt)*] 1479 1480 #[project( ! $proj_not_unpin_mark:ident)] 1481 $($tt:tt)* 1482 ) => { 1483 $crate::__pin_project_internal! { 1484 [$($proj_mut_ident)?] 1485 [$($proj_ref_ident)?] 1486 [$($proj_replace_ident)?] 1487 [ ! $proj_not_unpin_mark] 1488 [$($attrs)*] 1489 $($tt)* 1490 } 1491 }; 1492 // this is actually part of a recursive step that picks off a single non-`pin_project_lite` attribute 1493 // there could be more to parse 1494 ( 1495 [$($proj_mut_ident:ident)?] 1496 [$($proj_ref_ident:ident)?] 1497 [$($proj_replace_ident:ident)?] 1498 [$( ! $proj_not_unpin_mark:ident)?] 1499 [$($attrs:tt)*] 1500 1501 #[$($attr:tt)*] 1502 $($tt:tt)* 1503 ) => { 1504 $crate::__pin_project_internal! { 1505 [$($proj_mut_ident)?] 1506 [$($proj_ref_ident)?] 1507 [$($proj_replace_ident)?] 1508 [$( ! $proj_not_unpin_mark)?] 1509 [$($attrs)* #[$($attr)*]] 1510 $($tt)* 1511 } 1512 }; 1513 // now determine visibility 1514 // if public, downgrade 1515 ( 1516 [$($proj_mut_ident:ident)?] 1517 [$($proj_ref_ident:ident)?] 1518 [$($proj_replace_ident:ident)?] 1519 [$( ! $proj_not_unpin_mark:ident)?] 1520 [$($attrs:tt)*] 1521 pub $struct_ty_ident:ident $ident:ident 1522 $($tt:tt)* 1523 ) => { 1524 $crate::__pin_project_parse_generics! { 1525 [$($proj_mut_ident)?] 1526 [$($proj_ref_ident)?] 1527 [$($proj_replace_ident)?] 1528 [$($proj_not_unpin_mark)?] 1529 [$($attrs)*] 1530 [pub $struct_ty_ident $ident pub(crate)] 1531 $($tt)* 1532 } 1533 }; 1534 ( 1535 [$($proj_mut_ident:ident)?] 1536 [$($proj_ref_ident:ident)?] 1537 [$($proj_replace_ident:ident)?] 1538 [$( ! $proj_not_unpin_mark:ident)?] 1539 [$($attrs:tt)*] 1540 $vis:vis $struct_ty_ident:ident $ident:ident 1541 $($tt:tt)* 1542 ) => { 1543 $crate::__pin_project_parse_generics! { 1544 [$($proj_mut_ident)?] 1545 [$($proj_ref_ident)?] 1546 [$($proj_replace_ident)?] 1547 [$($proj_not_unpin_mark)?] 1548 [$($attrs)*] 1549 [$vis $struct_ty_ident $ident $vis] 1550 $($tt)* 1551 } 1552 }; 1553 } 1554 1555 #[doc(hidden)] 1556 #[macro_export] 1557 macro_rules! __pin_project_parse_generics { 1558 ( 1559 [$($proj_mut_ident:ident)?] 1560 [$($proj_ref_ident:ident)?] 1561 [$($proj_replace_ident:ident)?] 1562 [$($proj_not_unpin_mark:ident)?] 1563 [$($attrs:tt)*] 1564 [$vis:vis $struct_ty_ident:ident $ident:ident $proj_vis:vis] 1565 $(< 1566 $( $lifetime:lifetime $(: $lifetime_bound:lifetime)? ),* $(,)? 1567 $( $generics:ident 1568 $(: $generics_bound:path)? 1569 $(: ?$generics_unsized_bound:path)? 1570 $(: $generics_lifetime_bound:lifetime)? 1571 $(= $generics_default:ty)? 1572 ),* $(,)? 1573 >)? 1574 $(where 1575 $( $where_clause_ty:ty 1576 $(: $where_clause_bound:path)? 1577 $(: ?$where_clause_unsized_bound:path)? 1578 $(: $where_clause_lifetime_bound:lifetime)? 1579 ),* $(,)? 1580 )? 1581 { 1582 $($body_data:tt)* 1583 } 1584 $($(#[$drop_impl_attrs:meta])* impl $($pinned_drop:tt)*)? 1585 ) => { 1586 $crate::__pin_project_expand! { 1587 [$($proj_mut_ident)?] 1588 [$($proj_ref_ident)?] 1589 [$($proj_replace_ident)?] 1590 [$($proj_not_unpin_mark)?] 1591 [$proj_vis] 1592 [$($attrs)* $vis $struct_ty_ident $ident] 1593 [$(< 1594 $( $lifetime $(: $lifetime_bound)? ,)* 1595 $( $generics 1596 $(: $generics_bound)? 1597 $(: ?$generics_unsized_bound)? 1598 $(: $generics_lifetime_bound)? 1599 $(= $generics_default)? 1600 ),* 1601 >)?] 1602 [$( 1603 $( $lifetime $(: $lifetime_bound)? ,)* 1604 $( $generics 1605 $(: $generics_bound)? 1606 $(: ?$generics_unsized_bound)? 1607 $(: $generics_lifetime_bound)? 1608 ),* 1609 )?] 1610 [$( $( $lifetime ,)* $( $generics ),* )?] 1611 [$(where $( $where_clause_ty 1612 $(: $where_clause_bound)? 1613 $(: ?$where_clause_unsized_bound)? 1614 $(: $where_clause_lifetime_bound)? 1615 ),* )?] 1616 { 1617 $($body_data)* 1618 } 1619 $($(#[$drop_impl_attrs])* impl $($pinned_drop)*)? 1620 } 1621 }; 1622 } 1623 1624 #[doc(hidden)] 1625 pub mod __private { 1626 use core::mem::ManuallyDrop; 1627 #[doc(hidden)] 1628 pub use core::{ 1629 marker::{PhantomData, Unpin}, 1630 ops::Drop, 1631 pin::Pin, 1632 ptr, 1633 }; 1634 1635 // This is an internal helper struct used by `pin_project!`. 1636 #[doc(hidden)] 1637 pub struct AlwaysUnpin<T: ?Sized>(PhantomData<T>); 1638 1639 impl<T: ?Sized> Unpin for AlwaysUnpin<T> {} 1640 1641 // This is an internal helper used to ensure a value is dropped. 1642 #[doc(hidden)] 1643 pub struct UnsafeDropInPlaceGuard<T: ?Sized>(*mut T); 1644 1645 impl<T: ?Sized> UnsafeDropInPlaceGuard<T> { 1646 #[doc(hidden)] new(ptr: *mut T) -> Self1647 pub unsafe fn new(ptr: *mut T) -> Self { 1648 Self(ptr) 1649 } 1650 } 1651 1652 impl<T: ?Sized> Drop for UnsafeDropInPlaceGuard<T> { drop(&mut self)1653 fn drop(&mut self) { 1654 // SAFETY: the caller of `UnsafeDropInPlaceGuard::new` must guarantee 1655 // that `ptr` is valid for drop when this guard is destructed. 1656 unsafe { 1657 ptr::drop_in_place(self.0); 1658 } 1659 } 1660 } 1661 1662 // This is an internal helper used to ensure a value is overwritten without 1663 // its destructor being called. 1664 #[doc(hidden)] 1665 pub struct UnsafeOverwriteGuard<T> { 1666 target: *mut T, 1667 value: ManuallyDrop<T>, 1668 } 1669 1670 impl<T> UnsafeOverwriteGuard<T> { 1671 #[doc(hidden)] new(target: *mut T, value: T) -> Self1672 pub unsafe fn new(target: *mut T, value: T) -> Self { 1673 Self { target, value: ManuallyDrop::new(value) } 1674 } 1675 } 1676 1677 impl<T> Drop for UnsafeOverwriteGuard<T> { drop(&mut self)1678 fn drop(&mut self) { 1679 // SAFETY: the caller of `UnsafeOverwriteGuard::new` must guarantee 1680 // that `target` is valid for writes when this guard is destructed. 1681 unsafe { 1682 ptr::write(self.target, ptr::read(&*self.value)); 1683 } 1684 } 1685 } 1686 } 1687