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## Examples
17
18[`pin_project!`] macro creates a projection type covering all the fields of
19struct.
20
21```rust
22use std::pin::Pin;
23
24use pin_project_lite::pin_project;
25
26pin_project! {
27 struct Struct<T, U> {
28 #[pin]
29 pinned: T,
30 unpinned: U,
31 }
32}
33
34impl<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
43To use [`pin_project!`] on enums, you need to name the projection type
44returned from the method.
45
46```rust
47use std::pin::Pin;
48
49use pin_project_lite::pin_project;
50
51pin_project! {
52 #[project = EnumProj]
53 enum Enum<T, U> {
54 Variant { #[pin] pinned: T, unpinned: U },
55 }
56}
57
58impl<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
72Here are some similarities and differences compared to [pin-project].
73
74### Similar: Safety
75
76pin-project-lite guarantees safety in much the same way as [pin-project].
77Both are completely safe unless you write other unsafe code.
78
79### Different: Minimal design
80
81This 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
87This is the **only** reason to use this crate. However, **if you already
88have proc-macro related dependencies in your crate's dependency graph, there
89is no benefit from using this crate.** (Note: There is almost no difference
90in the amount of code generated between [pin-project] and pin-project-lite.)
91
92### Different: No useful error messages
93
94This macro does not handle any invalid input. So error messages are not to
95be useful in most cases. If you do need useful error messages, then upon
96error you can pass the same input to [pin-project] to receive a helpful
97description of the compile error.
98
99### Different: No support for custom Unpin implementation
100
101pin-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
105pin-project supports this.
106
107[not-unpin]: https://docs.rs/pin-project/latest/pin_project/attr.pin_project.html#unpin
108[pin-project]: https://github.com/taiki-e/pin-project
109[unsafe-unpin]: https://docs.rs/pin-project/latest/pin_project/attr.pin_project.html#unsafeunpin
110
111<!-- tidy:crate-doc:end -->
112
113[not-unpin-lite]: pin_project#unpin
114*/
115
116#![no_std]
117#![doc(test(
118 no_crate_inject,
119 attr(
120 deny(warnings, rust_2018_idioms, single_use_lifetimes),
121 allow(dead_code, unused_variables)
122 )
123))]
124// #![warn(unsafe_op_in_unsafe_fn)] // requires Rust 1.52
125#![warn(
126 // Lints that may help when writing public library.
127 missing_debug_implementations,
128 missing_docs,
129 clippy::alloc_instead_of_core,
130 clippy::exhaustive_enums,
131 clippy::exhaustive_structs,
132 clippy::impl_trait_in_params,
133 // clippy::missing_inline_in_public_items,
134 clippy::std_instead_of_alloc,
135 clippy::std_instead_of_core,
136)]
137
138/// A macro that creates a projection type covering all the fields of struct.
139///
140/// This macro creates a projection type according to the following rules:
141///
142/// - For the field that uses `#[pin]` attribute, makes the pinned reference to the field.
143/// - For the other fields, makes the unpinned reference to the field.
144///
145/// And the following methods are implemented on the original type:
146///
147/// ```
148/// # use std::pin::Pin;
149/// # type Projection<'a> = &'a ();
150/// # type ProjectionRef<'a> = &'a ();
151/// # trait Dox {
152/// fn project(self: Pin<&mut Self>) -> Projection<'_>;
153/// fn project_ref(self: Pin<&Self>) -> ProjectionRef<'_>;
154/// # }
155/// ```
156///
157/// By passing an attribute with the same name as the method to the macro,
158/// you can name the projection type returned from the method. This allows you
159/// to use pattern matching on the projected types.
160///
161/// ```
162/// # use pin_project_lite::pin_project;
163/// # use std::pin::Pin;
164/// pin_project! {
165/// #[project = EnumProj]
166/// enum Enum<T> {
167/// Variant { #[pin] field: T },
168/// }
169/// }
170///
171/// impl<T> Enum<T> {
172/// fn method(self: Pin<&mut Self>) {
173/// let this: EnumProj<'_, T> = self.project();
174/// match this {
175/// EnumProj::Variant { field } => {
176/// let _: Pin<&mut T> = field;
177/// }
178/// }
179/// }
180/// }
181/// ```
182///
183/// By passing the `#[project_replace = MyProjReplace]` attribute you may create an additional
184/// method which allows the contents of `Pin<&mut Self>` to be replaced while simultaneously moving
185/// out all unpinned fields in `Self`.
186///
187/// ```
188/// # use std::pin::Pin;
189/// # type MyProjReplace = ();
190/// # trait Dox {
191/// fn project_replace(self: Pin<&mut Self>, replacement: Self) -> MyProjReplace;
192/// # }
193/// ```
194///
195/// Also, note that the projection types returned by `project` and `project_ref` have
196/// an additional lifetime at the beginning of generics.
197///
198/// ```text
199/// let this: EnumProj<'_, T> = self.project();
200/// ^^
201/// ```
202///
203/// The visibility of the projected types and projection methods is based on the
204/// original type. However, if the visibility of the original type is `pub`, the
205/// visibility of the projected types and the projection methods is downgraded
206/// to `pub(crate)`.
207///
208/// # Safety
209///
210/// `pin_project!` macro guarantees safety in much the same way as [pin-project] crate.
211/// Both are completely safe unless you write other unsafe code.
212///
213/// See [pin-project] crate for more details.
214///
215/// # Examples
216///
217/// ```
218/// use std::pin::Pin;
219///
220/// use pin_project_lite::pin_project;
221///
222/// pin_project! {
223/// struct Struct<T, U> {
224/// #[pin]
225/// pinned: T,
226/// unpinned: U,
227/// }
228/// }
229///
230/// impl<T, U> Struct<T, U> {
231/// fn method(self: Pin<&mut Self>) {
232/// let this = self.project();
233/// let _: Pin<&mut T> = this.pinned; // Pinned reference to the field
234/// let _: &mut U = this.unpinned; // Normal reference to the field
235/// }
236/// }
237/// ```
238///
239/// To use `pin_project!` on enums, you need to name the projection type
240/// returned from the method.
241///
242/// ```
243/// use std::pin::Pin;
244///
245/// use pin_project_lite::pin_project;
246///
247/// pin_project! {
248/// #[project = EnumProj]
249/// enum Enum<T> {
250/// Struct {
251/// #[pin]
252/// field: T,
253/// },
254/// Unit,
255/// }
256/// }
257///
258/// impl<T> Enum<T> {
259/// fn method(self: Pin<&mut Self>) {
260/// match self.project() {
261/// EnumProj::Struct { field } => {
262/// let _: Pin<&mut T> = field;
263/// }
264/// EnumProj::Unit => {}
265/// }
266/// }
267/// }
268/// ```
269///
270/// If you want to call the `project()` method multiple times or later use the
271/// original [`Pin`] type, it needs to use [`.as_mut()`][`Pin::as_mut`] to avoid
272/// consuming the [`Pin`].
273///
274/// ```
275/// use std::pin::Pin;
276///
277/// use pin_project_lite::pin_project;
278///
279/// pin_project! {
280/// struct Struct<T> {
281/// #[pin]
282/// field: T,
283/// }
284/// }
285///
286/// impl<T> Struct<T> {
287/// fn call_project_twice(mut self: Pin<&mut Self>) {
288/// // `project` consumes `self`, so reborrow the `Pin<&mut Self>` via `as_mut`.
289/// self.as_mut().project();
290/// self.as_mut().project();
291/// }
292/// }
293/// ```
294///
295/// # `!Unpin`
296///
297/// If you want to make sure `Unpin` is not implemented, use the `#[project(!Unpin)]`
298/// attribute.
299///
300/// ```
301/// use pin_project_lite::pin_project;
302///
303/// pin_project! {
304/// #[project(!Unpin)]
305/// struct Struct<T> {
306/// #[pin]
307/// field: T,
308/// }
309/// }
310/// ```
311///
312/// This is equivalent to using `#[pin]` attribute for a [`PhantomPinned`] field.
313///
314/// ```
315/// use std::marker::PhantomPinned;
316///
317/// use pin_project_lite::pin_project;
318///
319/// pin_project! {
320/// struct Struct<T> {
321/// field: T,
322/// #[pin]
323/// _pin: PhantomPinned,
324/// }
325/// }
326/// ```
327///
328/// Note that using [`PhantomPinned`] without `#[pin]` or `#[project(!Unpin)]`
329/// attribute has no effect.
330///
331/// # Pinned Drop
332///
333/// In order to correctly implement pin projections, a type’s [`Drop`] impl must not move out of any
334/// structurally pinned fields. Unfortunately, [`Drop::drop`] takes `&mut Self`, not `Pin<&mut
335/// Self>`.
336///
337/// To implement [`Drop`] for type that has pin, add an `impl PinnedDrop` block at the end of the
338/// [`pin_project`] macro block. PinnedDrop has the following interface:
339///
340/// ```rust
341/// # use std::pin::Pin;
342/// trait PinnedDrop {
343/// fn drop(this: Pin<&mut Self>);
344/// }
345/// ```
346///
347/// Note that the argument to `PinnedDrop::drop` cannot be named `self`.
348///
349/// `pin_project!` implements the actual [`Drop`] trait via PinnedDrop you implemented. To
350/// explicitly drop a type that implements PinnedDrop, use the [drop] function just like dropping a
351/// type that directly implements [`Drop`].
352///
353/// `PinnedDrop::drop` will never be called more than once, just like [`Drop::drop`].
354///
355/// ```rust
356/// use pin_project_lite::pin_project;
357///
358/// pin_project! {
359/// pub struct Struct<'a> {
360/// was_dropped: &'a mut bool,
361/// #[pin]
362/// field: u8,
363/// }
364///
365/// impl PinnedDrop for Struct<'_> {
366/// fn drop(this: Pin<&mut Self>) { // <----- NOTE: this is not `self`
367/// **this.project().was_dropped = true;
368/// }
369/// }
370/// }
371///
372/// let mut was_dropped = false;
373/// drop(Struct { was_dropped: &mut was_dropped, field: 42 });
374/// assert!(was_dropped);
375/// ```
376///
377/// [`PhantomPinned`]: core::marker::PhantomPinned
378/// [`Pin::as_mut`]: core::pin::Pin::as_mut
379/// [`Pin`]: core::pin::Pin
380/// [pin-project]: https://github.com/taiki-e/pin-project
381#[macro_export]
382macro_rules! pin_project {
383 ($($tt:tt)*) => {
384 $crate::__pin_project_internal! {
385 [][][][][]
386 $($tt)*
387 }
388 };
389}
390
391// limitations:
392// - no support for tuple structs and tuple variant (wontfix).
393// - no support for multiple trait/lifetime bounds.
394// - no support for `Self` in where clauses. (wontfix)
395// - no support for overlapping lifetime names. (wontfix)
396// - no interoperability with other field attributes.
397// - no useful error messages. (wontfix)
398// etc...
399
400#[doc(hidden)]
401#[macro_export]
402macro_rules! __pin_project_expand {
403 (
404 [$($proj_mut_ident:ident)?]
405 [$($proj_ref_ident:ident)?]
406 [$($proj_replace_ident:ident)?]
407 [$($proj_not_unpin_mark:ident)?]
408 [$proj_vis:vis]
409 [$(#[$attrs:meta])* $vis:vis $struct_ty_ident:ident $ident:ident]
410 [$($def_generics:tt)*]
411 [$($impl_generics:tt)*] [$($ty_generics:tt)*] [$(where $($where_clause:tt)*)?]
412 {
413 $($body_data:tt)*
414 }
415 $($(#[$drop_impl_attrs:meta])* impl $($pinned_drop:tt)*)?
416 ) => {
417 $crate::__pin_project_reconstruct! {
418 [$(#[$attrs])* $vis $struct_ty_ident $ident]
419 [$($def_generics)*] [$($impl_generics)*]
420 [$($ty_generics)*] [$(where $($where_clause)*)?]
421 {
422 $($body_data)*
423 }
424 }
425
426 $crate::__pin_project_make_proj_ty! {
427 [$($proj_mut_ident)?]
428 [$proj_vis $struct_ty_ident $ident]
429 [__pin_project_make_proj_field_mut]
430 [$($impl_generics)*] [$($ty_generics)*] [$(where $($where_clause)*)?]
431 {
432 $($body_data)*
433 }
434 }
435 $crate::__pin_project_make_proj_ty! {
436 [$($proj_ref_ident)?]
437 [$proj_vis $struct_ty_ident $ident]
438 [__pin_project_make_proj_field_ref]
439 [$($impl_generics)*] [$($ty_generics)*] [$(where $($where_clause)*)?]
440 {
441 $($body_data)*
442 }
443 }
444 $crate::__pin_project_make_proj_replace_ty! {
445 [$($proj_replace_ident)?]
446 [$proj_vis $struct_ty_ident]
447 [__pin_project_make_proj_field_replace]
448 [$($impl_generics)*] [$($ty_generics)*] [$(where $($where_clause)*)?]
449 {
450 $($body_data)*
451 }
452 }
453
454 $crate::__pin_project_constant! {
455 [$(#[$attrs])* $vis $struct_ty_ident $ident]
456 [$($proj_mut_ident)?] [$($proj_ref_ident)?] [$($proj_replace_ident)?]
457 [$($proj_not_unpin_mark)?]
458 [$proj_vis]
459 [$($def_generics)*] [$($impl_generics)*]
460 [$($ty_generics)*] [$(where $($where_clause)*)?]
461 {
462 $($body_data)*
463 }
464 $($(#[$drop_impl_attrs])* impl $($pinned_drop)*)?
465 }
466 };
467}
468
469#[doc(hidden)]
470#[macro_export]
471macro_rules! __pin_project_constant {
472 (
473 [$(#[$attrs:meta])* $vis:vis struct $ident:ident]
474 [$($proj_mut_ident:ident)?] [$($proj_ref_ident:ident)?] [$($proj_replace_ident:ident)?]
475 [$($proj_not_unpin_mark:ident)?]
476 [$proj_vis:vis]
477 [$($def_generics:tt)*]
478 [$($impl_generics:tt)*] [$($ty_generics:tt)*] [$(where $($where_clause:tt)*)?]
479 {
480 $(
481 $(#[$pin:ident])?
482 $field_vis:vis $field:ident: $field_ty:ty
483 ),+ $(,)?
484 }
485 $($(#[$drop_impl_attrs:meta])* impl $($pinned_drop:tt)*)?
486 ) => {
487 #[allow(explicit_outlives_requirements)] // https://github.com/rust-lang/rust/issues/60993
488 #[allow(single_use_lifetimes)] // https://github.com/rust-lang/rust/issues/55058
489 // This lint warns of `clippy::*` generated by external macros.
490 // We allow this lint for compatibility with older compilers.
491 #[allow(clippy::unknown_clippy_lints)]
492 #[allow(clippy::redundant_pub_crate)] // This lint warns `pub(crate)` field in private struct.
493 #[allow(clippy::used_underscore_binding)]
494 const _: () = {
495 $crate::__pin_project_make_proj_ty! {
496 [$($proj_mut_ident)? Projection]
497 [$proj_vis struct $ident]
498 [__pin_project_make_proj_field_mut]
499 [$($impl_generics)*] [$($ty_generics)*] [$(where $($where_clause)*)?]
500 {
501 $(
502 $(#[$pin])?
503 $field_vis $field: $field_ty
504 ),+
505 }
506 }
507 $crate::__pin_project_make_proj_ty! {
508 [$($proj_ref_ident)? ProjectionRef]
509 [$proj_vis struct $ident]
510 [__pin_project_make_proj_field_ref]
511 [$($impl_generics)*] [$($ty_generics)*] [$(where $($where_clause)*)?]
512 {
513 $(
514 $(#[$pin])?
515 $field_vis $field: $field_ty
516 ),+
517 }
518 }
519
520 impl <$($impl_generics)*> $ident <$($ty_generics)*>
521 $(where
522 $($where_clause)*)?
523 {
524 $crate::__pin_project_struct_make_proj_method! {
525 [$($proj_mut_ident)? Projection]
526 [$proj_vis]
527 [project get_unchecked_mut mut]
528 [$($ty_generics)*]
529 {
530 $(
531 $(#[$pin])?
532 $field_vis $field
533 ),+
534 }
535 }
536 $crate::__pin_project_struct_make_proj_method! {
537 [$($proj_ref_ident)? ProjectionRef]
538 [$proj_vis]
539 [project_ref get_ref]
540 [$($ty_generics)*]
541 {
542 $(
543 $(#[$pin])?
544 $field_vis $field
545 ),+
546 }
547 }
548 $crate::__pin_project_struct_make_proj_replace_method! {
549 [$($proj_replace_ident)?]
550 [$proj_vis]
551 [ProjectionReplace]
552 [$($ty_generics)*]
553 {
554 $(
555 $(#[$pin])?
556 $field_vis $field
557 ),+
558 }
559 }
560 }
561
562 $crate::__pin_project_make_unpin_impl! {
563 [$($proj_not_unpin_mark)?]
564 [$vis $ident]
565 [$($impl_generics)*] [$($ty_generics)*] [$(where $($where_clause)*)?]
566 $(
567 $field: $crate::__pin_project_make_unpin_bound!(
568 $(#[$pin])? $field_ty
569 )
570 ),+
571 }
572
573 $crate::__pin_project_make_drop_impl! {
574 [$ident]
575 [$($impl_generics)*] [$($ty_generics)*] [$(where $($where_clause)*)?]
576 $($(#[$drop_impl_attrs])* impl $($pinned_drop)*)?
577 }
578
579 // Ensure that it's impossible to use pin projections on a #[repr(packed)] struct.
580 //
581 // Taking a reference to a packed field is UB, and applying
582 // `#[forbid(unaligned_references)]` makes sure that doing this is a hard error.
583 //
584 // If the struct ends up having #[repr(packed)] applied somehow,
585 // this will generate an (unfriendly) error message. Under all reasonable
586 // circumstances, we'll detect the #[repr(packed)] attribute, and generate
587 // a much nicer error above.
588 //
589 // See https://github.com/taiki-e/pin-project/pull/34 for more details.
590 //
591 // Note:
592 // - Lint-based tricks aren't perfect, but they're much better than nothing:
593 // https://github.com/taiki-e/pin-project-lite/issues/26
594 //
595 // - Enable both unaligned_references and safe_packed_borrows lints
596 // because unaligned_references lint does not exist in older compilers:
597 // https://github.com/taiki-e/pin-project-lite/pull/55
598 // https://github.com/rust-lang/rust/pull/82525
599 #[forbid(unaligned_references, safe_packed_borrows)]
600 fn __assert_not_repr_packed <$($impl_generics)*> (this: &$ident <$($ty_generics)*>)
601 $(where
602 $($where_clause)*)?
603 {
604 $(
605 let _ = &this.$field;
606 )+
607 }
608 };
609 };
610 (
611 [$(#[$attrs:meta])* $vis:vis enum $ident:ident]
612 [$($proj_mut_ident:ident)?] [$($proj_ref_ident:ident)?] [$($proj_replace_ident:ident)?]
613 [$($proj_not_unpin_mark:ident)?]
614 [$proj_vis:vis]
615 [$($def_generics:tt)*]
616 [$($impl_generics:tt)*] [$($ty_generics:tt)*] [$(where $($where_clause:tt)*)?]
617 {
618 $(
619 $(#[$variant_attrs:meta])*
620 $variant:ident $({
621 $(
622 $(#[$pin:ident])?
623 $field:ident: $field_ty:ty
624 ),+ $(,)?
625 })?
626 ),+ $(,)?
627 }
628 $($(#[$drop_impl_attrs:meta])* impl $($pinned_drop:tt)*)?
629 ) => {
630 #[allow(single_use_lifetimes)] // https://github.com/rust-lang/rust/issues/55058
631 // This lint warns of `clippy::*` generated by external macros.
632 // We allow this lint for compatibility with older compilers.
633 #[allow(clippy::unknown_clippy_lints)]
634 #[allow(clippy::used_underscore_binding)]
635 const _: () = {
636 impl <$($impl_generics)*> $ident <$($ty_generics)*>
637 $(where
638 $($where_clause)*)?
639 {
640 $crate::__pin_project_enum_make_proj_method! {
641 [$($proj_mut_ident)?]
642 [$proj_vis]
643 [project get_unchecked_mut mut]
644 [$($ty_generics)*]
645 {
646 $(
647 $variant $({
648 $(
649 $(#[$pin])?
650 $field
651 ),+
652 })?
653 ),+
654 }
655 }
656 $crate::__pin_project_enum_make_proj_method! {
657 [$($proj_ref_ident)?]
658 [$proj_vis]
659 [project_ref get_ref]
660 [$($ty_generics)*]
661 {
662 $(
663 $variant $({
664 $(
665 $(#[$pin])?
666 $field
667 ),+
668 })?
669 ),+
670 }
671 }
672 $crate::__pin_project_enum_make_proj_replace_method! {
673 [$($proj_replace_ident)?]
674 [$proj_vis]
675 [$($ty_generics)*]
676 {
677 $(
678 $variant $({
679 $(
680 $(#[$pin])?
681 $field
682 ),+
683 })?
684 ),+
685 }
686 }
687 }
688
689 $crate::__pin_project_make_unpin_impl! {
690 [$($proj_not_unpin_mark)?]
691 [$vis $ident]
692 [$($impl_generics)*] [$($ty_generics)*] [$(where $($where_clause)*)?]
693 $(
694 $variant: ($(
695 $(
696 $crate::__pin_project_make_unpin_bound!(
697 $(#[$pin])? $field_ty
698 )
699 ),+
700 )?)
701 ),+
702 }
703
704 $crate::__pin_project_make_drop_impl! {
705 [$ident]
706 [$($impl_generics)*] [$($ty_generics)*] [$(where $($where_clause)*)?]
707 $($(#[$drop_impl_attrs])* impl $($pinned_drop)*)?
708 }
709
710 // We don't need to check for '#[repr(packed)]',
711 // since it does not apply to enums.
712 };
713 };
714}
715
716#[doc(hidden)]
717#[macro_export]
718macro_rules! __pin_project_reconstruct {
719 (
720 [$(#[$attrs:meta])* $vis:vis struct $ident:ident]
721 [$($def_generics:tt)*] [$($impl_generics:tt)*]
722 [$($ty_generics:tt)*] [$(where $($where_clause:tt)*)?]
723 {
724 $(
725 $(#[$pin:ident])?
726 $field_vis:vis $field:ident: $field_ty:ty
727 ),+ $(,)?
728 }
729 ) => {
730 $(#[$attrs])*
731 $vis struct $ident $($def_generics)*
732 $(where
733 $($where_clause)*)?
734 {
735 $(
736 $field_vis $field: $field_ty
737 ),+
738 }
739 };
740 (
741 [$(#[$attrs:meta])* $vis:vis enum $ident:ident]
742 [$($def_generics:tt)*] [$($impl_generics:tt)*]
743 [$($ty_generics:tt)*] [$(where $($where_clause:tt)*)?]
744 {
745 $(
746 $(#[$variant_attrs:meta])*
747 $variant:ident $({
748 $(
749 $(#[$pin:ident])?
750 $field:ident: $field_ty:ty
751 ),+ $(,)?
752 })?
753 ),+ $(,)?
754 }
755 ) => {
756 $(#[$attrs])*
757 $vis enum $ident $($def_generics)*
758 $(where
759 $($where_clause)*)?
760 {
761 $(
762 $(#[$variant_attrs])*
763 $variant $({
764 $(
765 $field: $field_ty
766 ),+
767 })?
768 ),+
769 }
770 };
771}
772
773#[doc(hidden)]
774#[macro_export]
775macro_rules! __pin_project_make_proj_ty {
776 ([] $($field:tt)*) => {};
777 (
778 [$proj_ty_ident:ident $default_ident:ident]
779 [$proj_vis:vis struct $ident:ident]
780 $($field:tt)*
781 ) => {};
782 (
783 [$proj_ty_ident:ident]
784 [$proj_vis:vis struct $ident:ident]
785 [$__pin_project_make_proj_field:ident]
786 [$($impl_generics:tt)*] [$($ty_generics:tt)*] [$(where $($where_clause:tt)*)?]
787 {
788 $(
789 $(#[$pin:ident])?
790 $field_vis:vis $field:ident: $field_ty:ty
791 ),+ $(,)?
792 }
793 ) => {
794 $crate::__pin_project_make_proj_ty_body! {
795 [$proj_ty_ident]
796 [$proj_vis struct $ident]
797 [$($impl_generics)*] [$($ty_generics)*] [$(where $($where_clause)*)?]
798 [
799 $(
800 $field_vis $field: $crate::$__pin_project_make_proj_field!(
801 $(#[$pin])? $field_ty
802 )
803 ),+
804 ]
805 }
806 };
807 (
808 [$proj_ty_ident:ident]
809 [$proj_vis:vis enum $ident:ident]
810 [$__pin_project_make_proj_field:ident]
811 [$($impl_generics:tt)*] [$($ty_generics:tt)*] [$(where $($where_clause:tt)*)?]
812 {
813 $(
814 $(#[$variant_attrs:meta])*
815 $variant:ident $({
816 $(
817 $(#[$pin:ident])?
818 $field:ident: $field_ty:ty
819 ),+ $(,)?
820 })?
821 ),+ $(,)?
822 }
823 ) => {
824 $crate::__pin_project_make_proj_ty_body! {
825 [$proj_ty_ident]
826 [$proj_vis enum $ident]
827 [$($impl_generics)*] [$($ty_generics)*] [$(where $($where_clause)*)?]
828 [
829 $(
830 $variant $({
831 $(
832 $field: $crate::$__pin_project_make_proj_field!(
833 $(#[$pin])? $field_ty
834 )
835 ),+
836 })?
837 ),+
838 ]
839 }
840 };
841}
842
843#[doc(hidden)]
844#[macro_export]
845macro_rules! __pin_project_make_proj_ty_body {
846 (
847 [$proj_ty_ident:ident]
848 [$proj_vis:vis $struct_ty_ident:ident $ident:ident]
849 [$($impl_generics:tt)*] [$($ty_generics:tt)*] [$(where $($where_clause:tt)*)?]
850 [$($body_data:tt)+]
851 ) => {
852 #[doc(hidden)] // Workaround for rustc bug: see https://github.com/taiki-e/pin-project-lite/issues/77#issuecomment-1671540180 for more.
853 #[allow(dead_code)] // This lint warns unused fields/variants.
854 #[allow(single_use_lifetimes)] // https://github.com/rust-lang/rust/issues/55058
855 // This lint warns of `clippy::*` generated by external macros.
856 // We allow this lint for compatibility with older compilers.
857 #[allow(clippy::unknown_clippy_lints)]
858 #[allow(clippy::mut_mut)] // This lint warns `&mut &mut <ty>`. (only needed for project)
859 #[allow(clippy::redundant_pub_crate)] // This lint warns `pub(crate)` field in private struct.
860 #[allow(clippy::ref_option_ref)] // This lint warns `&Option<&<ty>>`. (only needed for project_ref)
861 #[allow(clippy::type_repetition_in_bounds)] // https://github.com/rust-lang/rust-clippy/issues/4326
862 $proj_vis $struct_ty_ident $proj_ty_ident <'__pin, $($impl_generics)*>
863 where
864 $ident <$($ty_generics)*>: '__pin
865 $(, $($where_clause)*)?
866 {
867 $($body_data)+
868 }
869 };
870}
871
872#[doc(hidden)]
873#[macro_export]
874macro_rules! __pin_project_make_proj_replace_ty {
875 ([] $($field:tt)*) => {};
876 (
877 [$proj_ty_ident:ident]
878 [$proj_vis:vis struct]
879 [$__pin_project_make_proj_field:ident]
880 [$($impl_generics:tt)*] [$($ty_generics:tt)*] [$(where $($where_clause:tt)*)?]
881 {
882 $(
883 $(#[$pin:ident])?
884 $field_vis:vis $field:ident: $field_ty:ty
885 ),+ $(,)?
886 }
887 ) => {
888 $crate::__pin_project_make_proj_replace_ty_body! {
889 [$proj_ty_ident]
890 [$proj_vis struct]
891 [$($impl_generics)*] [$($ty_generics)*] [$(where $($where_clause)*)?]
892 [
893 $(
894 $field_vis $field: $crate::$__pin_project_make_proj_field!(
895 $(#[$pin])? $field_ty
896 )
897 ),+
898 ]
899 }
900 };
901 (
902 [$proj_ty_ident:ident]
903 [$proj_vis:vis enum]
904 [$__pin_project_make_proj_field:ident]
905 [$($impl_generics:tt)*] [$($ty_generics:tt)*] [$(where $($where_clause:tt)*)?]
906 {
907 $(
908 $(#[$variant_attrs:meta])*
909 $variant:ident $({
910 $(
911 $(#[$pin:ident])?
912 $field:ident: $field_ty:ty
913 ),+ $(,)?
914 })?
915 ),+ $(,)?
916 }
917 ) => {
918 $crate::__pin_project_make_proj_replace_ty_body! {
919 [$proj_ty_ident]
920 [$proj_vis enum]
921 [$($impl_generics)*] [$($ty_generics)*] [$(where $($where_clause)*)?]
922 [
923 $(
924 $variant $({
925 $(
926 $field: $crate::$__pin_project_make_proj_field!(
927 $(#[$pin])? $field_ty
928 )
929 ),+
930 })?
931 ),+
932 ]
933 }
934 };
935}
936
937#[doc(hidden)]
938#[macro_export]
939macro_rules! __pin_project_make_proj_replace_ty_body {
940 (
941 [$proj_ty_ident:ident]
942 [$proj_vis:vis $struct_ty_ident:ident]
943 [$($impl_generics:tt)*] [$($ty_generics:tt)*] [$(where $($where_clause:tt)*)?]
944 [$($body_data:tt)+]
945 ) => {
946 #[doc(hidden)] // Workaround for rustc bug: see https://github.com/taiki-e/pin-project-lite/issues/77#issuecomment-1671540180 for more.
947 #[allow(dead_code)] // This lint warns unused fields/variants.
948 #[allow(single_use_lifetimes)] // https://github.com/rust-lang/rust/issues/55058
949 #[allow(clippy::mut_mut)] // This lint warns `&mut &mut <ty>`. (only needed for project)
950 #[allow(clippy::redundant_pub_crate)] // This lint warns `pub(crate)` field in private struct.
951 #[allow(clippy::type_repetition_in_bounds)] // https://github.com/rust-lang/rust-clippy/issues/4326
952 $proj_vis $struct_ty_ident $proj_ty_ident <$($impl_generics)*>
953 where
954 $($($where_clause)*)?
955 {
956 $($body_data)+
957 }
958 };
959}
960
961#[doc(hidden)]
962#[macro_export]
963macro_rules! __pin_project_make_proj_replace_block {
964 (
965 [$($proj_path:tt)+]
966 {
967 $(
968 $(#[$pin:ident])?
969 $field_vis:vis $field:ident
970 ),+
971 }
972 ) => {
973 let result = $($proj_path)* {
974 $(
975 $field: $crate::__pin_project_make_replace_field_proj!(
976 $(#[$pin])? $field
977 )
978 ),+
979 };
980
981 {
982 ( $(
983 $crate::__pin_project_make_unsafe_drop_in_place_guard!(
984 $(#[$pin])? $field
985 ),
986 )* );
987 }
988
989 result
990 };
991 ([$($proj_path:tt)+]) => { $($proj_path)* };
992}
993
994#[doc(hidden)]
995#[macro_export]
996macro_rules! __pin_project_struct_make_proj_method {
997 ([] $($variant:tt)*) => {};
998 (
999 [$proj_ty_ident:ident $_ignored_default_arg:ident]
1000 [$proj_vis:vis]
1001 [$method_ident:ident $get_method:ident $($mut:ident)?]
1002 [$($ty_generics:tt)*]
1003 $($variant:tt)*
1004 ) => {
1005 $crate::__pin_project_struct_make_proj_method! {
1006 [$proj_ty_ident]
1007 [$proj_vis]
1008 [$method_ident $get_method $($mut)?]
1009 [$($ty_generics)*]
1010 $($variant)*
1011 }
1012 };
1013 (
1014 [$proj_ty_ident:ident]
1015 [$proj_vis:vis]
1016 [$method_ident:ident $get_method:ident $($mut:ident)?]
1017 [$($ty_generics:tt)*]
1018 {
1019 $(
1020 $(#[$pin:ident])?
1021 $field_vis:vis $field:ident
1022 ),+
1023 }
1024 ) => {
1025 #[doc(hidden)] // Workaround for rustc bug: see https://github.com/taiki-e/pin-project-lite/issues/77#issuecomment-1671540180 for more.
1026 #[inline]
1027 $proj_vis fn $method_ident<'__pin>(
1028 self: $crate::__private::Pin<&'__pin $($mut)? Self>,
1029 ) -> $proj_ty_ident <'__pin, $($ty_generics)*> {
1030 unsafe {
1031 let Self { $($field),* } = self.$get_method();
1032 $proj_ty_ident {
1033 $(
1034 $field: $crate::__pin_project_make_unsafe_field_proj!(
1035 $(#[$pin])? $field
1036 )
1037 ),+
1038 }
1039 }
1040 }
1041 };
1042}
1043
1044#[doc(hidden)]
1045#[macro_export]
1046macro_rules! __pin_project_struct_make_proj_replace_method {
1047 ([] $($field:tt)*) => {};
1048 (
1049 [$proj_ty_ident:ident]
1050 [$proj_vis:vis]
1051 [$_proj_ty_ident:ident]
1052 [$($ty_generics:tt)*]
1053 {
1054 $(
1055 $(#[$pin:ident])?
1056 $field_vis:vis $field:ident
1057 ),+
1058 }
1059 ) => {
1060 #[doc(hidden)] // Workaround for rustc bug: see https://github.com/taiki-e/pin-project-lite/issues/77#issuecomment-1671540180 for more.
1061 #[inline]
1062 $proj_vis fn project_replace(
1063 self: $crate::__private::Pin<&mut Self>,
1064 replacement: Self,
1065 ) -> $proj_ty_ident <$($ty_generics)*> {
1066 unsafe {
1067 let __self_ptr: *mut Self = self.get_unchecked_mut();
1068
1069 // Destructors will run in reverse order, so next create a guard to overwrite
1070 // `self` with the replacement value without calling destructors.
1071 let __guard = $crate::__private::UnsafeOverwriteGuard::new(__self_ptr, replacement);
1072
1073 let Self { $($field),* } = &mut *__self_ptr;
1074
1075 $crate::__pin_project_make_proj_replace_block! {
1076 [$proj_ty_ident]
1077 {
1078 $(
1079 $(#[$pin])?
1080 $field
1081 ),+
1082 }
1083 }
1084 }
1085 }
1086 };
1087}
1088
1089#[doc(hidden)]
1090#[macro_export]
1091macro_rules! __pin_project_enum_make_proj_method {
1092 ([] $($variant:tt)*) => {};
1093 (
1094 [$proj_ty_ident:ident]
1095 [$proj_vis:vis]
1096 [$method_ident:ident $get_method:ident $($mut:ident)?]
1097 [$($ty_generics:tt)*]
1098 {
1099 $(
1100 $variant:ident $({
1101 $(
1102 $(#[$pin:ident])?
1103 $field:ident
1104 ),+
1105 })?
1106 ),+
1107 }
1108 ) => {
1109 #[doc(hidden)] // Workaround for rustc bug: see https://github.com/taiki-e/pin-project-lite/issues/77#issuecomment-1671540180 for more.
1110 #[inline]
1111 $proj_vis fn $method_ident<'__pin>(
1112 self: $crate::__private::Pin<&'__pin $($mut)? Self>,
1113 ) -> $proj_ty_ident <'__pin, $($ty_generics)*> {
1114 unsafe {
1115 match self.$get_method() {
1116 $(
1117 Self::$variant $({
1118 $($field),+
1119 })? => {
1120 $proj_ty_ident::$variant $({
1121 $(
1122 $field: $crate::__pin_project_make_unsafe_field_proj!(
1123 $(#[$pin])? $field
1124 )
1125 ),+
1126 })?
1127 }
1128 ),+
1129 }
1130 }
1131 }
1132 };
1133}
1134
1135#[doc(hidden)]
1136#[macro_export]
1137macro_rules! __pin_project_enum_make_proj_replace_method {
1138 ([] $($field:tt)*) => {};
1139 (
1140 [$proj_ty_ident:ident]
1141 [$proj_vis:vis]
1142 [$($ty_generics:tt)*]
1143 {
1144 $(
1145 $variant:ident $({
1146 $(
1147 $(#[$pin:ident])?
1148 $field:ident
1149 ),+
1150 })?
1151 ),+
1152 }
1153 ) => {
1154 #[doc(hidden)] // Workaround for rustc bug: see https://github.com/taiki-e/pin-project-lite/issues/77#issuecomment-1671540180 for more.
1155 #[inline]
1156 $proj_vis fn project_replace(
1157 self: $crate::__private::Pin<&mut Self>,
1158 replacement: Self,
1159 ) -> $proj_ty_ident <$($ty_generics)*> {
1160 unsafe {
1161 let __self_ptr: *mut Self = self.get_unchecked_mut();
1162
1163 // Destructors will run in reverse order, so next create a guard to overwrite
1164 // `self` with the replacement value without calling destructors.
1165 let __guard = $crate::__private::UnsafeOverwriteGuard::new(__self_ptr, replacement);
1166
1167 match &mut *__self_ptr {
1168 $(
1169 Self::$variant $({
1170 $($field),+
1171 })? => {
1172 $crate::__pin_project_make_proj_replace_block! {
1173 [$proj_ty_ident :: $variant]
1174 $({
1175 $(
1176 $(#[$pin])?
1177 $field
1178 ),+
1179 })?
1180 }
1181 }
1182 ),+
1183 }
1184 }
1185 }
1186 };
1187}
1188
1189#[doc(hidden)]
1190#[macro_export]
1191macro_rules! __pin_project_make_unpin_impl {
1192 (
1193 []
1194 [$vis:vis $ident:ident]
1195 [$($impl_generics:tt)*] [$($ty_generics:tt)*] [$(where $($where_clause:tt)*)?]
1196 $($field:tt)*
1197 ) => {
1198 // Automatically create the appropriate conditional `Unpin` implementation.
1199 //
1200 // Basically this is equivalent to the following code:
1201 // ```
1202 // impl<T, U> Unpin for Struct<T, U> where T: Unpin {}
1203 // ```
1204 //
1205 // However, if struct is public and there is a private type field,
1206 // this would cause an E0446 (private type in public interface).
1207 //
1208 // When RFC 2145 is implemented (rust-lang/rust#48054),
1209 // this will become a lint, rather than a hard error.
1210 //
1211 // As a workaround for this, we generate a new struct, containing all of the pinned
1212 // fields from our #[pin_project] type. This struct is declared within
1213 // a function, which makes it impossible to be named by user code.
1214 // This guarantees that it will use the default auto-trait impl for Unpin -
1215 // that is, it will implement Unpin iff all of its fields implement Unpin.
1216 // This type can be safely declared as 'public', satisfying the privacy
1217 // checker without actually allowing user code to access it.
1218 //
1219 // This allows users to apply the #[pin_project] attribute to types
1220 // regardless of the privacy of the types of their fields.
1221 //
1222 // See also https://github.com/taiki-e/pin-project/pull/53.
1223 #[allow(non_snake_case)]
1224 $vis struct __Origin<'__pin, $($impl_generics)*>
1225 $(where
1226 $($where_clause)*)?
1227 {
1228 __dummy_lifetime: $crate::__private::PhantomData<&'__pin ()>,
1229 $($field)*
1230 }
1231 impl <'__pin, $($impl_generics)*> $crate::__private::Unpin for $ident <$($ty_generics)*>
1232 where
1233 $crate::__private::PinnedFieldsOf<__Origin<'__pin, $($ty_generics)*>>:
1234 $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 // Workaround for issue on unstable negative_impls feature that allows unsound overlapping Unpin
1679 // implementations and rustc bug that leaks unstable negative_impls into stable.
1680 // See https://github.com/taiki-e/pin-project/issues/340#issuecomment-2432146009 for details.
1681 #[doc(hidden)]
1682 pub type PinnedFieldsOf<T> =
1683 <PinnedFieldsOfHelperStruct<T> as PinnedFieldsOfHelperTrait>::Actual;
1684 // We cannot use <Option<T> as IntoIterator>::Item or similar since we should allow ?Sized in T.
1685 #[doc(hidden)]
1686 pub trait PinnedFieldsOfHelperTrait {
1687 type Actual: ?Sized;
1688 }
1689 #[doc(hidden)]
1690 pub struct PinnedFieldsOfHelperStruct<T: ?Sized>(T);
1691 impl<T: ?Sized> PinnedFieldsOfHelperTrait for PinnedFieldsOfHelperStruct<T> {
1692 type Actual = T;
1693 }
1694
1695 // This is an internal helper struct used by `pin_project!`.
1696 #[doc(hidden)]
1697 pub struct AlwaysUnpin<T: ?Sized>(PhantomData<T>);
1698 impl<T: ?Sized> Unpin for AlwaysUnpin<T> {}
1699
1700 // This is an internal helper used to ensure a value is dropped.
1701 #[doc(hidden)]
1702 pub struct UnsafeDropInPlaceGuard<T: ?Sized>(*mut T);
1703 impl<T: ?Sized> UnsafeDropInPlaceGuard<T> {
1704 #[doc(hidden)]
1705 pub unsafe fn new(ptr: *mut T) -> Self {
1706 Self(ptr)
1707 }
1708 }
1709 impl<T: ?Sized> Drop for UnsafeDropInPlaceGuard<T> {
1710 fn drop(&mut self) {
1711 // SAFETY: the caller of `UnsafeDropInPlaceGuard::new` must guarantee
1712 // that `ptr` is valid for drop when this guard is destructed.
1713 unsafe {
1714 ptr::drop_in_place(self.0);
1715 }
1716 }
1717 }
1718
1719 // This is an internal helper used to ensure a value is overwritten without
1720 // its destructor being called.
1721 #[doc(hidden)]
1722 pub struct UnsafeOverwriteGuard<T> {
1723 target: *mut T,
1724 value: ManuallyDrop<T>,
1725 }
1726 impl<T> UnsafeOverwriteGuard<T> {
1727 #[doc(hidden)]
1728 pub unsafe fn new(target: *mut T, value: T) -> Self {
1729 Self { target, value: ManuallyDrop::new(value) }
1730 }
1731 }
1732 impl<T> Drop for UnsafeOverwriteGuard<T> {
1733 fn drop(&mut self) {
1734 // SAFETY: the caller of `UnsafeOverwriteGuard::new` must guarantee
1735 // that `target` is valid for writes when this guard is destructed.
1736 unsafe {
1737 ptr::write(self.target, ptr::read(&*self.value));
1738 }
1739 }
1740 }
1741}