|
| 1 | +# `arbitrary_self_types` |
| 2 | + |
| 3 | +The tracking issue for this feature is: [#44874] |
| 4 | + |
| 5 | +[#38788]: https://github.com/rust-lang/rust/issues/44874 |
| 6 | + |
| 7 | +------------------------ |
| 8 | + |
| 9 | +Allows any type implementing `core::ops::Receiver<Target=T>` to be used as the type |
| 10 | +of `self` in a method belonging to `T`. |
| 11 | + |
| 12 | +For example, |
| 13 | + |
| 14 | +```rust |
| 15 | +#![feature(arbitrary_self_types)] |
| 16 | + |
| 17 | +struct A; |
| 18 | + |
| 19 | +impl A { |
| 20 | + fn f(self: SmartPtr<Self>) -> i32 { 1 } // note self type |
| 21 | +} |
| 22 | + |
| 23 | +struct SmartPtr<T>(T); |
| 24 | + |
| 25 | +impl<T> core::ops::Receiver for SmartPtr<T> { |
| 26 | + type Target = T; |
| 27 | +} |
| 28 | + |
| 29 | +fn main() { |
| 30 | + let smart_ptr = SmartPtr(A); |
| 31 | + assert_eq!(smart_ptr.f(), 1); |
| 32 | +} |
| 33 | +``` |
| 34 | + |
| 35 | +The `Receiver` trait has a blanket implementation for all `T: Deref`, so in fact |
| 36 | +things like this work too: |
| 37 | + |
| 38 | +```rust |
| 39 | +#![feature(arbitrary_self_types)] |
| 40 | + |
| 41 | +use std::rc::Rc; |
| 42 | + |
| 43 | +struct A; |
| 44 | + |
| 45 | +impl A { |
| 46 | + fn f(self: Rc<Self>) -> i32 { 1 } // Rc implements Deref |
| 47 | +} |
| 48 | + |
| 49 | +fn main() { |
| 50 | + let smart_ptr = Rc::new(A); |
| 51 | + assert_eq!(smart_ptr.f(), 1); |
| 52 | +} |
| 53 | +``` |
| 54 | + |
| 55 | +Interestingly, that works even without the `arbitrary_self_types` feature |
| 56 | +- but that's because certain types are _effectively_ hard coded, including |
| 57 | +`Rc`. ("Hard coding" isn't quite true; they use a lang-item called |
| 58 | +`LegacyReceiver` to denote their special-ness in this way). With the |
| 59 | +`arbitrary_self_types` feature, their special-ness goes away, and custom |
| 60 | +smart pointers can achieve the same. |
| 61 | + |
| 62 | +## Changes to method lookup |
| 63 | + |
| 64 | +Method lookup previously used to work by stepping through the `Deref` |
| 65 | +chain then using the resulting list of steps in two different ways: |
| 66 | + |
| 67 | +* To identify types that might contribute methods via their `impl` |
| 68 | + blocks (inherent methods) or via traits |
| 69 | +* To identify the types that the method receiver (`a` in the above |
| 70 | + examples) can be converted to. |
| 71 | + |
| 72 | +With this feature, these lists are created by instead stepping through |
| 73 | +the `Receiver` chain. However, a note is kept about whether the type |
| 74 | +can be reached also via the `Deref` chain. |
| 75 | + |
| 76 | +The full chain (via `Receiver` hops) is used for the first purpose |
| 77 | +(identifying relevant `impl` blocks and traits); whereas the shorter |
| 78 | +list (reachable via `Deref`) is used for the second purpose. That's |
| 79 | +because, to convert the method target (`a` in `a.b()`) to the self |
| 80 | +type, Rust may need to be able to use `Deref::deref`. Type conversions, |
| 81 | +then, can only proceed as far as the end of the `Deref` chain whereas |
| 82 | +the longer `Receiver` chain can be used to explore more places where |
| 83 | +useful methods might reside. |
| 84 | + |
| 85 | +## Types suitable for use as smart pointers |
| 86 | + |
| 87 | +This feature allows the creation of customised smart pointers - for example |
| 88 | +your own equivalent to `Rc` or `Box` with whatever capabilities you like. |
| 89 | +Those smart pointers can either implement `Deref` (if it's safe to |
| 90 | +create a reference to the referent) or `Receiver` (if it isn't). |
| 91 | + |
| 92 | +Either way, smart pointer types should mostly _avoid having methods_. |
| 93 | +Calling methods on a smart pointer leads to ambiguity about whether you're |
| 94 | +aiming for a method on the pointer, or on the referent. |
| 95 | + |
| 96 | +Best practice is therefore to put smart pointer functionality into |
| 97 | +associated functions instead - that's what's done in all the smart pointer |
| 98 | +types within Rust's standard library which implement `Receiver`. |
| 99 | + |
| 100 | +If you choose to add any methods to your smart pointer type, your users |
| 101 | +may run into errors from deshadowing, as described in the next section. |
| 102 | + |
| 103 | +## Avoiding shadowing |
| 104 | + |
| 105 | +With or without this feature, Rust emits an error if it finds two method |
| 106 | +candidates, like this: |
| 107 | + |
| 108 | +```rust,compile_fail |
| 109 | +use std::pin::Pin; |
| 110 | +use std::pin::pin; |
| 111 | +
|
| 112 | +struct A; |
| 113 | +
|
| 114 | +impl A { |
| 115 | + fn get_ref(self: Pin<&A>) {} |
| 116 | +} |
| 117 | +
|
| 118 | +fn main() { |
| 119 | + let pinned_a: Pin<&A> = pin!(A).as_ref(); |
| 120 | + let pinned_a: Pin<&A> = pinned_a.as_ref(); |
| 121 | + pinned_a.get_ref(); // error[E0034]: multiple applicable items in scope |
| 122 | +} |
| 123 | +``` |
| 124 | + |
| 125 | +(this is why Rust's smart pointers are mostly carefully designed to avoid |
| 126 | +having methods at all, and shouldn't add new methods in future.) |
| 127 | + |
| 128 | +With `arbitrary_self_types`, we take care to spot some other kinds of |
| 129 | +conflict: |
| 130 | + |
| 131 | +```rust,compile_fail |
| 132 | +#![feature(arbitrary_self_types)] |
| 133 | +
|
| 134 | +use std::pin::Pin; |
| 135 | +use std::pin::pin; |
| 136 | +
|
| 137 | +struct A; |
| 138 | +
|
| 139 | +impl A { |
| 140 | + fn get_ref(self: &Pin<&A>) {} // note &Pin |
| 141 | +} |
| 142 | +
|
| 143 | +fn main() { |
| 144 | + let pinned_a: Pin<&mut A> = pin!(A); |
| 145 | + let pinned_a: Pin<&A> = pinned_a.as_ref(); |
| 146 | + pinned_a.get_ref(); |
| 147 | +} |
| 148 | +``` |
| 149 | + |
| 150 | +This is to guard against the case where an inner (referent) type has a |
| 151 | +method of a given name, taking the smart pointer by reference, and then |
| 152 | +the smart pointer implementer adds a similar method taking self by value. |
| 153 | +As noted in the previous section, the safe option is simply |
| 154 | +not to add methods to smart pointers, and then these errors can't occur. |
0 commit comments