compiler/rustc_error_codes/src/error_codes/E0038.md

   1 For any given trait `Trait` there may be a related _type_ called the _trait
   2 object type_ which is typically written as `dyn Trait`. In earlier editions of
   3 Rust, trait object types were written as plain `Trait` (just the name of the
   4 trait, written in type positions) but this was a bit too confusing, so we now
   5 write `dyn Trait`.
   6
   7 Some traits are not allowed to be used as trait object types. The traits that
   8 are allowed to be used as trait object types are called "object-safe" traits.
   9 Attempting to use a trait object type for a trait that is not object-safe will
  10 trigger error E0038.
  11
  12 Two general aspects of trait object types give rise to the restrictions:
  13
  14   1. Trait object types are dynamically sized types (DSTs), and trait objects of
  15      these types can only be accessed through pointers, such as `&dyn Trait` or
  16      `Box<dyn Trait>`. The size of such a pointer is known, but the size of the
  17      `dyn Trait` object pointed-to by the pointer is _opaque_ to code working
  18      with it, and different trait objects with the same trait object type may
  19      have different sizes.
  20
  21   2. The pointer used to access a trait object is paired with an extra pointer
  22      to a "virtual method table" or "vtable", which is used to implement dynamic
  23      dispatch to the object's implementations of the trait's methods. There is a
  24      single such vtable for each trait implementation, but different trait
  25      objects with the same trait object type may point to vtables from different
  26      implementations.
  27
  28 The specific conditions that violate object-safety follow, most of which relate
  29 to missing size information and vtable polymorphism arising from these aspects.
  30
  31 ### The trait requires `Self: Sized`
  32
  33 Traits that are declared as `Trait: Sized` or which otherwise inherit a
  34 constraint of `Self:Sized` are not object-safe.
  35
  36 The reasoning behind this is somewhat subtle. It derives from the fact that Rust
  37 requires (and defines) that every trait object type `dyn Trait` automatically
  38 implements `Trait`. Rust does this to simplify error reporting and ease
  39 interoperation between static and dynamic polymorphism. For example, this code
  40 works:
  41
  42 ```
  43 trait Trait {
  44 }
  45
  46 fn static_foo<T:Trait + ?Sized>(b: &T) {
  47 }
  48
  49 fn dynamic_bar(a: &dyn Trait) {
  50     static_foo(a)
  51 }
  52 ```
  53
  54 This code works because `dyn Trait`, if it exists, always implements `Trait`.
  55
  56 However as we know, any `dyn Trait` is also unsized, and so it can never
  57 implement a sized trait like `Trait:Sized`. So, rather than allow an exception
  58 to the rule that `dyn Trait` always implements `Trait`, Rust chooses to prohibit
  59 such a `dyn Trait` from existing at all.
  60
  61 Only unsized traits are considered object-safe.
  62
  63 Generally, `Self: Sized` is used to indicate that the trait should not be used
  64 as a trait object. If the trait comes from your own crate, consider removing
  65 this restriction.
  66
  67 ### Method references the `Self` type in its parameters or return type
  68
  69 This happens when a trait has a method like the following:
  70
  71 ```
  72 trait Trait {
  73     fn foo(&self) -> Self;
  74 }
  75
  76 impl Trait for String {
  77     fn foo(&self) -> Self {
  78         "hi".to_owned()
  79     }
  80 }
  81
  82 impl Trait for u8 {
  83     fn foo(&self) -> Self {
  84         1
  85     }
  86 }
  87 ```
  88
  89 (Note that `&self` and `&mut self` are okay, it's additional `Self` types which
  90 cause this problem.)
  91
  92 In such a case, the compiler cannot predict the return type of `foo()` in a
  93 situation like the following:
  94
  95 ```compile_fail,E0038
  96 trait Trait {
  97     fn foo(&self) -> Self;
  98 }
  99
 100 fn call_foo(x: Box<dyn Trait>) {
 101     let y = x.foo(); // What type is y?
 102     // ...
 103 }
 104 ```
 105
 106 If only some methods aren't object-safe, you can add a `where Self: Sized` bound
 107 on them to mark them as explicitly unavailable to trait objects. The
 108 functionality will still be available to all other implementers, including
 109 `Box<dyn Trait>` which is itself sized (assuming you `impl Trait for Box<dyn
 110 Trait>`).
 111
 112 ```
 113 trait Trait {
 114     fn foo(&self) -> Self where Self: Sized;
 115     // more functions
 116 }
 117 ```
 118
 119 Now, `foo()` can no longer be called on a trait object, but you will now be
 120 allowed to make a trait object, and that will be able to call any object-safe
 121 methods. With such a bound, one can still call `foo()` on types implementing
 122 that trait that aren't behind trait objects.
 123
 124 ### Method has generic type parameters
 125
 126 As mentioned before, trait objects contain pointers to method tables. So, if we
 127 have:
 128
 129 ```
 130 trait Trait {
 131     fn foo(&self);
 132 }
 133
 134 impl Trait for String {
 135     fn foo(&self) {
 136         // implementation 1
 137     }
 138 }
 139
 140 impl Trait for u8 {
 141     fn foo(&self) {
 142         // implementation 2
 143     }
 144 }
 145 // ...
 146 ```
 147
 148 At compile time each implementation of `Trait` will produce a table containing
 149 the various methods (and other items) related to the implementation, which will
 150 be used as the virtual method table for a `dyn Trait` object derived from that
 151 implementation.
 152
 153 This works fine, but when the method gains generic parameters, we can have a
 154 problem.
 155
 156 Usually, generic parameters get _monomorphized_. For example, if I have
 157
 158 ```
 159 fn foo<T>(x: T) {
 160     // ...
 161 }
 162 ```
 163
 164 The machine code for `foo::<u8>()`, `foo::<bool>()`, `foo::<String>()`, or any
 165 other type substitution is different. Hence the compiler generates the
 166 implementation on-demand. If you call `foo()` with a `bool` parameter, the
 167 compiler will only generate code for `foo::<bool>()`. When we have additional
 168 type parameters, the number of monomorphized implementations the compiler
 169 generates does not grow drastically, since the compiler will only generate an
 170 implementation if the function is called with unparameterized substitutions
 171 (i.e., substitutions where none of the substituted types are themselves
 172 parameterized).
 173
 174 However, with trait objects we have to make a table containing _every_ object
 175 that implements the trait. Now, if it has type parameters, we need to add
 176 implementations for every type that implements the trait, and there could
 177 theoretically be an infinite number of types.
 178
 179 For example, with:
 180
 181 ```
 182 trait Trait {
 183     fn foo<T>(&self, on: T);
 184     // more methods
 185 }
 186
 187 impl Trait for String {
 188     fn foo<T>(&self, on: T) {
 189         // implementation 1
 190     }
 191 }
 192
 193 impl Trait for u8 {
 194     fn foo<T>(&self, on: T) {
 195         // implementation 2
 196     }
 197 }
 198
 199 // 8 more implementations
 200 ```
 201
 202 Now, if we have the following code:
 203
 204 ```compile_fail,E0038
 205 # trait Trait { fn foo<T>(&self, on: T); }
 206 # impl Trait for String { fn foo<T>(&self, on: T) {} }
 207 # impl Trait for u8 { fn foo<T>(&self, on: T) {} }
 208 # impl Trait for bool { fn foo<T>(&self, on: T) {} }
 209 # // etc.
 210 fn call_foo(thing: Box<dyn Trait>) {
 211     thing.foo(true); // this could be any one of the 8 types above
 212     thing.foo(1);
 213     thing.foo("hello");
 214 }
 215 ```
 216
 217 We don't just need to create a table of all implementations of all methods of
 218 `Trait`, we need to create such a table, for each different type fed to
 219 `foo()`. In this case this turns out to be (10 types implementing `Trait`)\*(3
 220 types being fed to `foo()`) = 30 implementations!
 221
 222 With real world traits these numbers can grow drastically.
 223
 224 To fix this, it is suggested to use a `where Self: Sized` bound similar to the
 225 fix for the sub-error above if you do not intend to call the method with type
 226 parameters:
 227
 228 ```
 229 trait Trait {
 230     fn foo<T>(&self, on: T) where Self: Sized;
 231     // more methods
 232 }
 233 ```
 234
 235 If this is not an option, consider replacing the type parameter with another
 236 trait object (e.g., if `T: OtherTrait`, use `on: Box<dyn OtherTrait>`). If the
 237 number of types you intend to feed to this method is limited, consider manually
 238 listing out the methods of different types.
 239
 240 ### Method has no receiver
 241
 242 Methods that do not take a `self` parameter can't be called since there won't be
 243 a way to get a pointer to the method table for them.
 244
 245 ```
 246 trait Foo {
 247     fn foo() -> u8;
 248 }
 249 ```
 250
 251 This could be called as `<Foo as Foo>::foo()`, which would not be able to pick
 252 an implementation.
 253
 254 Adding a `Self: Sized` bound to these methods will generally make this compile.
 255
 256 ```
 257 trait Foo {
 258     fn foo() -> u8 where Self: Sized;
 259 }
 260 ```
 261
 262 ### Trait contains associated constants
 263
 264 Just like static functions, associated constants aren't stored on the method
 265 table. If the trait or any subtrait contain an associated constant, they cannot
 266 be made into an object.
 267
 268 ```compile_fail,E0038
 269 trait Foo {
 270     const X: i32;
 271 }
 272
 273 impl Foo {}
 274 ```
 275
 276 A simple workaround is to use a helper method instead:
 277
 278 ```
 279 trait Foo {
 280     fn x(&self) -> i32;
 281 }
 282 ```
 283
 284 ### Trait uses `Self` as a type parameter in the supertrait listing
 285
 286 This is similar to the second sub-error, but subtler. It happens in situations
 287 like the following:
 288
 289 ```compile_fail,E0038
 290 trait Super<A: ?Sized> {}
 291
 292 trait Trait: Super<Self> {
 293 }
 294
 295 struct Foo;
 296
 297 impl Super<Foo> for Foo{}
 298
 299 impl Trait for Foo {}
 300
 301 fn main() {
 302     let x: Box<dyn Trait>;
 303 }
 304 ```
 305
 306 Here, the supertrait might have methods as follows:
 307
 308 ```
 309 trait Super<A: ?Sized> {
 310     fn get_a(&self) -> &A; // note that this is object safe!
 311 }
 312 ```
 313
 314 If the trait `Trait` was deriving from something like `Super<String>` or
 315 `Super<T>` (where `Foo` itself is `Foo<T>`), this is okay, because given a type
 316 `get_a()` will definitely return an object of that type.
 317
 318 However, if it derives from `Super<Self>`, even though `Super` is object safe,
 319 the method `get_a()` would return an object of unknown type when called on the
 320 function. `Self` type parameters let us make object safe traits no longer safe,
 321 so they are forbidden when specifying supertraits.
 322
 323 There's no easy fix for this. Generally, code will need to be refactored so that
 324 you no longer need to derive from `Super<Self>`.