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