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