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