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