yoke_derive/lib.rs
1// This file is part of ICU4X. For terms of use, please see the file
2// called LICENSE at the top level of the ICU4X source tree
3// (online at: https://github.com/unicode-org/icu4x/blob/main/LICENSE ).
4
5// https://github.com/unicode-org/icu4x/blob/main/documents/process/boilerplate.md#library-annotations
6// #![cfg_attr(not(any(test, doc)), no_std)]
7#![cfg_attr(
8 not(test),
9 deny(
10 clippy::indexing_slicing,
11 clippy::unwrap_used,
12 clippy::expect_used,
13 clippy::panic,
14 )
15)]
16#![warn(missing_docs)]
17
18//! Custom derives for `Yokeable` from the `yoke` crate.
19
20mod lifetimes;
21mod visitor;
22
23use proc_macro::TokenStream;
24use proc_macro2::TokenStream as TokenStream2;
25use quote::quote;
26use syn::ext::IdentExt as _;
27use syn::spanned::Spanned;
28use syn::{parse_macro_input, parse_quote, DeriveInput, GenericParam, Ident, WherePredicate};
29use synstructure::Structure;
30
31use self::lifetimes::{custom_lt, ignored_lifetime_ident, replace_lifetime, static_lt};
32use self::visitor::{
33 check_parameter_for_bound_lts, check_type_for_parameters, check_where_clause_for_bound_lts,
34 CheckResult,
35};
36
37/// Custom derive for `yoke::Yokeable`.
38///
39/// If your struct contains `zerovec::ZeroMap`, then the compiler will not
40/// be able to guarantee the lifetime covariance due to the generic types on
41/// the `ZeroMap` itself. You must add the following attribute in order for
42/// the custom derive to work with `ZeroMap`.
43///
44/// ```rust,ignore
45/// #[derive(Yokeable)]
46/// #[yoke(prove_covariance_manually)]
47/// ```
48///
49/// Beyond this case, if the derive fails to compile due to lifetime issues, it likely
50/// means that the lifetime is not covariant and `Yokeable` is not safe to implement.
51#[proc_macro_derive(Yokeable, attributes(yoke))]
52pub fn yokeable_derive(input: TokenStream) -> TokenStream {
53 let input = parse_macro_input!(input as DeriveInput);
54 TokenStream::from(yokeable_derive_impl(&input))
55}
56
57/// A small amount of metadata about a field of the yokeable type
58struct FieldParamUsage {
59 uses_lt: bool,
60 uses_ty: bool,
61}
62
63impl From<CheckResult> for FieldParamUsage {
64 fn from(value: CheckResult) -> Self {
65 Self {
66 uses_lt: value.uses_lifetime_param,
67 uses_ty: value.uses_type_params,
68 }
69 }
70}
71
72fn yokeable_derive_impl(input: &DeriveInput) -> TokenStream2 {
73 let name = &input.ident;
74 let tybounds = input
75 .generics
76 .params
77 .iter()
78 .filter_map(|param| {
79 match param {
80 GenericParam::Lifetime(_) => None,
81 GenericParam::Type(ty) => {
82 // Strip out param defaults, we don't need them in the impl
83 let mut ty = ty.clone();
84 ty.default = None;
85 Some(GenericParam::Type(ty))
86 }
87 // TODO: support const-generics in a future PR
88 // GenericParam::Const(const_param) => {
89 // // Strip out param defaults, we don't need them in the impl
90 // let mut const_param = const_param.clone();
91 // const_param.eq_token = None;
92 // const_param.default = None;
93 // Some(GenericParam::Const(const_param))
94 // }
95 GenericParam::Const(_) => None,
96 }
97 })
98 .collect::<Vec<_>>();
99 let typarams = tybounds
100 .iter()
101 .map(|param| match param {
102 // We filtered out lifetime parameters
103 GenericParam::Lifetime(_) => unreachable!(),
104 GenericParam::Type(ty) => ty.ident.clone(),
105 // TODO: support const-generics in a future PR
106 // GenericParam::Const(const_param) => const_param.ident.clone(),
107 GenericParam::Const(_) => unreachable!(),
108 })
109 .collect::<Vec<_>>();
110 let wherebounds = input
111 .generics
112 .where_clause
113 .iter()
114 .flat_map(|wc| wc.predicates.iter())
115 // If some future version of Rust adds more than just lifetime and type where-bound
116 // predicates, we may want to match more predicates.
117 .filter(|p| matches!(p, WherePredicate::Type(_)))
118 .collect::<Vec<_>>();
119 // We require all type parameters be 'static, otherwise
120 // the Yokeable impl becomes really unwieldy to generate safely.
121 let static_bounds: Vec<WherePredicate> = tybounds
122 .iter()
123 .filter_map(|param| {
124 if let GenericParam::Type(ty) = param {
125 let ty = &ty.ident;
126 Some(parse_quote!(#ty: 'static))
127 } else {
128 None
129 }
130 })
131 .collect();
132 // Above idents are *not* `unraw`d, because they may be emitted by the derive
133 // (so they might actually need to be raw).
134
135 // Either the `unraw`d first lifetime parameter of the yokeable, or some ignored ident.
136 // This parameter affects `uses_lifetime_param` values of `CheckResult`s and `uses_lt`
137 // values of `FieldParamUsage`, but those values only impact the generated code if there
138 // is at least one lifetime parameter; therefore, the random ident doesn't matter.
139 let lt_param = input
140 .generics
141 .lifetimes()
142 .next()
143 .map_or_else(ignored_lifetime_ident, |lt| lt.lifetime.ident.unraw());
144 let typarams_env = tybounds
145 .iter()
146 .filter_map(|param| {
147 if let GenericParam::Type(ty) = param {
148 Some(ty.ident.unraw())
149 } else {
150 None
151 }
152 })
153 .collect();
154 let mut underscores_for_lt = 0;
155
156 // We need to do this analysis even before the case where there are zero lifetime parameters
157 // in order to choose a `'__[underscores]__yoke` lifetime.
158 // We need to check:
159 // - trait bounds on generic type parameters
160 // - default types for generic type parameters
161 // - type bounds on const generic parameters
162 // - where-bounds
163 // - field types
164 // Checking lifetime parameters and default values for const generic parameters isn't
165 // particularly useful, but does no harm, so the simplest approach to knock out the first three
166 // is to just check every parameter.
167 for param in &input.generics.params {
168 underscores_for_lt = underscores_for_lt.max(check_parameter_for_bound_lts(param));
169 }
170 if let Some(where_clause) = &input.generics.where_clause {
171 underscores_for_lt = underscores_for_lt.max(check_where_clause_for_bound_lts(where_clause));
172 }
173
174 let structure = {
175 let mut structure = Structure::new(input);
176 structure.bind_with(|_| synstructure::BindStyle::Move);
177 structure
178 };
179
180 // Information from `synstructure::Structure`, whose ordering of fields is deterministic.
181 // Note that it's crucial that we don't filter out any variants or fields from the `Structure`.
182 let mut field_info: Vec<FieldParamUsage> = Vec::new();
183 // This code creating `field_info` should not be carelessly modified, else it could cause
184 // a panic in a below `expect`.
185 for variant_info in structure.variants() {
186 for field_binding_info in variant_info.bindings() {
187 let field = field_binding_info.ast();
188 // Note: `lt_param` and everything in `typarams_env` were `unraw`d
189 let check_result = check_type_for_parameters(<_param, &typarams_env, &field.ty);
190
191 underscores_for_lt = underscores_for_lt.max(check_result.min_underscores_for_yoke_lt);
192 field_info.push(check_result.into());
193 }
194 }
195 let field_info = field_info;
196
197 // All usages of the `check_*` functions are above this point,
198 // in order to ensure that `yoke_lt` is correct.
199 let (yoke_lt, bound_lt) = {
200 let underscores = "_".repeat(underscores_for_lt);
201 (
202 format!("'{underscores}yoke"),
203 format!("'_{underscores}yoke"),
204 )
205 };
206 // This is used where the `Yokeable<'a>` trait uses `'a` by default
207 let yoke_lt = custom_lt(&yoke_lt);
208 // This is used where the `Yokeable<'a>` trait uses `'b` by default
209 let bound_lt = custom_lt(&bound_lt);
210
211 let mut lts = input.generics.lifetimes();
212
213 if lts.next().is_none() {
214 // There are 0 lifetime parameters.
215
216 return quote! {
217 // This is safe because there are no lifetime parameters, and `type Output = Self`.
218 unsafe impl<#yoke_lt, #(#tybounds),*> yoke::Yokeable<#yoke_lt>
219 for #name<#(#typarams),*>
220 where
221 #(#static_bounds,)*
222 #(#wherebounds,)*
223 Self: Sized
224 {
225 type Output = Self;
226 #[inline]
227 fn transform(&self) -> &Self::Output {
228 self
229 }
230 #[inline]
231 fn transform_owned(self) -> Self::Output {
232 self
233 }
234 #[inline]
235 unsafe fn make(this: Self::Output) -> Self {
236 this
237 }
238 #[inline]
239 fn transform_mut<F>(&#yoke_lt mut self, f: F)
240 where
241 F: 'static + for<#bound_lt> FnOnce(&#bound_lt mut Self::Output) {
242 f(self)
243 }
244 }
245 };
246 };
247
248 if lts.next().is_some() {
249 // We already extracted one lifetime into `source_lt`, so this means there are
250 // multiple lifetimes.
251 return syn::Error::new(
252 input.generics.span(),
253 "derive(Yokeable) cannot have multiple lifetime parameters",
254 )
255 .to_compile_error();
256 }
257
258 let manual_covariance = input.attrs.iter().any(|a| {
259 if a.path().is_ident("yoke") {
260 if let Ok(i) = a.parse_args::<Ident>() {
261 if i == "prove_covariance_manually" {
262 return true;
263 }
264 }
265 }
266 false
267 });
268
269 if !manual_covariance {
270 // This is safe because as long as `transform()` compiles,
271 // we can be sure that `'a` is a covariant lifetime on `Self`.
272 // (Using `'a` as shorthand for `#yoke_lt`.)
273 //
274 // In particular, the operand of `&raw const` is not a location where implicit
275 // type coercion can occur, so the type of `&raw const self` is `*const &'a Self`.
276 // The RHS of a `let` with an explicit type annotation allows type coercion, so
277 // `transform` checks that `*const &'a Self` can coerce to `*const &'a Self::Output`.
278 // Most of the possible type coercions
279 // (listed at https://doc.rust-lang.org/reference/type-coercions.html)
280 // do not apply, other than subtyping coercions and transitive coercions (which do
281 // not add anything beyond subtyping coercions). In particular, there's nothing
282 // like a `DerefRaw` on `*const T`, and `&T` does not implement `Unsize`, so
283 // there cannot be an unsizing coercion from `*const &'a Self` to
284 // `*const &'a Self::Output`. Therefore, `transform` compiles if and only if
285 // a subtyping coercion is possible; this requires that `Self` must be a subtype
286 // of `Self::Output`, just as `&'static T` is a subtype of `&'a T` (for `T: 'static`).
287 // This ensures covariance.
288 //
289 // This will not work for structs involving ZeroMap since
290 // the compiler does not know that ZeroMap is covariant.
291 //
292 // This custom derive can be improved to handle this case when necessary,
293 // with `prove_covariance_manually`.
294 return quote! {
295 unsafe impl<#yoke_lt, #(#tybounds),*> yoke::Yokeable<#yoke_lt>
296 for #name<'static, #(#typarams),*>
297 where
298 #(#static_bounds,)*
299 #(#wherebounds,)*
300 // Adding `Self: Sized` here doesn't work.
301 // `for<#bound_lt> #name<#bound_lt, #(#typarams),*>: Sized`
302 // might work, though. Since these trait bounds are very finicky, it's best to just
303 // not try unless necessary.
304 {
305 type Output = #name<#yoke_lt, #(#typarams),*>;
306 #[inline]
307 fn transform(&#yoke_lt self) -> &#yoke_lt Self::Output {
308 if false {
309 let _: *const &#yoke_lt Self::Output = &raw const self;
310 }
311 self
312 }
313 #[inline]
314 fn transform_owned(self) -> Self::Output {
315 self
316 }
317 #[inline]
318 unsafe fn make(from: Self::Output) -> Self {
319 ::core::mem::transmute::<Self::Output, Self>(from)
320 }
321 #[inline]
322 fn transform_mut<F>(&#yoke_lt mut self, f: F)
323 where
324 F: 'static + for<#bound_lt> FnOnce(&#bound_lt mut Self::Output) {
325 let y = unsafe { &mut *(self as *mut Self as *mut Self::Output) };
326 f(y)
327 }
328 }
329 };
330 }
331
332 // `prove_covariance_manually` requires additional bounds
333 let mut manual_proof_bounds: Vec<WherePredicate> = Vec::new();
334 let mut yokeable_checks = TokenStream2::new();
335 let mut output_checks = TokenStream2::new();
336 let mut field_info = field_info.into_iter();
337
338 // See `synstructure::Structure::each` and `synstructure::VariantInfo::each`
339 // for the setup of the two `*_checks` token streams. We can elide some brackets compared
340 // to `synstructure`, since we know that each check defines no local variables, items, etc.
341
342 // We iterate over the fields of `structure` in the same way that `field_info` was created.
343 for variant_info in structure.variants() {
344 let mut yokeable_check_body = TokenStream2::new();
345 let mut output_check_body = TokenStream2::new();
346
347 for field_binding_info in variant_info.bindings() {
348 let field = field_binding_info.ast();
349 let field_binding = &field_binding_info.binding;
350
351 // This invariant is somewhat complicated, but immutable variables, iteration order,
352 // and creating/using one `FieldParamUsage per iteration ensure that `field_info`
353 // has an entry for this field (and it refers to the expected field).
354 #[expect(
355 clippy::expect_used,
356 reason = "See above comment; this should never panic"
357 )]
358 let FieldParamUsage { uses_lt, uses_ty } = field_info
359 .next()
360 .expect("fields of an unmutated synstructure::Structure should remain the same");
361
362 // Note that this type could be a weird non-pure macro type. However, even though
363 // we evaluate it once or twice in where-bounds, we evaluate it exactly once
364 // in the soundness-critical checks, so it can't cause UB by unexpectedly evaluating
365 // to a different type. That can only cause a compile error at worst.
366 let fty_static = replace_lifetime(<_param, &field.ty, static_lt());
367
368 // For field types that don't use type or lifetime parameters, we don't add `Yokeable`
369 // or `'static` where-bounds, and the field is required to unconditionally meet a
370 // `'static` requirement (in its output form).
371 //
372 // For field types that use the lifetime parameter but no type parameters, we also don't
373 // add any where-bounds, and the field is required to unconditionally meet a
374 // `Yokeable` requirement (in its static yokeable form).
375 // (The compiler should be able to figure out whether that requirement is satisfied.
376 // A where-bound is intentionally avoided, to avoid letting `derive(Yokeable)`
377 // compile on a struct when it's statically known that the where-bound is never
378 // satisfied.)
379 //
380 // For field types that use a type parameter but not the lifetime parameter, the field
381 // is assumed not to borrow from the cart and is therefore required to be `'static`
382 // (in its output form), and a where-bound is added for this field being `'static`.
383 //
384 // For field types that use both the lifetime parameter and type parameters, the
385 // field is required to be `Yokeable` (in its static form). Since there may be complex
386 // preconditions to `FieldTy: Yokeable` that need to be satisfied, a where-bound
387 // requires that `FieldTy<'static>: Yokeable<#yoke_lt, Output = FieldTy<#yoke_lt>>`.
388 // This requirement is also tested on the field's static yokeable form.
389
390 // Note: if `field.ty` involves a non-pure macro type, each time it's evaluated, it
391 // could be a different type. The where-bounds are relied on to make the impl compile
392 // in sane cases, *not* for soundness. Our `transform()` impl does not blindly assume
393 // that the fields' types implement `Yokeable` or `'static`, regardless of these bounds.
394 if uses_ty {
395 if uses_lt {
396 let fty_output = replace_lifetime(<_param, &field.ty, yoke_lt.clone());
397
398 manual_proof_bounds.push(
399 parse_quote!(#fty_static: yoke::Yokeable<#yoke_lt, Output = #fty_output>),
400 );
401 } else {
402 manual_proof_bounds.push(parse_quote!(#fty_static: 'static));
403 }
404 }
405 if uses_lt {
406 // This confirms that this `FieldTy` is a subtype of something which implements
407 // `Yokeable<'a>`, and since only `'static` types can be subtypes of a `'static`
408 // type (and all `Yokeable` implementors are `'static`), we have that either:
409 // - `FieldTy` is some `'static` type which does NOT implement `Yokeable`, but via
410 // function pointer subtyping or something similar, is a subtype of something
411 // implementing `Yokeable`, or
412 // - `FieldTy` is some type which does itself implement `Yokeable`.
413 // In either of those cases, it is sound to treat `FieldTy` as covariant in the `'a`
414 // parameter. (Using `'a` as shorthand for `#yoke_lt`.)
415 //
416 // Now, to justify that `FieldTy` (the field's actual type,
417 // not just `field.ty`, which may have a non-pure macro type)
418 // is a subtype of something which implements `Yokeable<'a>`:
419 //
420 // `#field_binding` has type `&'a FieldTy` (since it's a field of `&'a Self` matched
421 // as `self`). The operand of `&raw const` is not a location where implicit type
422 // coercion can occur. Therefore, `&raw const #field_binding` is guaranteed to be
423 // type `*const &'a FieldTy`. The argument to `__yoke_derive_require_yokeable`
424 // does allow type coercion.
425 // Looking at <https://doc.rust-lang.org/reference/type-coercions.html>,
426 // there are only three types of coercions that could plausibly apply:
427 // - subtyping coercions,
428 // - transitive coercions, and
429 // - unsizing coercions.
430 // (If some sort of `DerefRaw` trait gets added for `*const`, there could plausibly
431 // be problems with that. But there's no reason to think that such a trait will be
432 // added, since it'd mess with `unsafe` code, and Rust devs should recognize that.)
433 //
434 // Since `&'a _` does not implement `Unsize`, we have that `*const &'a _` does not
435 // allow an unsizing coercion to occur. Therefore, there are only subtyping
436 // coercions, since transitive coercions add nothing on top of subtyping coercions.
437 // Therefore, if this compiles, `*const &'a FieldTy` must be a subtype of
438 // `*const &'a T` where `T = #fty_static` is the generic parameter of
439 // `__yoke_derive_require_yokeable`.
440 // Looking at the signature of that function generated below, we have that
441 // `T: Yokeable<'a>` (if it compiles). Note that if `#fty_static` is incorrect,
442 // even if there is some other `T` which would work, this will just fail to compile.
443 // Since `*const _` and `&'a _` are covariant over their type parameters, we have
444 // that `FieldTy` must be a subtype of `T` in order for a subtyping coercion from
445 // `*const &'a FieldTy` to `*const &'a T` to occur.
446 //
447 // Therefore, `FieldTy` must be a subtype of something which implements
448 // `Yokeable<'a>` in order for this to compile. (Though that is not a _sufficient_
449 // condition to compile, as some weird macro type could break stuff.)
450 yokeable_check_body.extend(quote! {
451 __yoke_derive_require_yokeable::<#yoke_lt, #fty_static>(&raw const #field_binding);
452 });
453 } else {
454 // No visible nested lifetimes, so there should be nothing to be done in sane cases.
455 // However, in case a macro type does something strange and accesses the available
456 // `#yoke_lt` lifetime, we still need to check that the field's actual type is
457 // `'static` regardless of `#yoke_lt` (which we can check by ensuring that it
458 // be a subtype of a `'static` type).
459 // See reasoning in the `if` branch for why this works. The difference is that
460 // `FieldTy` is guaranteed to be a subtype of `T = #fty_static` where `T: 'static`
461 // (if this compiles). Since the field's type is a subtype of something which is
462 // `'static`, it must itself be `'static`, and therefore did not manage to use
463 // `#yoke_lt` via a macro.
464 // Note that creating and using `#fty_output` is not necessary here, since
465 // `field.ty == fty_static == fty_output` (no lifetime was visibly present which
466 // could be replaced).
467 output_check_body.extend(quote! {
468 __yoke_derive_require_static::<#yoke_lt, #fty_static>(&raw const #field_binding);
469 });
470 }
471 }
472
473 let pat = variant_info.pat();
474 yokeable_checks.extend(quote! { #pat => { #yokeable_check_body }});
475 output_checks.extend(quote! { #pat => { #output_check_body }});
476 }
477
478 quote! {
479 // SAFETY: we assert covariance in `borrowed_checks`
480 unsafe impl<#yoke_lt, #(#tybounds),*> yoke::Yokeable<#yoke_lt>
481 for #name<'static, #(#typarams),*>
482 where
483 #(#static_bounds,)*
484 #(#wherebounds,)*
485 #(#manual_proof_bounds,)*
486 // Adding `Self: Sized` here doesn't work.
487 // `for<#bound_lt> #name<#bound_lt, #(#typarams),*>: Sized`
488 // might work, though. Since these trait bounds are very finicky, it's best to just
489 // not try unless necessary.
490 {
491 type Output = #name<#yoke_lt, #(#typarams),*>;
492 #[inline]
493 fn transform(&#yoke_lt self) -> &#yoke_lt Self::Output {
494 // These are just type asserts, we don't need to run them
495 if false {
496 // This could, hypothetically, conflict with the name of one of the `FieldTy`s
497 // we read (and cause a compilation error). However, such a conflict cannot
498 // cause unsoundness, since this function is in scope no matter what.
499 // (The problem is that attempting to refer to a type named
500 // `__yoke_derive_require_yokeable` would instead refer to this function item
501 // and therefore fail.)
502 #[allow(dead_code)]
503 fn __yoke_derive_require_yokeable<
504 #yoke_lt: #yoke_lt,
505 T: yoke::Yokeable<#yoke_lt>,
506 >(_t: *const &#yoke_lt T) {}
507
508 match self {
509 #yokeable_checks
510 }
511 }
512 let output = unsafe { ::core::mem::transmute::<&#yoke_lt Self, &#yoke_lt Self::Output>(self) };
513 if false {
514 // Same deal as above.
515 #[allow(dead_code)]
516 fn __yoke_derive_require_static<
517 #yoke_lt: #yoke_lt,
518 T: 'static,
519 >(_t: *const &#yoke_lt T) {}
520
521 match output {
522 #output_checks
523 }
524 }
525 output
526 }
527 #[inline]
528 fn transform_owned(self) -> Self::Output {
529 unsafe { ::core::mem::transmute::<Self, Self::Output>(self) }
530 }
531 #[inline]
532 unsafe fn make(from: Self::Output) -> Self {
533 unsafe { ::core::mem::transmute::<Self::Output, Self>(from) }
534 }
535 #[inline]
536 fn transform_mut<F>(&#yoke_lt mut self, f: F)
537 where
538 F: 'static + for<#bound_lt> FnOnce(&#bound_lt mut Self::Output) {
539 let y = unsafe { &mut *(self as *mut Self as *mut Self::Output) };
540 f(y)
541 }
542 }
543 }
544}