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