pin_project_internal/
pinned_drop.rs

Help
1// SPDX-License-Identifier: Apache-2.0 OR MIT
2
3use proc_macro2::{Span, TokenStream};
4use quote::{ToTokens as _, format_ident, quote};
5use syn::{
6    Error, FnArg, GenericArgument, Ident, ImplItem, ItemImpl, Pat, PatIdent, PatType, Path,
7    PathArguments, Result, ReturnType, Signature, Token, Type, TypePath, TypeReference,
8    parse_quote, spanned::Spanned as _, token::Colon, visit_mut::VisitMut as _,
9};
10
11use crate::utils::{ReplaceReceiver, SliceExt as _};
12
13pub(crate) fn attribute(args: &TokenStream, mut input: ItemImpl) -> TokenStream {
14    let res = (|| -> Result<()> {
15        if !args.is_empty() {
16            bail!(args, "unexpected argument: `{}`", args)
17        }
18        validate_impl(&input)?;
19        expand_impl(&mut input);
20        Ok(())
21    })();
22
23    if let Err(e) = res {
24        let mut tokens = e.to_compile_error();
25        if let Type::Path(self_ty) = &*input.self_ty {
26            let (impl_generics, _, where_clause) = input.generics.split_for_impl();
27
28            // Generate a dummy impl of `PinnedDrop`.
29            // In many cases, `#[pinned_drop] impl` is declared after `#[pin_project]`.
30            // Therefore, if `pinned_drop` compile fails, you will also get an error
31            // about `PinnedDrop` not being implemented.
32            // This can be prevented to some extent by generating a dummy
33            // `PinnedDrop` implementation.
34            // We already know that we will get a compile error, so this won't
35            // accidentally compile successfully.
36            //
37            // However, if `input.self_ty` is not Type::Path, there is a high possibility that
38            // the type does not exist (since #[pin_project] can only be used on struct/enum
39            // definitions), so do not generate a dummy impl.
40            tokens.extend(quote! {
41                impl #impl_generics ::pin_project::__private::PinnedDrop for #self_ty
42                #where_clause
43                {
44                    unsafe fn drop(self: ::pin_project::__private::Pin<&mut Self>) {}
45                }
46            });
47        }
48        tokens
49    } else {
50        input.into_token_stream()
51    }
52}
53
54/// Validates the signature of given `PinnedDrop` impl.
55fn validate_impl(item: &ItemImpl) -> Result<()> {
56    const INVALID_ITEM: &str =
57        "#[pinned_drop] may only be used on implementation for the `PinnedDrop` trait";
58
59    if let Some(attr) = item.attrs.find("pinned_drop") {
60        bail!(attr, "duplicate #[pinned_drop] attribute");
61    }
62
63    if let Some((_, path, _)) = &item.trait_ {
64        if !path.is_ident("PinnedDrop") {
65            bail!(path, INVALID_ITEM);
66        }
67    } else {
68        bail!(item.self_ty, INVALID_ITEM);
69    }
70
71    if item.unsafety.is_some() {
72        bail!(item.unsafety, "implementing the trait `PinnedDrop` is not unsafe");
73    }
74    if item.items.is_empty() {
75        bail!(item, "not all trait items implemented, missing: `drop`");
76    }
77
78    match &*item.self_ty {
79        Type::Path(_) => {}
80        ty => {
81            bail!(ty, "implementing the trait `PinnedDrop` on this type is unsupported");
82        }
83    }
84
85    item.items.iter().enumerate().try_for_each(|(i, item)| match item {
86        ImplItem::Const(item) => {
87            bail!(item, "const `{}` is not a member of trait `PinnedDrop`", item.ident)
88        }
89        ImplItem::Type(item) => {
90            bail!(item, "type `{}` is not a member of trait `PinnedDrop`", item.ident)
91        }
92        ImplItem::Fn(method) => {
93            validate_sig(&method.sig)?;
94            if i == 0 { Ok(()) } else { bail!(method, "duplicate definitions with name `drop`") }
95        }
96        _ => unreachable!("unexpected ImplItem"),
97    })
98}
99
100/// Validates the signature of given `PinnedDrop::drop` method.
101///
102/// The correct signature is: `(mut) self: (<path>::)Pin<&mut Self>`
103fn validate_sig(sig: &Signature) -> Result<()> {
104    fn get_ty_path(ty: &Type) -> Option<&Path> {
105        if let Type::Path(TypePath { qself: None, path }) = ty { Some(path) } else { None }
106    }
107
108    const INVALID_ARGUMENT: &str = "method `drop` must take an argument `self: Pin<&mut Self>`";
109
110    if sig.ident != "drop" {
111        bail!(sig.ident, "method `{}` is not a member of trait `PinnedDrop`", sig.ident);
112    }
113
114    if let ReturnType::Type(_, ty) = &sig.output {
115        match &**ty {
116            Type::Tuple(ty) if ty.elems.is_empty() => {}
117            _ => bail!(ty, "method `drop` must return the unit type"),
118        }
119    }
120
121    match sig.inputs.len() {
122        1 => {}
123        0 => return Err(Error::new(sig.paren_token.span.join(), INVALID_ARGUMENT)),
124        _ => bail!(sig.inputs, INVALID_ARGUMENT),
125    }
126
127    if let Some(arg) = sig.receiver() {
128        // (mut) self: <path>
129        if let Some(path) = get_ty_path(&arg.ty) {
130            let ty =
131                path.segments.last().expect("type paths should always have at least one segment");
132            if let PathArguments::AngleBracketed(args) = &ty.arguments {
133                // (mut) self: (<path>::)<ty><&mut <elem>..>
134                if let Some(GenericArgument::Type(Type::Reference(TypeReference {
135                    mutability: Some(_),
136                    elem,
137                    ..
138                }))) = args.args.first()
139                {
140                    // (mut) self: (<path>::)Pin<&mut Self>
141                    if args.args.len() == 1
142                        && ty.ident == "Pin"
143                        && get_ty_path(elem).map_or(false, |path| path.is_ident("Self"))
144                    {
145                        if sig.unsafety.is_some() {
146                            bail!(sig.unsafety, "implementing the method `drop` is not unsafe");
147                        }
148                        return Ok(());
149                    }
150                }
151            }
152        }
153    }
154
155    bail!(sig.inputs[0], INVALID_ARGUMENT)
156}
157
158// from:
159//
160// fn drop(self: Pin<&mut Self>) {
161//     // ...
162// }
163//
164// into:
165//
166// unsafe fn drop(self: Pin<&mut Self>) {
167//     fn __drop_inner<T>(__self: Pin<&mut Foo<'_, T>>) {
168//         fn __drop_inner() {}
169//         // ...
170//     }
171//     __drop_inner(self);
172// }
173//
174fn expand_impl(item: &mut ItemImpl) {
175    // `PinnedDrop` is a private trait and should not appear in docs.
176    item.attrs.push(parse_quote!(#[doc(hidden)]));
177
178    let path = &mut item.trait_.as_mut().expect("unexpected inherent impl").1;
179    *path = parse_quote_spanned! { Span::call_site().located_at(path.span()) =>
180        ::pin_project::__private::PinnedDrop
181    };
182
183    let method =
184        if let ImplItem::Fn(method) = &mut item.items[0] { method } else { unreachable!() };
185
186    // `fn drop(mut self: Pin<&mut Self>)` -> `fn __drop_inner<T>(mut __self: Pin<&mut Receiver>)`
187    let drop_inner = {
188        let mut drop_inner = method.clone();
189        let ident = format_ident!("__drop_inner");
190        // Add a dummy `__drop_inner` function to prevent users call outer `__drop_inner`.
191        drop_inner.block.stmts.insert(0, parse_quote!(fn #ident() {}));
192        drop_inner.sig.ident = ident;
193        drop_inner.sig.generics = item.generics.clone();
194        let receiver = drop_inner.sig.receiver().expect("drop() should have a receiver").clone();
195        let pat = Box::new(Pat::Ident(PatIdent {
196            attrs: vec![],
197            by_ref: None,
198            mutability: receiver.mutability,
199            ident: Ident::new("__self", receiver.self_token.span()),
200            subpat: None,
201        }));
202        drop_inner.sig.inputs[0] = FnArg::Typed(PatType {
203            attrs: receiver.attrs,
204            pat,
205            colon_token: Colon::default(),
206            ty: receiver.ty,
207        });
208        let self_ty = if let Type::Path(ty) = &*item.self_ty { ty } else { unreachable!() };
209        let mut visitor = ReplaceReceiver(self_ty);
210        visitor.visit_signature_mut(&mut drop_inner.sig);
211        visitor.visit_block_mut(&mut drop_inner.block);
212        drop_inner
213    };
214
215    // `fn drop(mut self: Pin<&mut Self>)` -> `unsafe fn drop(self: Pin<&mut Self>)`
216    method.sig.unsafety = Some(<Token![unsafe]>::default());
217    let self_token = if let FnArg::Receiver(ref mut rec) = method.sig.inputs[0] {
218        rec.mutability = None;
219        &rec.self_token
220    } else {
221        panic!("drop() should have a receiver")
222    };
223
224    method.block.stmts = parse_quote! {
225        #[allow(
226            clippy::missing_const_for_fn,
227            clippy::needless_pass_by_value, // This lint does not warn the receiver.
228            clippy::single_call_fn
229        )]
230        #drop_inner
231        __drop_inner(#self_token);
232    };
233}
pin_project_internal/pinned_drop.rs

pin_project_internal/
pinned_drop.rs
