Documentation

Author: oli-obk

compiler/rustc_middle/src/ty/generics.rs

@@ -424,6 +424,8 @@ impl<'tcx> GenericPredicates<'tcx> {
         instantiated.spans.extend(self.predicates.iter().map(|(_, s)| s));
     }
 
+    /// Allow simple where bounds like `T: Debug`, but prevent any kind of
+    /// outlives bounds or uses of generic parameters on the right hand side.
     pub fn is_fully_generic_for_reflection(self) -> bool {
         struct ParamChecker;
         impl<'tcx> TypeVisitor<TyCtxt<'tcx>> for ParamChecker {

compiler/rustc_middle/src/ty/mod.rs

@@ -280,9 +280,9 @@ pub struct ImplTraitHeader<'tcx> {
 }
 
 impl<'tcx> ImplTraitHeader<'tcx> {
-    /// For trait impls, checks whether the type and trait only have generic parameters in their
-    /// arguments and only uses each generic param once, too.
-    /// Pessimistic analysis, so it will reject projection types (except for weak aliases)
+    /// For trait impls, checks whether the type and trait only have generic lifetime parameters in their
+    /// arguments and only use any generic param once.
+    /// This is a pessimistic analysis, so it will reject projection types (except for weak aliases)
     /// and other types that may be actually ok. We can allow more in the future.
     pub fn is_fully_generic_for_reflection(self) -> bool {
         #[derive(Default)]

library/core/src/any.rs

@@ -907,10 +907,8 @@ pub const fn type_name_of_val<T: ?Sized>(_val: &T) -> &'static str {
     type_name::<T>()
 }
 
-/// Trait that is automatically implemented for all `dyn Trait<'b, C> + 'a`
-/// * without assoc type bounds,
-/// * adds `T: 'a + 'b` requirements, and
-/// * `C: 'static` requirements on all params of the dyn trait.
+/// Trait that is automatically implemented for all `dyn Trait<'b, C> + 'a` without assoc type bounds.
+/// It implicitly adds `T: 'a` requirements, which is otherwise not representable on `Pointee`.
 ///
 /// This is required for `try_as_dyn` to be able to soundly convert non-static
 /// types to `dyn Trait`.
@@ -921,14 +919,52 @@ pub const fn type_name_of_val<T: ?Sized>(_val: &T) -> &'static str {
 ///
 #[unstable(feature = "try_as_dyn", issue = "144361")]
 #[lang = "try_as_dyn"]
+#[rustc_deny_explicit_impl]
 pub trait TryAsDynCompatible<T>: ptr::Pointee<Metadata = ptr::DynMetadata<Self>> {}
 
-/// Returns `Some(&U)` if `T` can be coerced to the trait object type `U`. Otherwise, it returns `None`.
+/// Returns `Some(&U)` if `T` can be coerced to the dyn trait type `U`. Otherwise, it returns `None`.
+///
+/// # Run-time failures
+///
+/// There are multiple ways to get a `None`, and you need to manually analyze which one it is, as the
+/// compiler does not provide any help here.
+///
+/// * `T` does not implement `Trait` at all,
+/// * `T`'s impl for `Trait` is not fully generic,
+/// * `T`'s impl for `Trait` is a builtin impl (e.g. `dyn Debug` implements `Debug`)
+///
+/// ## Fully generic impls
+///
+/// `try_as_dyn` does not have access to lifetime information, thus it cannot differentiate between
+/// `'static`, other lifetimes, and can't reason about outlives bounds on impls. Thus we can only accept
+/// impls that do not have `'static` lifetimes, or outlives bounds of any kind. You can have simple
+/// trait bounds, and the compiler will transitively only use impls of those simple trait bounds that satisfy
+/// the same rules as the main trait you're converting to.
+///
+/// An example of a legal impl is:
+///
+/// ```rust,ignore
+/// impl<'a, 'b, T: Debug, U: Display> Trait<'a, T> for Type<'b, U> {}
+/// ```
+///
+/// Impls without generic parameters at all are also legal, as long as they contain no `'static` lifetimes.
+///
+/// ## Builtin impls
+///
+/// Builtin impls (like `impl Debug for dyn Debug`) have various obscure rules and often are not fully generic.
+/// To simplify reasoning about what is allowed and what not, all builtin impls are rejected and will neither
+/// directly nor indirectly contribute to a `Some` result.
 ///
 /// # Compile-time failures
-/// Determining whether `T` can be coerced to the trait object type `U` requires compiler trait resolution.
+/// Determining whether `T` can be coerced to the dyn trait type `U` requires compiler trait resolution.
 /// In some cases, that resolution can exceed the recursion limit,
 /// and compilation will fail instead of this function returning `None`.
+///
+/// The input type `T` must outlive the lifetime `'a` on the `dyn Trait + 'a`.
+/// This is basically the same rule that forbids `let x: &dyn Trait + 'static = &&some_local_variable;`
+/// So if you see borrow check errors around `try_as_dyn`, think about whether a normal unsizing
+/// coercion would be possible at all if you were using concrete types or had bounds on the input type.
+///
 /// # Examples
 ///
 /// ```rust
@@ -973,37 +1009,7 @@ pub const fn try_as_dyn<T, U: TryAsDynCompatible<T> + ?Sized>(t: &T) -> Option<&
 
 /// Returns `Some(&mut U)` if `T` can be coerced to the trait object type `U`. Otherwise, it returns `None`.
 ///
-/// # Compile-time failures
-/// Determining whether `T` can be coerced to the trait object type `U` requires compiler trait resolution.
-/// In some cases, that resolution can exceed the recursion limit,
-/// and compilation will fail instead of this function returning `None`.
-/// # Examples
-///
-/// ```rust
-/// #![feature(try_as_dyn)]
-///
-/// use core::any::try_as_dyn_mut;
-///
-/// trait Animal {
-///     fn speak(&self) -> &'static str;
-/// }
-///
-/// struct Dog;
-/// impl Animal for Dog {
-///     fn speak(&self) -> &'static str { "woof" }
-/// }
-///
-/// struct Rock; // does not implement Animal
-///
-/// let mut dog = Dog;
-/// let mut rock = Rock;
-///
-/// let as_animal: Option<&mut dyn Animal> = try_as_dyn_mut::<Dog, dyn Animal>(&mut dog);
-/// assert_eq!(as_animal.unwrap().speak(), "woof");
-///
-/// let not_an_animal: Option<&mut dyn Animal> = try_as_dyn_mut::<Rock, dyn Animal>(&mut rock);
-/// assert!(not_an_animal.is_none());
-/// ```
+/// See documentation of [try_as_dyn] for details about the behaviour and limitations.
 #[must_use]
 #[unstable(feature = "try_as_dyn", issue = "144361")]
 pub const fn try_as_dyn_mut<T, U: TryAsDynCompatible<T> + ?Sized>(t: &mut T) -> Option<&mut U> {

tests/ui/any/reject_manual_impl.rs

@@ -0,0 +1,29 @@
+#![feature(try_as_dyn)]
+
+use std::any::TryAsDynCompatible;
+
+struct Foo(dyn Iterator<Item = u32>);
+
+impl TryAsDynCompatible<u32> for Foo {}
+//~^ ERROR: explicit impls for the `TryAsDynCompatible` trait are not permitted
+
+struct Bar(dyn Iterator<Item = u32>);
+
+impl<T> TryAsDynCompatible<T> for Bar {}
+//~^ ERROR: explicit impls for the `TryAsDynCompatible` trait are not permitted
+
+struct Baz;
+
+impl<T> TryAsDynCompatible<T> for Baz {}
+//~^ ERROR: explicit impls for the `TryAsDynCompatible` trait are not permitted
+
+trait Trait {}
+
+impl<T> TryAsDynCompatible<T> for dyn Trait {}
+//~^ ERROR: explicit impls for the `TryAsDynCompatible` trait are not permitted
+
+impl TryAsDynCompatible<u32> for dyn Iterator<Item = u32> {}
+//~^ ERROR: explicit impls for the `TryAsDynCompatible` trait are not permitted
+//~| ERROR: only traits defined in the current crate can be implemented for arbitrary types
+
+fn main() {}

tests/ui/any/reject_manual_impl.stderr

@@ -0,0 +1,47 @@
+error[E0322]: explicit impls for the `TryAsDynCompatible` trait are not permitted
+  --> $DIR/reject_manual_impl.rs:7:1
+   |
+LL | impl TryAsDynCompatible<u32> for Foo {}
+   | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ impl of `TryAsDynCompatible` not allowed
+
+error[E0322]: explicit impls for the `TryAsDynCompatible` trait are not permitted
+  --> $DIR/reject_manual_impl.rs:12:1
+   |
+LL | impl<T> TryAsDynCompatible<T> for Bar {}
+   | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ impl of `TryAsDynCompatible` not allowed
+
+error[E0322]: explicit impls for the `TryAsDynCompatible` trait are not permitted
+  --> $DIR/reject_manual_impl.rs:17:1
+   |
+LL | impl<T> TryAsDynCompatible<T> for Baz {}
+   | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ impl of `TryAsDynCompatible` not allowed
+
+error[E0322]: explicit impls for the `TryAsDynCompatible` trait are not permitted
+  --> $DIR/reject_manual_impl.rs:22:1
+   |
+LL | impl<T> TryAsDynCompatible<T> for dyn Trait {}
+   | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ impl of `TryAsDynCompatible` not allowed
+
+error[E0322]: explicit impls for the `TryAsDynCompatible` trait are not permitted
+  --> $DIR/reject_manual_impl.rs:25:1
+   |
+LL | impl TryAsDynCompatible<u32> for dyn Iterator<Item = u32> {}
+   | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ impl of `TryAsDynCompatible` not allowed
+
+error[E0117]: only traits defined in the current crate can be implemented for arbitrary types
+  --> $DIR/reject_manual_impl.rs:25:1
+   |
+LL | impl TryAsDynCompatible<u32> for dyn Iterator<Item = u32> {}
+   | ^^^^^-----------------------^^^^^------------------------
+   |      |                           |
+   |      |                           `dyn Iterator<Item = u32>` is not defined in the current crate
+   |      `u32` is not defined in the current crate
+   |
+   = note: impl doesn't have any local type before any uncovered type parameters
+   = note: for more information see https://doc.rust-lang.org/reference/items/implementations.html#orphan-rules
+   = note: define and implement a trait or new type instead
+
+error: aborting due to 6 previous errors
+
+Some errors have detailed explanations: E0117, E0322.
+For more information about an error, try `rustc --explain E0117`.