From fc784ea823a64ab2cbddf48ea215ab94dff2e883 Mon Sep 17 00:00:00 2001 From: boats Date: Wed, 21 Feb 2018 13:53:53 -0800 Subject: [PATCH 01/14] Detailed design of immovability API. --- text/0000-pin_and_move.md | 313 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 313 insertions(+) create mode 100644 text/0000-pin_and_move.md diff --git a/text/0000-pin_and_move.md b/text/0000-pin_and_move.md new file mode 100644 index 00000000000..cefd074fc1c --- /dev/null +++ b/text/0000-pin_and_move.md @@ -0,0 +1,313 @@ +- Feature Name: pin_and_move +- Start Date: 2018-02-19 +- RFC PR: (leave this empty) +- Rust Issue: (leave this empty) + +# Summary +[summary]: #summary + +Introduce new APIs to libcore / libstd to serve as safe abstractions for data +which cannot be safely moved around. + +# Motivation +[motivation]: #motivation + +Why are we doing this? What use cases does it support? What is the expected outcome? + +# Explanation +[explanation]: #explanation + +## The `Move` auto trait + +This new auto trait is added to the `core::marker` and `std::marker` modules: + +```rust +pub unsafe auto trait Move { } +``` + +A type implements `Move` if in its stack representation, it contains internal +references to other positions within its strack representation. Nearly every +type in Rust is `Move`. + +Positive impls of `Move` are added for types which contain pointers to generic +types, but do not contain those types in their stack representation, e.g: + +```rust +unsafe impl<'a, T: ?Sized> Move for &'a T { } +unsafe impl<'a, T: ?Sized> Move for &'a mut T { } +unsafe impl<'a, T: ?Sized> Move for Box { } +unsafe impl<"a, T> Move for Vec { } +// etc +``` + +This trait is a lang item, but only to generate negative impls for certain +generators. Unlike previous `?Move` proposals, and unlike some traits like +`Sized` and `Copy`, this trait does not impose any particular semantics on +types that do or don't implement it. + +## The stability marker traits + +A hierarchy of marker traits for smart pointer types is added to `core::marker` +and `std::marker`. These exist to provide a shared language for talking about +the guarantees that different smart pointers provide. This enables both the +kinds of self-referential support we talk about later in this RFC and other +APIs like rental and owning-ref. + +### `Own` and `Share` + +```rust +unsafe trait Own: Deref { } +unsafe trait Share: Deref + Clone { } +``` + +These two traits are for smart pointers which implement some form of ownership +construct. + +- **Own** implies that this type has unique ownership over the data which it + dereferences to. That is, unless the data is moved out of the smart pointer, + when this pointer is destroyed, so too will that data. Examples of `Own` + types are `Box`, `Vec` and `String`. +- **Share** implies that this type has shared ownership over the data which it + dereferences to. It implies `Clone`, and every type it is `Clone`d it must + continue to refer to the same data; it cannot perform deep clones of that + data. Examples of `Share` + +These traits are mutually exclusive - it would be a logic error to implement +both of them for a single type. We retain the liberty to assume that no type +ever does implement both - we could upgrade this from a logic error to +undefined behavior, we could make changes that would break any code that +implements both traits for the same type. + +### `StableDeref` and `StableDerefMut` + +```rust +unsafe trait StableDeref: Deref { } +unsafe trait StableDerefMut: StableDeref + DerefMut { } +``` + +These two traits are for any pointers which guarantee that the type they +dereference to is at a stable address. That is, moving the pointer does not +move the type being addressed. + +- **StableDeref** implies that the referenced data will not move if you move + this type or dereference it *immutably*. Types that implement this include + `Box`, both reference types, `Rc`, `Arc`, `Vec`, and `String`. + Pretty much everything in std that implements `Deref` implements + `StableDeref`. +- **StableDerefMut** implies the same guarantees as `StableDeref`, but also + guarantees that dereferencing a *mutable* reference will not cause the + referenced data to change addresses. Because of this, it also implies + `DerefMut`. Examples of type that implement this include `&mut T`, `Box`, + and `Vec`. + +Note that `StableDerefMut` does not imply that taking a mutable reference to +the smart pointer will not cause the referenced data to move. For example, +calling `push` on a `Vec` can cause the slice it dereferences to to change +locations. Its only obtaining a mutable reference to the target data which is +guaranteed not to relocate it. + +Note also that this RFC does not propose implementing `StableDerefMut` for +`String`. This is to be forward compatible with the static string optimization, +an optimization which allows values of `&'static str` to be converted to +`String` without incurring a heap allocation. A component of this optimization +would cause `String` to allocate when dereferencing to an `&mut str` if the +backing data would otherwise be in rodata. + +### Notes on existing ecosystem traits + +These traits supplant certain traits in the ecosystem which already provide +similar guarantees. In particular, the [stable-deref][stable-deref] crate +provides a similar bit different hierarchy. The differences are: + +- That crate draws no distinction between `StableDeref` and `StableDerefMut`. + This does not leave forward compatibility for the static string optimization + mentioned previously. +- That crate has no equivalent to the `Own` trait, which is necessary for some + APIs using internal references. +- That crate has a `StableDerefClone` type, which is equivalent to the bound + `Share + StableDeref` in our system. + +If the hierarchy proposed in this RFC becomes stable, all users are encouraged +to migrate from that crate to the standard library traits. + +## The `Pin` type + +The `Pin` type is a wrapper around a mutable reference. If the type it +references is `!Move`, the `Pin` type guarantees that the referenced data will +never be moved again. It has a relatively small API. It is added to both +`std::mem` and `core::mem`. + +```rust +struct Pin<'a, T: ?Sized + 'a> { + data: &'a mut T, +} + +impl<'a, T: ?Sized + Move> Pin<'a, T> { + pub fn new(data: &'a mut T) -> Pin<'a, T>; +} + +impl<'a, T: ?Sized> Pin<'a, T> { + pub unsafe fn new_unchecked(data: &'a mut T) -> Pin<'a, T>; + + pub unsafe fn get_mut(this: Pin<'a, T>) -> &'a mut T; + + pub fn borrow<'b>(this: &'b mut Pin<'a, T>) -> Pin<'b, T>; +} + +impl<'a, T: ?Sized> Deref for Pin<'a, T> { + type Target = T; +} + +impl<'a, T: ?Sized + Move> DerefMut for Pin<'a, T> { } +``` + +For types which implement `Move`, `Pin` is essentially the same as an `&mut T`. +But for types which do not, the conversion between `&mut T` and `Pin` is +unsafe (however, `Pin` can be easily immutably dereferenced, even for `!Move` +types). + +The contract on the unsafe part of `Pin`s API is that a Pin cannot be +constructed if the data it references would ever move again, and that it cannot +be converted into a mutable reference if the data might ever be moved out of +that reference. In other words, if you have a `Pin` containing data which does +not implement `Move`, you have a guarantee that that data will never move. + +The next two subsections describe safe APIs for constructing a `Pin` of data +which cannot be moved - one in the heap, and one in the stack. + +### Pinning to the heap: The `Anchor` type + +The `Anchor` wrapper takes a type that implements `StableDeref` and `Own`, and +prevents users from moving data out of that unless it implements `Move`. It is +added to `std::mem` and `core::mem`. + +```rust +struct Anchor { + ptr: T, +} + +impl Anchor { + pub fn new(ptr: T) -> Anchor; + + pub unsafe fn get_mut(this: &mut Anchor) -> &mut T; + + pub unsafe fn into_inner_unchecked(this: Anchor) -> T; + + pub fn pin<'a>(this: &'a mut Anchor) -> Pin<'a, T::Target>; +} + +impl Anchor where T::Target: Move { + pub fn into_inner(this: Anchor) -> T; +} + +impl Deref for Anchor { + type Target = T; +} + +impl DerefMut for Anchor where T::Target: Move { } +``` + +Because `Anchor` implements `StableDeref` and `Own`, and it is not safe to get +an `&mut T` if the target of `T ` does not implement `Move`, an anchor +guarantees that the target of `T` will never move again. This satisfies the +safety constraints of `Pin`, allowing a user to construct a `Pin` from an +anchored pointer. + +Because the data is anchored into the heap, you can move the anchor around +without moving the data itself. This makes anchor a very flexible way to handle +immovable data, at the cost of a heap allocation. + +An example use: + +```rust +let mut anchor = Anchor::new(Box::new(immovable_data)); +let pin = Anchor::pin(&mut anchor); +``` + +### Pinning to the stack: `Pin::stack` and `pinned` + +Data can also be pinned to the stack. This avoids the heap allocation, but the +pin must not outlive the data being pinned, and the API is less convenient. + +First, the pinned function, added to `std::mem` and `core::mem`: + +```rust +pub struct StackPinned<'a, T: ?Sized> { + _marker: PhantomData<&'a mut &'a ()>, + data: T +} + +pub fn pinned<'a, T>(data: T) -> StackPinned<'a, T> { + StackPinned { + data, _marker: PhantomData, + } +} +``` + +Second, this constructor is added to `Pin`: + +```rust +impl<'a, T: ?Sized> Pin<'a, T> { + pub fn stack(data: &'a mut StackPinned<'a, T>) -> Pin<'a, T>; +} +``` + +Because the lifetime of the `StackPinned` and the lifetime of the reference to +it are bound together, the StackPinned wrapper is functionally moved (and with +it the data inside it) into the Pin. Thus, even though the data is allocated on +the stack, it is pinned to its location for the remainder of its scope. + +```rust +let mut data = mem::pinned(immovable_data); +let pin = Pin::stack(&mut data); +``` + +## Immovable generators + +Today, the unstable generators feature has an option to create generators which +contain references that live across yield points - these are, in effect, +internal references into the generator's state machine. Because internal +references are invalidated if the type is moved, these kinds of generators +("immovable generators") are currently unsafe to create. + +Once the arbitrary_self_types feature becomes object safe, we will make three +changes to the generator API: + +1. We will change the `resume` method to take self by `self: Pin` instead + of `&mut self`. +2. We will implement `!Move` for the anonymous type of an immovable generator. +3. We will make it safe to define an immovable generator. + +This is an example of how the APIs in this RFC allow for self-referential data +types to be created safely. + +## Stabilization planning + +This RFC proposes a large API addition, and so it is broken down into four +separate feature flags, which can be stabilized in stages: + +1. `stable_deref` - to control the smart pointer trait hierarchy - StableDeref, + StableDerefMut, Own, and Share. +2. `pin_and_move` - to control the `Move` auto trait and the `Pin` type. These + two components only make sense working together. +3. `anchor` - to control the `Anchor` struct, pinning to the heap. +4. `stack_pinning` - to control the APIs related to stack pinning. + +# Drawbacks +[drawbacks]: #drawbacks + +Why should we *not* do this? + +# Rationale and alternatives +[alternatives]: #alternatives + +- Why is this design the best in the space of possible designs? +- What other designs have been considered and what is the rationale for not choosing them? +- What is the impact of not doing this? + +# Unresolved questions +[unresolved]: #unresolved-questions + +- What parts of the design do you expect to resolve through the RFC process before this gets merged? +- What parts of the design do you expect to resolve through the implementation of this feature before stabilization? +- What related issues do you consider out of scope for this RFC that could be addressed in the future independently of the solution that comes out of this RFC? From 99b9222450a63fae575168b1d6a7142af2af1500 Mon Sep 17 00:00:00 2001 From: boats Date: Wed, 21 Feb 2018 14:01:41 -0800 Subject: [PATCH 02/14] Anchor requires StableDerefMut. --- derefs.dot | 12 ++++++++++++ derefs.png | Bin 0 -> 26876 bytes features.dot | 5 +++++ features.png | Bin 0 -> 20313 bytes text/0000-pin_and_move.md | 8 ++++---- 5 files changed, 21 insertions(+), 4 deletions(-) create mode 100644 derefs.dot create mode 100644 derefs.png create mode 100644 features.dot create mode 100644 features.png diff --git a/derefs.dot b/derefs.dot new file mode 100644 index 00000000000..73f4a2f7f4b --- /dev/null +++ b/derefs.dot @@ -0,0 +1,12 @@ +digraph { + Deref [shape=box] + Deref -> DerefMut + Deref -> StableDeref + Deref -> Own + Deref -> Share + DerefMut [shape=box] + DerefMut -> StableDerefMut + Clone [shape=box] + Clone -> Share + StableDeref -> StableDerefMut +} diff --git a/derefs.png b/derefs.png new file mode 100644 index 0000000000000000000000000000000000000000..b5aad5fe2cde34824b4886df4621fe601a2fe216 GIT binary patch literal 26876 zcmb@uc{tYH`vv-tkO)N?LTHdmghZKzN+ObE2q{Cx$UKy(GAEIeBr=myW+GE5WGZEf zk~twEoV9y@zw7*Q&UMcD!f5>bl(@>-IF%m|vm$+1V)3 zy7cJry~txBLTuJgi(cm(n+QzN-#D6|zww*RoXw_V{l~H`+J714KmJk>(*Av;_0HHx z7IvfNz=`O1_m$pf`ChUIc}NtnC!z zSbaS#tY)Atq9{D+)*)Hh-V!F>QA(p|W690y*DC|oY$yy*+E*LF7qPTBcbUguo5IY@ zy!n8G-zbOh5nc=WgYRC8HhKyQ{C0b5{`b$6q3`j~Yhiry52j}|VtD)e`<)iY&iwCF znAiM!KvCf^cJY6|N|X4%KI;F^KNNQK#0lm@yt!TeO+(3No?UQoaH#xJbU7+AveKnd zCNMZS`Rq%(=8ld#-zr>2H+DYdV0ZoYhF#;{ey08V_v6olo<0>Tb{@XwI8fU^l;~UQ zPsesK?wk}FIUQR_A#7FJgiEaHtscM6u9Q^zp8FHCYZL93WtD( znyRs}k$ik8mn1`ZdAa^eJDy+D(~g7ntUuija9sr7 zWu6di(_Wv&J^L?x^oxvSX}mA3v%kBskr7|Cw({z#{)vh34LdX);!e~q@6;_>zM zotfz7t_$a>F85w63>VZnRTvi+=Wstjo35du;pg03aB{MFfztOxJW=`5@6W25sUGAc zhJNUua*LDqm7|;+?a1EzWZrlEjet@5P_8v=)?C#U#$MEM4_$V2q+(T6_D|4AU%Tr9 z4)#&+#owzbuWM?O9z9apFS}z0-P(=274Ge~-Ln41Icw{iPtEJTF3gVRyJu(~KP5ZS zQ?~ZRi4%C9`qXdVzwa+BOIC}Z_RE^iefI3Kxffe#yo~SiAxdRWk8#fU_ix`!TOJ*@ z?9Aa&5nzp%volSrN! zLN4XJo!vT0T2|I=cHU2)KK=OgY=?k=K%UE}-r&&Cz}Tl}^-WE|h%hsAb1DiRf|k{^ zElr!^_vzV1^NBA-Zh!xXef|1%3k!WuW?6pzJ{DH|j%!xjwC$Ll-bTv&gBM=E2G@A} z9=lQIIVT__L|;@?^k;FhA}Kl9U(uh|bn*8%#X6^T?Iw}eRe@`x?%uue^QXgoId87$ z?Z-1Zu6V!v-^Wx@kxbol_66hc@bJe%N5LQ_ZdzGc*^i$-nf8`@ZxQgC{}x;D;@jwG z$nw&nvYHwlK2FubVq3hF{qp;9vCu;e&-@qjE#5}P$KR~1R0!n|qo$>$%_}IV=_&Ix zH8s7udhN!(;npXT#&h#SiPbeVtBZ?^9WGz4{@Gvch)DXxxBisvuF>CBH#vh$Z=bw! zWj{qhi0zU4^mmFe57*H2JcpQ>N`d>kckfIuUJMQhpgDj3e4AzF>0ILikpZL6<{a*M z&!5xyS+A~Ml=1o_N;&uEXMcODjkUE|^Fu|UUAw9ieV5M+xX60`&iZX{V`D>E@tvX9 znivlxQ7M#y^`W@6&uil&OG`JeUcEZR?0s`{URT9o0am}$bFbzvetuJ2 z_TOO;j5+$$;_XICWvTl#rF7x#hx&SYE-tRLv@{B9`vQmPIfb%2{FA>qQj;z;Jz&B= zNTGdU(|e4H*}UZV5H|MrPw41u2nq^f38@hh7S5RRY9CI?Shi$J8vFcTAjrJEv#0vo z+gPy+jd9ko+2K3~H^#)o6uM2Bg>}-<&^$bqsh3~!xFfjqvw2()*`S;3yIA=6B372? zDhl3To|`bDp`)vAZQa0g@QRnsJ@eX7D$3ufI==SQ*w|P>85ypwuC70S1|oWQ=I*oK zn-zzua`|LBThjyC>Xu|RG0WyHS!Z9aYkhK}?t!dlhD$iI-JY%jn_z7I!0Q_ugoK0? ze0=1Plb$+#J9_D3UXtS6*GN}S##XIfuW6>gfB*ih*<@1L)WkeD(OvyEb}u=zc$9OM zepGocUm~3x9BJ>t8=9J%`v#8KD@csAnP_UR+i%-NbMWB7!otEW{QOr()lr?#38slLPOIVsJUNl5 zYH2C7Zu0?3lGb(YWL18oqxt#yI8jsTPFBt!tFIrU@NCvGQBha@{3y?DI@h6isGdBz zo_f_PvdhiQT7^YLjyzGO9JG{!`>I77vv5O6ft*orjQA@`E0M&5~B_(PS#k+Rx z`t#>c<%bXJwY9YiJ?BKq7bgxrw{E{Vdfhr3(TL-!WMIIRdi-7xaKIy%(T+b8C6ikE z`t>e{g0zod_u{s1Ie3tpii+w-bJD8&_wPqWM*8vj{Gqyg_wM!U*ZuC@<90j5+bMSM zHV$!RZ!e#fl~vq9R}t)1z?Jc?{*uXZWkp4*&M6#$ymgg~$*Eh{uX%r8+8=d%vz!-) zhlj_{nHd!o6`Eq#Ns&&A!zwEE1+p%;u}@gPjyOA%&&l$|b<;ylbqKM5hYz=0>UzHB z^7qE8xw(5$4{H?-z8fJS=h-Gvp^km)U@nkWJS^Lj0qm zSUaPv0g3{iJrfTN4R!e5$Z2V9z5k6Jg>aHQ|DnyN+62pvmf3ucDyx9Y7Jn86>$(qRVM^W~Ogo0H>Yz-0VpE#|mG08Rs7qK0dzl78a5Q z>w>gblNe>6{yTp;ARyo&pr(V9lahu8g*exy0ek{7Y zqpGT^8K*F3ptOaK&&$uKWTdLDjxIetoz(Jmyoczyxw#u3$Z~UX za)!kRn%=%+sHulN(gL!2^ypFj+qWUl3kn)4EB#7KOHo#Cj#^F*Hp#DSy{e$FGT-D| z82(|)F1@TRNLd$~9(>!a?CvhTnvO0S`R;~_0FvCJ#ktALcY?KjC_;x0-5=#(s99(f z4PF1XzP=JwAkX&mezIIGEv(q8swas)48RsS17*=Au9H=tK5W0%kW`9~}_fb0(h#*|9cCQ0<(BMUBh- zxerOobOFJ^g1dJ!Dk>@()=^P@&U+!Z^mSyPJ>WD*pP!%K_u~gW-tBc=-DRE#Q?{EV z313a!FZThJj+KMsI%?uWz#qf9s1SbTpmXgRr}RtR#1PiiE}J>!68G*p7tSkt6Ce8s zTgGw7O;p6Bypd!SdNflSf>s#=f;F|ZX2^m+r>Cp2CvRLf7oiWRE_56a_4(^|$m>t! z=z(^$1cfCf1HZn#y?*ni5(=%y+(Z~QMEKNHjp#3uFtxW}ttyrm);@Ufz_LAq{qNF} zm_wg}VVMW})YR0^si~{zjXK5Hw)*Ula&XA|Lg%5YYW9=^**>VeT<-VyXS%Bjl`dNY(Wcb`xktvtthTqe7n)xE z2=9E@*;&HO%&a-N6=91WEwV;>@aD8(0UYwPwSmp-3ZJ=J}h*z z^m^oQegQ$jm|_m|xMBhjd!jQUA|BH(FE7(GGZXyOj7BbJK;kB#JpYz06awu4J&MA0 z_IfYODB?kLj7ow?kwee$qo?d3I=7~qTuAfe&8`-Q;>~uPc<}mVuTMxAx0D&`hhd$S zZpg+xRc+}yVis@M9zTBU!1JW1*kv^6`gMB43Ll=|zkkOaa1_|Qc{2+a7sCyeDx4Yj zU03MN1*Pvu*S!f~Cx|>lw{EkameA`o?c~1kaV9A#shokGfrEqR4;(ybKJ%l6B&bfu z1N<99rdrhalG4)XeOH#G7#SH0!`sfiwCk?I2j;m>8at1DWIYxuQZv{P-TtCCy4c*6 za)E;uS&E*XUZLd5xTxFDb6dA<;};cWL9s)Qun25iLE}{2-OY35$`$%`>%PmZyZHS1 za|d*K#KXhds3_b!(af?#}p!NZi!MC#VXytb0=d)YxOTPE2|r;=+^ZC$Lg1P zNOn5*oEdtbz{W(9N#wfr6?L;ATTh{k>~KvclV{E zXJ%)IaS#pFqVCPiI2+`hqq4HGiN1T6bAEAA$I5DF=hHYD%0m>i9CINyFgg-vfQjkX zta*jwhp*p<^}%YGqK&ea&his5EOuUlC3yWIufa;~5QcfUmf=7T(9^XoM(0)ee2c_{QXX=rL_wNZ}d|}@ke)~4t z0U4R9w{O=P8yj28;)4!(%+Qy4%w9v~UdJOtBbS&^kn=Wr$BDkd!2l7X;=Ty^Wv!CT zYfes1dFZGJAQ6b7$NE>FHt|mREp<$nofHO1d<9bVQC9oVYBsmF`agNHqx{d;knLjl zklQgauiD$$Yier1Zdu41%(4LY;#8PVeXSAh-udUa)8)%kttaFOl%>8(0RjpJEkYoV z%k%BoJK4m?PV7{*eL5Az=6_w(d%^jT+fNF@-8@i3R{G#UL7X|8jx0qWt4_y%%`8E7 zkq;h(Z##CU51C5^1P8V_`0rmYoRyK#>SY;5L01b43pQ3(MLRpY*8@{XYB#;Sy@y}< z(;2GiaHC#rMO%0?Jp8-N&7<*HRW$6{W@ZAN+H5&#Y1aXz8yXu!LEKory0#i$uf`>7 zJ6+Z)(dx7yKp1r5f#LR0YKAEm&>;KV`%yIC_?)~;Xp+%R6oOsl>ozm4k z2jWTn*s*GW(&ke4%Q=EO4UZgILpBTOoo(Yrv)WM3pR=oQ#X`uJb+q$Prgp(NzviiCTSlyxmdF2>+n8Z;_N_=a#a2jc-NzIFKDUHU6V+ zpv5TW_Atn*N?-g|Kbv7rz2NbYU=h2@8Sbdxy^7m2wjHWkq&t~hAS>w zTMlPLmztaJ#zEwUpFe*p96r37oVF-OzmN#2_oZk-y4kjH7;$-?ThvgDd&P{43H z$M7lufX|)6mY-~EJyVQ?NQDqCZYHng@zYiMYEG>Vqa zzw~L}hqkuIg@p%ll7&*@;yAbtI6TZsyK(d8SA5(WW@cX-enA#`%P)nFhH5dpfOi;N zK+61@o!tg{>Ff0T;P>yUD2RXi0xKj;A*2Xj~KlyeMP0D$bU$% zbo()ZsAeR-hN`M-`}Xb2kUg!Zr>gTrGes?e*YUQd`|H=Qo3FD9oM3tR5asrb@s z*QiI@(l-@@l9Q8_k@5`dZtv>IjEK4ia*wns|99OM9~hc%G6K``DDUk-9+B!>!JPT&3Lge2 zN6rWy=2*3A6=`XY961sv>$(3?a&k+Vrz`2yDe+&9|L%E=b9g;8^mTzvXLG*AF~Wd% zm$(ufpm=;{;SRdn=c+sUgq4z5Hf-1MyK_fR@X1NhoXnl7(&{NEJ?4K|_?yHgCZ0fn z9_;H=prm0X2PY>_fc(-?II7BvXE<~AY{it<0+PGNUgOd}8S7|Q#D{fvvE&*W>h<(A z?d4DIN!dH`oY>i2=;)7j>w43W4jN-C(j1>T)8LY&dP-Yc5yvU>GWY2^AJwsX##QKQ zkwAbYvy7*oO-1Q`28jF#{z)b=R(TVeezXXxZ(Wan zKV3#)1U~sDn(!xd4bSPL_S{5{ECEz5V`|$WkLC?LnV6s=y zGWKnWx#nneTJri$QI5^8JGy<;CQ1z_>XpeJ}chc;-5TEz>@z(qoFYYYmAy|t&=j;mHUz>@6rXWXGeG5xu zQIYf>{X9ROuX@@zNspgAnX45DsvBqlN8die%a$?tcYgZ(rAvQnl~P9>m;buw3}l4j zjDE;E^Nc)f*K;f7t5>h)zi%JG;k=cSViD$|YP5I$;*-1aX+M5gA``7W@!(LD3tMY* zb7gMDGJ{`O#N!-LkwNJ34H5^Y=kuODs|NT91Es>j!6D%!L+e(+6My$^S;2G$Y9P`l z*Up%cXHTChIyi`)Jb6;oX;A&o{QRqqj*Vyl!B5Rv6Vk%vO4h0Uhj^KhuG%#vp&Xs` zo_x^gB3UC*j()GLD~W|NJUXfaSW8d&)YWyXqCy^D*pcUMR5Uu9jz1wL$OCA4R@2hn zQW5Bv5m3&RaR420>&1)T+$Yv>ad5O1`itwx12jB8_lo*MN5^&~6>O*P=u$4kA`LW6 zK2Jin6*_=ruznH;{^313C({~@4FWMohkHR1pS4ewI9ExLah=$FkT3TFzL{ROU-rTZ z4(PMYrrWxzszGDFXT0PpI>uwVcTX%G@?N+N0CNNlI1Yss=;ne4X73sr`1kDDL#=?m z?bKZ#sZ-Up3h#3L%(39~IPBp1%s`ZY?B2qH&Yh0Wdxn+!hxWU%&o5708M)RpRE>4p zwAc8xeZ^93j-1X(Jv}|bxL`+U#l@dl&(TsF+vb8?_%4*-VcGI%HG0yhJ9mNrZp_fV z5haI^aA+9nzke=tOdhjN!xygt=}lUMnw*#EI!~x6GA<*JJGxg{hsGy>3PYRX7!w>N z4)Nf*RVyu0V;!1>(Sj+&HNmQP?%WBB%(EiA{H|SuZ+r9ht+t^dBL$3inxlU)qJ*nA zIw*)1fIRa!jtuk#8p@C1Va5LleRQWevqAbK9nFq*CS_-b5sJ^mXWk-=PfgW5=FT0n zZ*OAsD|}>WsIO*C2B~kY0>nN)TJ`z%?b}n;%2#_lJD{!febpk zxxM|=M^ByYL>wA^l8E+%=Bk1pxD9h0{U1O}1g#h1eU3s(1xXJ!KwDQ= z*Ot!-1&Am>aS~SRk+RO8$^6Y;TU#r-f4|=Ry&vsD7a(a75iIAIsMCH>=U<9l)}ma` zP84ouV|Z%aF8pUe;X|$2L+4I!OcwsT70%D0384=6<9#hgx`uyPekp| zNR;D2hj~p`cy&ZwHG)-maqa!<4wF5yVAoXJCCdATL(uvQ#e+P=t>|c*zft@w^rBbB^aBC|6}PYm?LG#% z3W=XTv(*#-sI!rDCa5C5+h zAdKmftt}C51Iz2?PF)mJK0dR*dE~K4g%6-)_LXFzs|pmkL}uQI)3!s(xeF&0g=3Ti zq8@^Q!t*xq}MkMAT%YlakuwTW)!&Brn(O43tzV&0i z#oFcBT;HU}k7>X$5DAHN+SoDl5+tO%x(xK3A+JYn0nyPL7JiSfg<4lo z#3ce-1F~q=w6FqBKl0T;r-|?C#1$V|sq6Hv6JHcBUD^$;Cj9eDdqIFs#1qAseKQd5 z9oej`tnVlNf8wn&(!%qL$mH*Y<^Kr5l^=;&BL4Y(YfzjETpk*oT_p5|ba?RQ%uZ-m2bGXRu#z-5FDJcOyOZJ5u} z!YfeRA|fKdZGEMD?>~bSC+#k2H-R5uKVbrzdx)&TA>%CcrMuhI#^$r7yFS(=UP(;n z%$XagiUR!nNnOgjH!5#kpM?C8&)1%@a%JqJc6!rNMn+cFZZK~BSeyJ6WAK4^zUJm; zzwGQin|XLFB2e!$+N0zTle|C(W&obQ;Bes+s*Mvf@9XcsD(AhB_S&isQACK-KjSZZ zfA+mv1$M`*BkRo1U%yVq>#(`3p{MstOf)GQg0vqeX|wT#UAMt_32R6VSmr9gamSy1 ziV***{}Tsb6i^1{(fwND6c;&pT%*hqner*r2KTK zfdHIwNV>{ArO00)eH#rVu#pau=d=|Y-Wh~KI;=Qb*%+*#XR-0{ zWPh0Rxpg!Je|H%8W*hh#gjzCKla!^Nl#@G|_~h<~hK1RL3g@P$pBX)_HdW!d(wHcp zi1wko-1{Esy@`el@kKd^F$wMesd2T(xmj6{!Lo;>o=DV03V%H`Z3TjcjgvDyZ)xAb zeaW?L{q>>xyK7NW9YJ{AKj^v+&9ovKRn(RKk&&C&m&%5Q8$7n!{5YWS5?qgns3T`) z;)^sP)RA3ak9e)d=N&+`ing-7y`X`o2s=U$L!Mo?%=H?xe;7c@{y|swc7Ad34f0Df z8+;aqcl`MAk1+#aL7ge&J^U*EYmjg5mckE)g+ zxwqvQ9sJPRDkv{6|K{DhZ!)*4z6}mWLe3l>899mW`Um39P|afp1TyTM6+k0-1>UX= z_1mDpn*E^CUuLYKgniE;vR67fI$e<3aCjP0Z1oz`#7+rc;Fb5$Ahbm0>Ah&%A7^JD z2a%MFCh0D(tjBAYL#a_9ZCk<3T7j2G93O^E3U%c;@=Y>Cznp=Fc4Q8##yBw=Kd55u z6HD!Cs;ac^Zf-0TE-*iMVh5gdMX(M>fz|~n5^xR_d&~-VM%^|5@_=dNwzIP{ArO}r zdsoWmcIuJ`v)Fq9_1p^Wxdgl#c(C(kW=i50-#fA%}Jc%7a{>$ z(CH)pBtv3^g3a1F)${hQ_{Dlq*rag+YxPxT-H_&kLq||5w?pkFtpTXj>UptIGO+KnN?4z`&JhEG%#4V@8AFX-u9`PYS>O2vCB&fF7f+qxrTrI zh(w5n@f^Ifj!&*pb;Y9R=Y9@uM0VgE9vGU>PD6wmby4 z@Bz@IC_GsL$d#-cKEx7hZdjMzijFz$_`UsYkX{Jgqg#A=e`k(ikrMFs4wT5QJk#of z-gmO%w9Vh>Hlo>=@%eiIaG8}d@*!odZFg}Dn54q++O#y}pDsWd_)J*AkRao?;>g7; zs~r}IiUc=ISP>kAPRHA~bcIuxxc9RpHa$V|HyAE&1&&vaj+g;h9@ob+(;YEt>HSQk4YsKWYUK&_`ds-(ymKA8b#;0mo~jLc#;E z+w4F>Ba*`tY2$LQBLlTzf*^G}DvrE@YMF-WOhV-7kt6AyHa+&byMxjXqi}zJpAdpm z|FE!-LrhEz>XsVfxCrYhO-DyJ)?2}cKPA>6n100UdrGzm|zu}YS@wJ zz@uit$S1cMA5ilqX4lh;O}v`>uu&RuqEtA8RoDeFs70Di63~G+f)r7O%+*}s>x*(< zv2-~1wA7^2`P7l{2X5mc*O5Ta+uNUjg&_%SG;P7BIMh2ekQoTWQ=>dQRBf5D3twwO zGRrOixr9ZQ+Zk@YTLkB)%fy$vVDc>SY++6uFY@zm`7F<0baHg$2lIq|+_HAGel6DQ^0fI^8AeCorFz3iEMC0M<<$*i3#cEM)}IJXTga6*ua1?AnpvZl&Z;ZIJngD zBO-={TRN|B=TE``=TKm4Y&>^S`vL&f4o^={WKNIK#hA}lsWzQCtQ0OuYc|%hg;j>T>dhs8OoILxhRwL0pKi{w(_S8qf)YfQxx=Y=4em|fzHzz6ge$+&I!Namr z;t#ny38wfys};H6vow49LrY5%%8bNFnJKcn3i25>HT4fDmN28LqV<}|^<4^qJasoN zPRMy4%grRL$tB}!+ve!0a~tXuSx10h1}3IcADwyz!49XQrGK+T2a{w3Y@(zf+x3(l z0q1cWG#sL#4HW%8Ny(T+X3^6}j~yHKXO??tS{)=g;uOIruZai1>G{_4yJW0HHH@qM z{7p^)VpWKS0}R^OblCLHtT^{>;HNc|u+7*Nnd9?+{;>EN*z3X|CJA~Z73p~cr5H+A z!uW1P0!shZmu9NSKj6-$jcp|^h&}UJ^1ymQjZj12h2?7qJOawz;3so>27E(Dv2tYH z(AmSBH}7_)fBl`RPGTNrJhH+lE2>6UAV5<+1P@&Fq6D2XwE|kF%-Q){x7Is3J8$*& z_Ab6W6mA&%F6Q#kdsd2!=kH6&yHD)ir~_*&+b_D2l8KUd12JV4=e|lRY6Wm2S(hKE zj*1UVPDVhMAm*u$FYQgt_x#RAIbx)UiixGqy2Bp8E$IS=rQrSa*P69||4uhS$vLH= zzHJk@4@u?BL@>X81*^wbAHhb)L|mP!P^v; zUkd*z@rc429P9b{Qtv5W?;$roxW2rWW;>m1U9mI7$jh|-Y%Brd z|2ewc{`^cb6nC&_xV7zo`>(Ahb#&N^H^UJDiRKkNIQUMtJr^(awu>V04jUS7exE3B zGCCdRA*s`DvK{>f80^U7O$`l@>((~I32|LT0Q#2M*vF@ZK1;=y9zZSjs~c$Gg)k8a z=@QB3d}~JepP=WiC=nFD7ccfBpddEb40g1&y@oYhLFErHE|`8p!%*}+112jAr?V&B zvD^7xD}UdPL2J(+#$Uu9@69t^g%=+^demX+>)}s_!rY%H^CMHQrK1bxN<3yh+?mVQ z`0m{lh+SeGINBDzHe=GV?NCzI++8#J**)#UsN~c~*9X^YsPWn2Sdv|)Bfj=Ptj3s)v!LA7e45hT#W7Ia| z`;8kns3@Vlvc+Ali%m->5hZw3xFsxFH;NeQ+b%Y-jcNg(H|c-!T_(DiO6Qe+9hPSdIY>sDqyISqeWri}gBBPE+rT|jl*07J18W-?gI(y_dg zQxiRQ&}${YoCS)Q9Dn=vtzeY8N}|`V8JiTJ7I*~PPYbq%y_oS)&}7NT!WVR0tz3zo%Kr}S zw{c?8qs$<@xSAwKtWw9uE>Ymhxt(Aj4G$R(nQAD9wyiM&6x;sKI04LuRt{I5^^&Lya zLS|*BX2*}WkbE`1Y6lU{lmT}Jdva1zwo$h1-8-2*t@lo6mWu*@w-%V3g`GVR8G=F~ zTm#PhTf2R3KbrX|#6wQJGz2zx`QU9bmp*rOaZzCIYOi!X<$K}6h5Ro!Z{59nW?Wq7 zwrjU**>cg@GiRvMmWwLhmNRPgjF*kbcDx8x-E#r3i9#U^l9rGPe2q|fx5OL;?WjL~ zp9c&wR*Q-Pf-Se@PEL+pnAK#fu{T(I)BdVJ=#Toq!K4J*m(PDs=sHP=2@M^IaDq_WT!IHWPbHl7F=}T9 zUDz~Y_~22;*;BneZ10+zS#UlXj8q*R#bD~dLZM_)+AuP%7z5q`Tm0--S1pGLeoJg3g{@;-VibUFqnle3A^OnxExh~%^S|Ei#R^`>kVw_5S5%OwXFYflo9cjzY&3jPYqF<1 ze^;knLX<|{z1v_Fgk<$5hav5FyXz99I_uWnnfc<95_4ehIO)sV;drD=*JTi>f=8P2 zu;bV&o6m)QD|^j)W;%-mI?lR$>R}rO$P|^5I{jlGCQ@=Dcb)v7`3bZZD`C?{g$`6_ z&YW>@bydsM%g&IM0zih2U=9>dMypVjk?oj3Mlf>jBTh|K5cy0?7*{mwv;B4K%d09d5>3*CXSv0XmT(_GB3S70;gKru2RLw(THw zLPA0qYUrCK+0qE4qrm&+i#vAh%9NRF`t>tsF=xS})BDpshq5wxC}tS9`@J+gnqWED zPNff<0?3YGc-|yn9;H^mZ=QfUvd;BfnAr)rKAdnp7({ylh^u96%nQ*t4D1H%#-&|< z?MD@antmHkQvU9@AE6xbUG}0@K%;f1yS5w73y}BL18F zPmPYk#VE96M=)tTKyi`2ms$Z7Nqd(QY6t2);TMq+v;p({b1zu`@W>4ReAavcgc^)h zA!xoHHGhNG;U3ZC3A7%bq{i?ci+h?0nhL*)eMb=lpsK@=Cm6kGU-b`y*&>we=SPTy#k@S~X$0j136- zKkF;V9j#pBGHY+mq*ceU8Yhvet>7BD9T}-LG&&9A3=B(cFKo|(vp8>UeH4f){kLLW zZEc6Xs*&_)YtN|vl~b}AIqL39vfh{wvj59yZDRw;CV$AJ)J+jQm-HEZ{YU`R+40Y@ zglmB{Cx3pWs1?{c6#zO4L_h2jttg^Bf48+g5(^S1aX|_t7M{KMelgq&#SZ<{dyGrt z2r&kc2`&OfG9xfJr~+qQ`t15T>;yz03G_t(NZa91N9vcb?IILVwD)Ozq$F)PJWKnS zI7I!BLDkQmy=Q1-lo=K>-87%ci;NU2Ymzv7M_u;i%UX;)D1sU&Fpd|thgqN4-=P9A zoUN6oi)SNxsxRr8jAy5c!QpEml~^-+YP;P1J-W)d`AtXJ1; z*e>zIkSqCqhUVVV@zRAwp`AOgCMOFbWjOvGJM+oZI!Id;2=Yg7g*?zZ#Ww)oFw=i2KX+}NlQXyVuR_3Jg%oqq5J3`XmwuYjbl!@Q^?)KSun z){?$tL$VK$EGsAH4Pu)6m}e>^BJy2keRW#~-ko$+9v(8l;q1os6hCN(aw~r?{~eNF zNuQ;rq?)1_KwTz2ImtIMx50iA#~o}q?B%;t?a;RWSzeqJ^ZY$#u$I#g2Di;bc0$6f z1(DwjWkP1ss8ZCh2%-`~!Vw;Q0xY!av=>J*bAOI~693e0(O9ww{&ouSrh4$rH}Kj} zYs{Db&NEc7-B16FR$g0Q|2ljDFWy7-sIEVZQw?>B+1%XxfV4DxoYyh7w5qQ?Z2}^S zsHkWqx?LFeJJa6U!@Eur8cMmU)nrjJ0~sm98*L<$aqRnkni~=CBcw;jS5GH4ZAM?s zhiZ5Y68*QZ(|H)Kin@oROa?>s3my2&7e;m!mXt`nsejF=bC1mDVkD7__mW8vOeD0q zUpHvM&(p%+3)!b)+T!VP1UV=4_2zV)9lMQ+pKHh3+S!Gph<=6H)$)VXk#ALC_ov7J zB|1wqtq!KDtWf7WLYc+|LjHt|#NBiZ(rCyb4aU5D=o8j1=+E4MSOjN^ME zq&!XH7=^7Pf}#bD*An8Vu+C;w^*e~@;p7OpuVX<4-_ExGuNNTt%^2`Z8!A7{Q;$G+ zT;_Qagzz9Ky5aR}GSzizAjn^%+Ni=Of#iCOa7{YzFzvV)WF-M)1|^ObJQ+A+&B`xd zHscL~VUgOddH*^*N<3ho4C~I{)`iyCpx!dFQ8nzf=R|HujfI$KfV~;a4 zkNuBi6Bu!?TBrh?J8l_3d$1SlajV-$R#Y?+yiHN~To0x+$@mhuf#ZpC3Fvfld6Ad6k ztMM->`?g;SqiEM{R)?PwPPO{>_Lz=blM|h}CKq|O-=o}6QNo5KV_&0z%89>^A&`hF zcq84EEiPWHa4q@wXnKu*Td|{7n9G)M|8;(!m>53=<~9uw zMUT-GoWyLLzf7>$n{<%V5Z8z0SLT^PZr&o}b(DIXo>YyyO1N_2ctenJ6^kLl`_at)?Z_3f>$t^aaJ=f#=vx2(bZ# zm(I`2+X88TC^#vpsc*8q_cuT0vI)Jqo!cLNBJ|KuA%fA~2yEX@i?Ry;6B*0HsW=}| zTPiNp>VWnXnq;gjm=AOue&65SONNl`;NlX9ik56OgImOP4MchHsZb{rOnpx|i78(T_d^qZWs5AJST{ z+orQFI>yG~fZ=9nCJ%Vb2%#quz5HDR*_^JUqr=H)BMJ3lHu2o(qbY^ni~C9US+TOr zjTtB6C_-z51Y;3+947)&*QV#TpYODCr%E11o**))U2l09a?;kVTerx`@xo0=mDm&v zQ5|0&h0lIwvX>9`i@qs0!#X`-X5K@UNL)nYU}2S8n$aN_O`u*0&z(7vauQYvGwcuf zDoBmk&1>K+lX12T>vYn<5)*F)al;`efmI`xaxmhrKs$}PIl=xLgdgeed*y!s=4Uj! z&ABG>8VNG&xDenP5`fa3w>LQ@Q*&xGY#|d`$j9OPsjI6i{O7O*1SV5ZpkiKOG&VuT zrHafR!hNp)aSk{7gdYkB*k$`2&N9fmc{VdEr=viw zVDb5A%eeKpwd?4#+w&Y7?<|AtZrjm}n&cOHFK@OB>nUWU(BBq3RWzx*fm(WN1Ma(E zo)+KyppxcK>4S?80vgVL7k?A&EYto!3anujR3&%=jO;ad zpqe~eTmhN;&|Q(Eef#J(KwvUuxlQ>=qd_OB|k<7Q8X~qU5N_r zw)A&Yq7iQPxZHU4O`l-3hj<~>c<9l{h&9>!{QULp?d^~c`o0$|e`#)}lo|I^)T*3Hh&re$U-pE|`3@;FH^lj@6YfHVk3%!l47xqSe))?_lzcH}&L%KGWk zr}}sA4&zn=AOYgCDlV3>UQ?y*(PuPp(4a8F1xP~y?F$B!>d#6OV{}76ZLO+h zfkBA8B`olP=)ZJNopRhEfkaF?7ZNxisX3&b$dGxl7iBVfM4~aW+!P8H+lAsAdYLt_ zu1^tw132^tyz-WfAw|q|WyZ|edN!;g@%QeTigG+WnNIm4OJBgmLF@nO>lh0~gr*yl z7!Gt~R1yrUE5`#6{r%s+cl6(V42i^n&*QPZ*u8h;rV_vjV&h`lv?=+;iw=SNKb&Ro z??fN%7p6f#EJF@V1qYXu9E8VhOYB>WkJTkiP0h}ZzjRHQQp{|BgcOX{5FKOxa-KDl zAS$v}X8XoOeiUuPi?bc__mRZWUG)zRwoOb|qC#SlmP5jl1;@1bZPQv**u7pxVGc!q!T^=W0Oastu>nW4_qZ9f|ySI^VVd! z%2oO?x5fGMB(V^S5$GU~?(zHpmJg@3;)ZF7et*`!ED&&|57Y63C7VAm0mQMO?M2uO zps)KPX{AKZFB?&%A$11y>hFo}5R@zg$1Oa@CTmMe1q{9dX*r4C1L0{me69EL{@bA}hN>5r%e+@RIWn_>G7T6e8_ikfVQm;@mP30bTmN~RI_AD(u zT@ioP-PQH>uEus!>*fFcT(w$PiTF3d`FJ*mG zjh?@3Z6N0ZEoQD!mE%+RoVg^b%0o%K5*>Bt_n87vX$i+1fQ-MI6EEC`7hcB;H~sg* z4S1n8Ua0Wj3m=J^uTG<5sz}?(%O5afCqemmQ;RwNfh&eAP_Ruw;DSI{)%%S_iQb)& z?Lrpg?89N{Hns>Br3G3BalIgq<{8F+Z|qGM$hk{J*0Ok$WQ|}zWO-m!XiP?Kt{P@1 zk+2-$Nk9;n9~;^5-zUjBOGU>#;*~I(>`8Tl{o~OVtd}e{tye?)>= zl+-sRiJE^)qdVUDFx3r*(6uG*uJJXG=0oMUkKt=dtZ@~rA5SrrRsNPAe_a#cwMl{Z zJrPYIJDEYH(h_2GzS7SRC5{&~buCfa>hZRGhc906U>#AMw*2pjnAt9PaN@TP|NWK^ zzvUlMyzKkmm)%r+FMSi9H=%XdnFIy+j-TDGz1ord0g*m_RT_H_%UX6N|9e1rl*1a{ zHvb^8Aan**m-bI<8O@=@tAN-F&i!vU6NMUQoPf+emb#1U)ve;{m z28+y@x@G0rjQ5mrgOG%Bn^oiWZ=IJmF;ON2F(Y=BfF*E0n4zvk&^e+z60H>ladsb0 zpUL%!amKm9h9bep{XnS%gO<*GIQHL{k!BG027ajmE$#?1A1oc}QI(~{Kl}lMI5nWk zgG{e||ebFr|94E>ItH65k{ry*K_m*N=+3S{UPhL-`I8uakeA6fVnw%s@>+)z3pOyl$^FwtBc1 zAE|WV87FWFeANox-m-1hl3d)}NiCMB@r6U#(b(vtDc20LRq=Pa!t7{MTRwcCM*5$d zaK<#5QgRE~MC?-~oGh3|-@P55tDf@V$}}((4BGtB4Sjumm2){b(8CvyA_MSVpk^{M zGPGdVj*sU8zBLHAA<|q513Y4uWl- zfQ!C93ItiZ%|}N)4t`iDfAJ63@s!t{6IIA;r!M?FMo<*Knsq_fS8p@8u0ef0 zn3P0C`VnDaC3IwDTExicU0^IQ77&b`J02Dm!41^TDniti1AF!ALW`hXJHQJeb zIVlAsk7tiZB^x~rE;9-M-8ASVJ@;c^U{#fE~IuhiG_oK;g3BrEnaBa-J&PH0Vf%G{8~vXo5uf;%bIhn4&v_ zGD`z>uy6=pF5$|>?Ex&m&I>g<`-ufrRVm@#BqtqoPhiw3U&6cBsSOGeA$YMFxTj#NNGbU3+mrj&6y-wS1{qC8y2!X8 zp7k8AE5J=DWL#zc{*5RusaI=I!gHGf?vj3y+!jV`XbA~Su%E*&A&8-tr%#`f-Rj-8 z{+9~rIS2=aYlHB)X*oG46P2Ny;-an-hWPPTeGwqkw#;e`NCCujLFQb}pI1oIA{IKg z<@q629-iZ2gX)Pj9M#BI1cu@v1mMPp9zZ&E+*KxuG5zvmTLU6_TSu!xQK&(9JiR=m zNvMBZY)IxUz^w%X*nTiceQa`4I0kp6yaro>9VTZU3M4x&U3dl8&>s;%wc=B`Ys7I# z$W>5zxHXFaBe3-3z9C%qHLRznG(p4#m=OkWR|fJoxoh$%1|@Kari{4w1Dw}pGK+&u zAXh%Xp2SFT!!RNF0qE@kLvQGx+Hr-^62VaJ|LEylz93M&GP+6O=*C1l&Y?O@j;D#vzm!TBU6pd^Pe_H-pIHsnKT3;2=k?t@ z=XrXbJ&&hV|KI=n{aoI+|LbQ9?w9P;0l}}LD~puUG6%-N>Fdrb6W5z3iEbvi2QgWQ zX_@Vx^n_BoNXN~FoC01Pwns3bO3>eIUNK8lNNw;CwzG>AVWL`r6Q1<6SwHIRRAinG zLLn`zB{-tj?0FN!bDsVCKyfo`$PBDYI9BqT;~V+*+Oeza{^KGyZOsKpn{=jZGjNnC zS(#iQ7-=#s40#%nO>1_IrcHz=&}2PhJx+21zU1%sTfhEtYk2Rs!RRPkHzk4P>WqAE z3p6RTbR26)FuPtpGHpK}pDJH-kAkf>mX`mdRE9M77-HS?mF}>X==;P0dbmg4{%%;(GGyC9HB%Rcpmymm}? z?pamG>F3w_UO6&`lit^4t!05GVUewE@Z!;p+J5)KIx-9NB;CoA16(w!{_?r2nUp~x zY}t%tPI2?*->FG6q)vd_<7d}HR+)bFRbg$VqublLfx^(1AKbOdWc&elU?I6&{;2pP z_61|t9Z6RiQ9q@<6%`d@yqxUqA79y?QA6ZuyvW{VTN87p zvTYkcizJyRWmGi{S66G@J?Jkzevt#kC1xpxny0GIZfUYou*#}I$;?Mj1R28cS{dR& z9ln!cqA(@43n;Y;xt%zx^2eK|Ce*4)U`Soh`tZE${`z;(+M(o!OW`P4XS?+dIhxcD zOW4Wjen`Fw^b5g##Vs8o=!xUp_{E6CctXdJPBVpGf+!hi>ozy~IUxH7vs~b8p@RpI ztY#c~H9gjXnnjBh6^ge2&OGMs7FFP@#(9MxaQ5GR+cqLzGkX43{nVTL0h)YJ=dr2q za~Im%kL2y#tqhuo+6b~Rme5>4Ku!%Ih66VSSGc*wGJp9{-o?Z~Zx;zENYUoJn5BXo z8ZOy8IoUZl)PCsy8{x>VxBlVW0H6YSR?v{zl+Qjpki4fmVg6i2_b?@6Isp2p8a<3Y zbs=B##6w?}T@T`pU{k0OZ&#Va6F}aCL^`=uDC*|FZDGRcJorV~<3OqNO^y9evv(d* zlc9q4Ml9hS6cp4+sE9A1Qs(NSoR%IEA{?h4&4IZ(cH~GUvtcpL7^`n)ef@P&OOO9$ z1sjVw<{y)U+Pg@XYx#yjY$5K*Om}SCCc{mnTWhmHq2(j4s7m>BPEOCcd<*!15qlTe z+2z9DX1BNd9ZN~M&W!9qFsx6O)9L#2aw~|=1J&L&dOoW%k6mfoZlXQXow=$&!2zw~ z8S43j3@LA3Nld!_c28ARRdIxtOGpvw1Zo0J)F(Uvr25zRUCW;M5ZN; z8a>*-AiUYE_p;5~zpKf>8S)anTwJOdR6RmN3#(tpzHhNAGv70D=k2b%n0OK`f(j2^ z_Ebhz^5RjBB&o>|Ys=zhP;3;;R77ri$Muz)Rq6S#fOZ!Bmhz}ri`(j3;^jw(ww<%{ z1aQ)q(@(7w#{wdpigg&!=OIr(Xbo-x+CooHv9Rbp*))^PB!K3VEw5?*BE~E7aCh5- z2RBs3!OY=EilVV2g3q;tBvWZ)38G(U(|)!g8|SfNiu|&~tE4<)FgR;KrN;mw z(zXe}ct!{w{qZ^H0e@%b$<{1a`8ficg$kVC7rW$CPN=86A%B-shx?Iy=)wKWG7RbD z2jo_D>1&NR)38Y*m82{0ETgH-iri9KfmFd&VslN|VC{Xb@bc5GZJnKQR;{7K_OP-) zXI&=%Jn4fS^3t7&SQ2<`Y=aoiZVwe2C6LB!~csA%~n zIBT%wz)UjE1kxm$HeMr5Q0N*xsFo2AR0T!_4Pnays(hhM0L%WO?4>%FiF~Ne1*POMJb=*YYA+a_ zmYMPJdP(d_=cy0d+7``=(Z1F3Y?2@D#KSaleZhAtPvuqVE%5iBhSAPC{0+52eQ)sk zbu5^sV}h}r3j)j0LHDnmH(ddRK$dGl9}cHoo^H;sZ|KlLy%R&PKcTUSssNCbGTOj$znY9ra^BsI=|ksWwJAbr?0~sA-|foo{#52INh1%5 z&j?6PPfLp#&76eGEt}gpSt}9noiTR+R9D_+( z!=@7(touL6Zsti?OE2fCtfWv7Q!S~P;@p3pl(+X4&CSJCY8Cy15!t#VDyik>=K9d5 z|6hf;XPy@i>udxa^xrYNUCPFGm}FVo)>nGi5Z3a_63y}b0Q=G;-5nsKv+Rajy@ zsK*Y72pV^F_hi-s7!);qz-vzqD7(U}o@oD(H&o#kvWL1V|KV=BwO|r1V3VUuJZOQt zy3RMbBj!3iXA?6f|R7#$-t$B4JS)q2~64lON7Evj*>;Va|EABXD;l%%a~jWh$T|6 zknUalJga0M`tF|qn161{`Ip%+iE=Bvxc_#Q6LlB`1T!zIsn=82DB>zA8f{(O7;f-d zxK7c0-&2y(gv)vW$10%crRb_mBH83d>Ba&YibX@4uC3$WpF-sj_NKNJFQw2rg;Zm-1c zb-8@#O#lP=6l?+AJwVhB9@knN$EFe5=F_^v?SAb6g8PBJQ~ zRVWrx^!WpqySPLXV?d1AK6M_VQ-{miG#BVW@^JTq{Th=&2S+3lX(zvZror+>s?4$O z@$WyG!C)^IIW{7pL%_JLIBq>LtE5NMbBS@(i&3TKiu>}63@!9=w)`qVT(gY6TM1zX z|K@1&sCeQ03%5aeMQ$`SDWIYe`KRx8G}_?v7xhlPp2mRYXVy&iQ=M|2`nZe0~BIuIx`lvqLxfL$rj_K5batiE)!9a+pJ ztINX0yKspyEfQehE20R=>;woF*;f{IvxlWSUkyo*%3Fz4?$1Ttm{dD786tKV#NEUx zC5|VD{I}QB1kxgU?gxJNfO8hWoxWSH`LRUKvAB+4?-FD^0mbZ&-yC1II9^aRFs77! z5xT<~PD2!#;l{@5d~;}f(s~gvYw&pKNF&3?R%_ETVY3gGhws?Fow_R|iUi3Mb`_V* z=1$9eIX&rx8kAOHaF+oJucGumxixyUqFg@CWVs;fJZBk4{TO>Apvv*PRhhb|L3K5f zh;{)ZfNB#Ffg)m?+$AUhZEg;4>n*RVKO5HQ0l3n?mh&ESx<5U-1YF}GhCl6*@9CNQ z?q4JuLs&4K;nnox09+qyTJ*04+&FQfZg?_^B;XcdX9YpSInUKuU7^p#66v?tP$402 z-Ti6q*$Wp85C98645^K<5KFN4S`v954|dzw9{%eAly)>Xl3bpxp2J}<1Z0W?d0&wp zwIY2XOG$r1KR2`}G7%IW{x4GbM_Qji!ZX26#`)ysW;R;9ii@1)Z$=?@+zaurQGw ztr@* zg2p9pyj5)*1B&CJo*^Ol0%_&THg%ql&xb&;%lTt~XQt=fZfN+vH*ZyD^#$-So{?Zh zJ32OxGx=^o8aPoGki1Gz#zm4Sc%SiE@aS-hJZuF49V>JO9sb3uKQCQV=ee)Q4MY<8 zUEztKS%xpd<`ldZvR20CY3nTwxUV+=h7Z{eJGvyAU#E&&{GH&Zk?4<%@Q+lMW_>o{ zhcO+Wz(ExYVg$j^wc*LT>YUFwPu-fb^mHW8;iBw8r6A;8<^B^*R?W1s66%_+{3g)d zRSTBeLHdJ88>P>5K0kUTc}}>D2SHf>0tC3)j89DA(^J|i4O%=PA>P2_@kpXxY*H^9 zH3dX)^2tvHh)snklNymRK1VA4o2~DM$+O%OBbG< HFWdJ&)}w}N literal 0 HcmV?d00001 diff --git a/features.dot b/features.dot new file mode 100644 index 00000000000..0b11329e4ed --- /dev/null +++ b/features.dot @@ -0,0 +1,5 @@ +digraph { + stable_deref -> anchor_type + pin_and_move -> anchor_type + pin_and_move -> stack_pinning +} diff --git a/features.png b/features.png new file mode 100644 index 0000000000000000000000000000000000000000..cd2c102cecc3233a1b821f8dab182d6b819ada5c GIT binary patch literal 20313 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 { ptr: T, } -impl Anchor { +impl Anchor { pub fn new(ptr: T) -> Anchor; pub unsafe fn get_mut(this: &mut Anchor) -> &mut T; @@ -196,15 +196,15 @@ impl Anchor { pub fn pin<'a>(this: &'a mut Anchor) -> Pin<'a, T::Target>; } -impl Anchor where T::Target: Move { +impl Anchor where T::Target: Move { pub fn into_inner(this: Anchor) -> T; } -impl Deref for Anchor { +impl Deref for Anchor { type Target = T; } -impl DerefMut for Anchor where T::Target: Move { } +impl DerefMut for Anchor where T::Target: Move { } ``` Because `Anchor` implements `StableDeref` and `Own`, and it is not safe to get From 077cc71e87c730025ce55c5c0bc7d1e48f6fe9b4 Mon Sep 17 00:00:00 2001 From: boats Date: Wed, 21 Feb 2018 14:02:19 -0800 Subject: [PATCH 03/14] Remove graphviz junk. --- derefs.dot | 12 ------------ derefs.png | Bin 26876 -> 0 bytes features.dot | 5 ----- features.png | Bin 20313 -> 0 bytes 4 files changed, 17 deletions(-) delete mode 100644 derefs.dot delete mode 100644 derefs.png delete mode 100644 features.dot delete mode 100644 features.png diff --git a/derefs.dot b/derefs.dot deleted file mode 100644 index 73f4a2f7f4b..00000000000 --- a/derefs.dot +++ /dev/null @@ -1,12 +0,0 @@ -digraph { - Deref [shape=box] - Deref -> DerefMut - Deref -> StableDeref - Deref -> Own - Deref -> Share - DerefMut [shape=box] - DerefMut -> StableDerefMut - Clone [shape=box] - Clone -> Share - StableDeref -> StableDerefMut -} diff --git a/derefs.png b/derefs.png deleted file mode 100644 index b5aad5fe2cde34824b4886df4621fe601a2fe216..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 26876 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 HFWdJ&)}w}N diff --git a/features.dot b/features.dot deleted file mode 100644 index 0b11329e4ed..00000000000 --- a/features.dot +++ /dev/null @@ -1,5 +0,0 @@ -digraph { - stable_deref -> anchor_type - pin_and_move -> anchor_type - pin_and_move -> stack_pinning -} diff --git a/features.png b/features.png deleted file mode 100644 index cd2c102cecc3233a1b821f8dab182d6b819ada5c..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 20313 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 Date: Fri, 23 Feb 2018 17:03:23 -0800 Subject: [PATCH 04/14] Pin/Move/etc RFC. --- text/0000-pin_and_move.md | 82 +++++++++++++++++++++++++++++++++++---- 1 file changed, 74 insertions(+), 8 deletions(-) diff --git a/text/0000-pin_and_move.md b/text/0000-pin_and_move.md index edd551524c9..9a59b1878cd 100644 --- a/text/0000-pin_and_move.md +++ b/text/0000-pin_and_move.md @@ -12,7 +12,17 @@ which cannot be safely moved around. # Motivation [motivation]: #motivation -Why are we doing this? What use cases does it support? What is the expected outcome? +A longstanding problem for Rust has been dealing with types that should not be +moved. A common motivation for this is when a struct contains a pointer into +its own representation - moving that struct would invalidate that pointer. This +use case has become especially important recently with work on generators. +Because generators essentially reify a stackframe into an object that can be +manipulated in code, it is likely for idiomatic usage of a generator to result +in such a self-referential type, if it is allowed. + +This proposal adds an API to std which would allow you to guarantee that a +particular value will never move again, enabling safe APIs that rely on +self-references to exist. # Explanation [explanation]: #explanation @@ -296,18 +306,74 @@ separate feature flags, which can be stabilized in stages: # Drawbacks [drawbacks]: #drawbacks -Why should we *not* do this? +This adds additional APIs to std, including several marker traits and an auto +trait. Such additions should not be taken lightly, and only included if they +are well-justified by the abstractions they express. # Rationale and alternatives [alternatives]: #alternatives -- Why is this design the best in the space of possible designs? -- What other designs have been considered and what is the rationale for not choosing them? -- What is the impact of not doing this? +## Comparison to `?Move` + +One previous proposal was to add a built-in `Move` trait, similar to `Sized`. A +type that did not implement `Move` could not be moved after it had been +referenced. + +This solution had some problems. First, the `?Move` bound ended up "infecting" +many different APIs where it wasn't relevant, and introduced a breaking change +in several cases where the API bound changed in a non-backwards compatible way. + +In a certain sense, this proposal is a much more narrowly scoped version of +`?Move`. With `?Move`, *any* reference could act as the "Pin" reference does +here. However, because of this flexibility, the negative consequences of having +a type that can't be moved had a much broader impact. + +Instead, we require APIs to opt into supporting immovability (a niche case) by +operating with the `Pin` type, avoiding "infecting" the basic reference type +with concerns around immovable types. + +## Comparison to using `unsafe` APIs + +Another alternative we've considered was to just have the APIs which require +immovability be `unsafe`. It would be up to the users of these APIs to review +and guarantee that they never moved the self-referential types. For example, +generator would look like this: + +```rust +trait Generator { + type Yield; + type Return; + + unsafe fn resume(&mut self) -> CoResult; +} +``` + +This would require no extensions to the standard library, but would place the +burden on every user who wants to call resume to guarantee (at the risk of +memory insafety) that their types were not moved, or that they were moveable. +This seemed like a worse trade off than adding these APIs. + +## Relationship to owning-ref & rental + +Existing crates like owning-ref and rental make some use of "self-referential" +types. Unlike the generators this RFC is designed to support, their references +always point into the heap - making it acceptable to move their types around. + +However, some of this infrastructure is still useful to those crates. In +particular, the stable deref hierarchy is related to the existing hierarchy in +the stable_deref crate, which those other crates depend on. By uplifting those +markers into the standard library, we create a shared, endorsed, and guaranteed +set of markers for the invariants those libraries care about. + +In order to be implemented in safe code, those library need additional features +connecting to "existential" or "generative" lifetimes. These language changes +are out of scope for this RFC. # Unresolved questions [unresolved]: #unresolved-questions -- What parts of the design do you expect to resolve through the RFC process before this gets merged? -- What parts of the design do you expect to resolve through the implementation of this feature before stabilization? -- What related issues do you consider out of scope for this RFC that could be addressed in the future independently of the solution that comes out of this RFC? +The names used in this RFC are all entirely up for debate. Some of the items +introduced (especially the `Move` trait) have evolved away from their original +design, making the names a bit of a misnomer (`Move` really means that its safe +to convert between `Pin` and `&mut T`, for example). We want to make sure we +have adequate names before stabilizing these APIs. From 95bcad6048a5a1218197a8cb718e50335e0fb8a9 Mon Sep 17 00:00:00 2001 From: boats Date: Fri, 23 Feb 2018 17:07:46 -0800 Subject: [PATCH 05/14] strack attack --- text/0000-pin_and_move.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0000-pin_and_move.md b/text/0000-pin_and_move.md index 9a59b1878cd..c17569fe429 100644 --- a/text/0000-pin_and_move.md +++ b/text/0000-pin_and_move.md @@ -36,7 +36,7 @@ pub unsafe auto trait Move { } ``` A type implements `Move` if in its stack representation, it contains internal -references to other positions within its strack representation. Nearly every +references to other positions within its stack representation. Nearly every type in Rust is `Move`. Positive impls of `Move` are added for types which contain pointers to generic From f28446b3286733c191832b376c7d06c0a23bead2 Mon Sep 17 00:00:00 2001 From: boats Date: Fri, 23 Feb 2018 17:10:22 -0800 Subject: [PATCH 06/14] Fix very important mistake --- text/0000-pin_and_move.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/text/0000-pin_and_move.md b/text/0000-pin_and_move.md index c17569fe429..84cf42c177f 100644 --- a/text/0000-pin_and_move.md +++ b/text/0000-pin_and_move.md @@ -35,9 +35,9 @@ This new auto trait is added to the `core::marker` and `std::marker` modules: pub unsafe auto trait Move { } ``` -A type implements `Move` if in its stack representation, it contains internal -references to other positions within its stack representation. Nearly every -type in Rust is `Move`. +A type implements `Move` if in its stack representation, it does not contain +internal references to other positions within its stack representation. Nearly +every type in Rust is `Move`. Positive impls of `Move` are added for types which contain pointers to generic types, but do not contain those types in their stack representation, e.g: From f530db29f772d32f69e20021d3ec56bfebdb3592 Mon Sep 17 00:00:00 2001 From: boats Date: Fri, 23 Feb 2018 17:12:52 -0800 Subject: [PATCH 07/14] Share types are Rc and Arc. --- text/0000-pin_and_move.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0000-pin_and_move.md b/text/0000-pin_and_move.md index 84cf42c177f..1c12a59ec94 100644 --- a/text/0000-pin_and_move.md +++ b/text/0000-pin_and_move.md @@ -80,7 +80,7 @@ construct. - **Share** implies that this type has shared ownership over the data which it dereferences to. It implies `Clone`, and every type it is `Clone`d it must continue to refer to the same data; it cannot perform deep clones of that - data. Examples of `Share` + data. Examples of `Share` types are `Rc` and `Arc`. These traits are mutually exclusive - it would be a logic error to implement both of them for a single type. We retain the liberty to assume that no type From dcb91a2dd681be8288aa5200536ecdc28ea84a68 Mon Sep 17 00:00:00 2001 From: boats Date: Fri, 23 Feb 2018 17:15:23 -0800 Subject: [PATCH 08/14] stable_deref_trait crate link --- text/0000-pin_and_move.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/text/0000-pin_and_move.md b/text/0000-pin_and_move.md index 1c12a59ec94..3b0e0efc554 100644 --- a/text/0000-pin_and_move.md +++ b/text/0000-pin_and_move.md @@ -126,8 +126,8 @@ backing data would otherwise be in rodata. ### Notes on existing ecosystem traits These traits supplant certain traits in the ecosystem which already provide -similar guarantees. In particular, the [stable-deref][stable-deref] crate -provides a similar bit different hierarchy. The differences are: +similar guarantees. In particular, the [stable_deref_trait][stable-deref] +crate provides a similar bit different hierarchy. The differences are: - That crate draws no distinction between `StableDeref` and `StableDerefMut`. This does not leave forward compatibility for the static string optimization @@ -377,3 +377,5 @@ introduced (especially the `Move` trait) have evolved away from their original design, making the names a bit of a misnomer (`Move` really means that its safe to convert between `Pin` and `&mut T`, for example). We want to make sure we have adequate names before stabilizing these APIs. + +[stable-deref]: https://crates.io/crates/stable_deref_trait From 2cd352a432c45f782cd238fe1916139b479f2308 Mon Sep 17 00:00:00 2001 From: boats Date: Tue, 27 Feb 2018 16:56:22 -0800 Subject: [PATCH 09/14] Reduce scope of pin/move RFC. --- text/0000-pin_and_move.md | 288 +++++++++++--------------------------- 1 file changed, 81 insertions(+), 207 deletions(-) diff --git a/text/0000-pin_and_move.md b/text/0000-pin_and_move.md index 3b0e0efc554..c15987a82f2 100644 --- a/text/0000-pin_and_move.md +++ b/text/0000-pin_and_move.md @@ -39,115 +39,63 @@ A type implements `Move` if in its stack representation, it does not contain internal references to other positions within its stack representation. Nearly every type in Rust is `Move`. -Positive impls of `Move` are added for types which contain pointers to generic -types, but do not contain those types in their stack representation, e.g: - -```rust -unsafe impl<'a, T: ?Sized> Move for &'a T { } -unsafe impl<'a, T: ?Sized> Move for &'a mut T { } -unsafe impl<'a, T: ?Sized> Move for Box { } -unsafe impl<"a, T> Move for Vec { } -// etc -``` - This trait is a lang item, but only to generate negative impls for certain generators. Unlike previous `?Move` proposals, and unlike some traits like -`Sized` and `Copy`, this trait does not impose any particular semantics on -types that do or don't implement it. - -## The stability marker traits +`Sized` and `Copy`, this trait does not impose any compiler-based semantics +types that do or don't implement it. Instead, the semantics are entirely +enforced through library APIs which use `Move` as a marker. -A hierarchy of marker traits for smart pointer types is added to `core::marker` -and `std::marker`. These exist to provide a shared language for talking about -the guarantees that different smart pointers provide. This enables both the -kinds of self-referential support we talk about later in this RFC and other -APIs like rental and owning-ref. +## The `Anchor` type -### `Own` and `Share` +An anchor is a new kind of smart pointer. It is very much like a box - it is a +heap-allocated, exclusive-ownership type - but it provides additional +constraints. Unless the type it references implements `Move`, it is not +possible to mutably dereference the `Anchor` or move out of it. It does +implement immutable Deref for all types, including types that don't implement +`Move`. ```rust -unsafe trait Own: Deref { } -unsafe trait Share: Deref + Clone { } -``` +#[fundamental] +struct Anchor { + inner: Box, +} + +impl Anchor { + pub fn new(data: T) -> Anchor; +} -These two traits are for smart pointers which implement some form of ownership -construct. +impl Anchor { + pub fn as_pin<'a>(&'a mut self) -> Pin<'a, T>; -- **Own** implies that this type has unique ownership over the data which it - dereferences to. That is, unless the data is moved out of the smart pointer, - when this pointer is destroyed, so too will that data. Examples of `Own` - types are `Box`, `Vec` and `String`. -- **Share** implies that this type has shared ownership over the data which it - dereferences to. It implies `Clone`, and every type it is `Clone`d it must - continue to refer to the same data; it cannot perform deep clones of that - data. Examples of `Share` types are `Rc` and `Arc`. + pub unsafe fn get_mut(this: &mut Anchor) -> &mut T; -These traits are mutually exclusive - it would be a logic error to implement -both of them for a single type. We retain the liberty to assume that no type -ever does implement both - we could upgrade this from a logic error to -undefined behavior, we could make changes that would break any code that -implements both traits for the same type. + pub unsafe fn into_inner_unchecked(this: Anchor) -> T; +} -### `StableDeref` and `StableDerefMut` +impl Anchor { + pub unsafe fn into_inner(this: Anchor) -> T; +} -```rust -unsafe trait StableDeref: Deref { } -unsafe trait StableDerefMut: StableDeref + DerefMut { } +impl Deref for Anchor { + type Target = T; +} + +impl DerefMut for Anchor { } + +unsafe impl Move for Anchor { } ``` -These two traits are for any pointers which guarantee that the type they -dereference to is at a stable address. That is, moving the pointer does not -move the type being addressed. - -- **StableDeref** implies that the referenced data will not move if you move - this type or dereference it *immutably*. Types that implement this include - `Box`, both reference types, `Rc`, `Arc`, `Vec`, and `String`. - Pretty much everything in std that implements `Deref` implements - `StableDeref`. -- **StableDerefMut** implies the same guarantees as `StableDeref`, but also - guarantees that dereferencing a *mutable* reference will not cause the - referenced data to change addresses. Because of this, it also implies - `DerefMut`. Examples of type that implement this include `&mut T`, `Box`, - and `Vec`. - -Note that `StableDerefMut` does not imply that taking a mutable reference to -the smart pointer will not cause the referenced data to move. For example, -calling `push` on a `Vec` can cause the slice it dereferences to to change -locations. Its only obtaining a mutable reference to the target data which is -guaranteed not to relocate it. - -Note also that this RFC does not propose implementing `StableDerefMut` for -`String`. This is to be forward compatible with the static string optimization, -an optimization which allows values of `&'static str` to be converted to -`String` without incurring a heap allocation. A component of this optimization -would cause `String` to allocate when dereferencing to an `&mut str` if the -backing data would otherwise be in rodata. - -### Notes on existing ecosystem traits - -These traits supplant certain traits in the ecosystem which already provide -similar guarantees. In particular, the [stable_deref_trait][stable-deref] -crate provides a similar bit different hierarchy. The differences are: - -- That crate draws no distinction between `StableDeref` and `StableDerefMut`. - This does not leave forward compatibility for the static string optimization - mentioned previously. -- That crate has no equivalent to the `Own` trait, which is necessary for some - APIs using internal references. -- That crate has a `StableDerefClone` type, which is equivalent to the bound - `Share + StableDeref` in our system. - -If the hierarchy proposed in this RFC becomes stable, all users are encouraged -to migrate from that crate to the standard library traits. +For types that do not implement `Move`, instead of using mutable references, +users of `Anchor` will use the `Pin` type, described in the next section. ## The `Pin` type The `Pin` type is a wrapper around a mutable reference. If the type it references is `!Move`, the `Pin` type guarantees that the referenced data will -never be moved again. It has a relatively small API. It is added to both -`std::mem` and `core::mem`. +never be moved again. ```rust +#[fundamental] struct Pin<'a, T: ?Sized + 'a> { data: &'a mut T, } @@ -173,8 +121,7 @@ impl<'a, T: ?Sized + Move> DerefMut for Pin<'a, T> { } For types which implement `Move`, `Pin` is essentially the same as an `&mut T`. But for types which do not, the conversion between `&mut T` and `Pin` is -unsafe (however, `Pin` can be easily immutably dereferenced, even for `!Move` -types). +unsafe. The contract on the unsafe part of `Pin`s API is that a Pin cannot be constructed if the data it references would ever move again, and that it cannot @@ -182,95 +129,8 @@ be converted into a mutable reference if the data might ever be moved out of that reference. In other words, if you have a `Pin` containing data which does not implement `Move`, you have a guarantee that that data will never move. -The next two subsections describe safe APIs for constructing a `Pin` of data -which cannot be moved - one in the heap, and one in the stack. - -### Pinning to the heap: The `Anchor` type - -The `Anchor` wrapper takes a type that implements `StableDeref` and `Own`, and -prevents users from moving data out of that unless it implements `Move`. It is -added to `std::mem` and `core::mem`. - -```rust -struct Anchor { - ptr: T, -} - -impl Anchor { - pub fn new(ptr: T) -> Anchor; - - pub unsafe fn get_mut(this: &mut Anchor) -> &mut T; - - pub unsafe fn into_inner_unchecked(this: Anchor) -> T; - - pub fn pin<'a>(this: &'a mut Anchor) -> Pin<'a, T::Target>; -} - -impl Anchor where T::Target: Move { - pub fn into_inner(this: Anchor) -> T; -} - -impl Deref for Anchor { - type Target = T; -} - -impl DerefMut for Anchor where T::Target: Move { } -``` - -Because `Anchor` implements `StableDeref` and `Own`, and it is not safe to get -an `&mut T` if the target of `T ` does not implement `Move`, an anchor -guarantees that the target of `T` will never move again. This satisfies the -safety constraints of `Pin`, allowing a user to construct a `Pin` from an -anchored pointer. - -Because the data is anchored into the heap, you can move the anchor around -without moving the data itself. This makes anchor a very flexible way to handle -immovable data, at the cost of a heap allocation. - -An example use: - -```rust -let mut anchor = Anchor::new(Box::new(immovable_data)); -let pin = Anchor::pin(&mut anchor); -``` - -### Pinning to the stack: `Pin::stack` and `pinned` - -Data can also be pinned to the stack. This avoids the heap allocation, but the -pin must not outlive the data being pinned, and the API is less convenient. - -First, the pinned function, added to `std::mem` and `core::mem`: - -```rust -pub struct StackPinned<'a, T: ?Sized> { - _marker: PhantomData<&'a mut &'a ()>, - data: T -} - -pub fn pinned<'a, T>(data: T) -> StackPinned<'a, T> { - StackPinned { - data, _marker: PhantomData, - } -} -``` - -Second, this constructor is added to `Pin`: - -```rust -impl<'a, T: ?Sized> Pin<'a, T> { - pub fn stack(data: &'a mut StackPinned<'a, T>) -> Pin<'a, T>; -} -``` - -Because the lifetime of the `StackPinned` and the lifetime of the reference to -it are bound together, the StackPinned wrapper is functionally moved (and with -it the data inside it) into the Pin. Thus, even though the data is allocated on -the stack, it is pinned to its location for the remainder of its scope. - -```rust -let mut data = mem::pinned(immovable_data); -let pin = Pin::stack(&mut data); -``` +The `Anchor` type has a method `as_pin`, which returns a `Pin`, because it +upholds the guarantees necessary to safely construct a `Pin`. ## Immovable generators @@ -291,24 +151,12 @@ changes to the generator API: This is an example of how the APIs in this RFC allow for self-referential data types to be created safely. -## Stabilization planning - -This RFC proposes a large API addition, and so it is broken down into four -separate feature flags, which can be stabilized in stages: - -1. `stable_deref` - to control the smart pointer trait hierarchy - StableDeref, - StableDerefMut, Own, and Share. -2. `pin_and_move` - to control the `Move` auto trait and the `Pin` type. These - two components only make sense working together. -3. `anchor` - to control the `Anchor` struct, pinning to the heap. -4. `stack_pinning` - to control the APIs related to stack pinning. - # Drawbacks [drawbacks]: #drawbacks -This adds additional APIs to std, including several marker traits and an auto -trait. Such additions should not be taken lightly, and only included if they -are well-justified by the abstractions they express. +This adds additional APIs to std, including an auto trait. Such additions +should not be taken lightly, and only included if they are well-justified by +the abstractions they express. # Rationale and alternatives [alternatives]: #alternatives @@ -353,21 +201,47 @@ burden on every user who wants to call resume to guarantee (at the risk of memory insafety) that their types were not moved, or that they were moveable. This seemed like a worse trade off than adding these APIs. -## Relationship to owning-ref & rental +## Anchor as a wrapper type and `StableDeref` + +In a previous iteration of this RFC, `Anchor` was a wrapper type that could +"anchor" any smart pointer, and there was a hierarchy of traits relating to the +stability of the referent of different pointer types. + +The primary benefit of this approach was that it was partially integrated with +crates like owning-ref and rental, which also use a hierarchy of stability +traits. However, because of differences in the requirements, the traits used by +owning-ref et al ended up being a non-overlapping subset of the traits proposed +by this RFC from the traits used by the Anchor type. Merging these into a +single hierarchy provided relatively little benefit. + +And the only types that implemented all of the necessary traits to be put into +an Anchor before were `Box` and `Vec`. Because you cannot get mutable +access to the smart pointer (unless the referent implements `Move`), an +`Anchor>` was not really any different from an `Anchor>` in the +previous iteration of the RFC. For this reason, making `Anchor` always a box, +and just supporting `Anchor<[T]>`, reduced the API complexity without losing +any expressiveness. + +## Stack pinning API (potential future extension) + +This API supports "anchoring" `!Move` types in the heap. However, they can also +be safely held in place in the stack, allowing a safe API for creating a `Pin` +referencing a stack allocated `!Move` type. + +This API is small, and does not become a part of anyone's public API. For that +reason, we'll start by allowing it to grow out of tree, in third party crates, +before including it in std. -Existing crates like owning-ref and rental make some use of "self-referential" -types. Unlike the generators this RFC is designed to support, their references -always point into the heap - making it acceptable to move their types around. +## Making `Pin` a built-in type (potential future extension) -However, some of this infrastructure is still useful to those crates. In -particular, the stable deref hierarchy is related to the existing hierarchy in -the stable_deref crate, which those other crates depend on. By uplifting those -markers into the standard library, we create a shared, endorsed, and guaranteed -set of markers for the invariants those libraries care about. +The `Pin` type could instead be a new kind of first-class reference - `&'a pin +T`. This would have some advantages - it would be trivial to project through +fields, for example, and "stack pinning" would not require an API, it would be +natural. However, it has the downside of adding a new reference type, a very +big language change. -In order to be implemented in safe code, those library need additional features -connecting to "existential" or "generative" lifetimes. These language changes -are out of scope for this RFC. +For now, we're happy to stick with the `Pin` struct in std, and if this type is +ever added, turn the `Pin` type into an alias for the reference type. # Unresolved questions [unresolved]: #unresolved-questions From 99a9c4cae9e756fd44336a3e2448f527984647ee Mon Sep 17 00:00:00 2001 From: Aaron Turon Date: Tue, 27 Feb 2018 17:03:19 -0800 Subject: [PATCH 10/14] Add guide --- text/0000-pin_and_move.md | 39 ++++++++++++++++++++++++++++++++++++--- 1 file changed, 36 insertions(+), 3 deletions(-) diff --git a/text/0000-pin_and_move.md b/text/0000-pin_and_move.md index c15987a82f2..367548fdd25 100644 --- a/text/0000-pin_and_move.md +++ b/text/0000-pin_and_move.md @@ -24,8 +24,41 @@ This proposal adds an API to std which would allow you to guarantee that a particular value will never move again, enabling safe APIs that rely on self-references to exist. -# Explanation -[explanation]: #explanation +# Guide-level explanation + +The core goal of this RFC is to **provide a reference type where the referent is guaranteed to never move before being dropped**. We want to do this with a minimum disruption to the type system, and in fact, this RFC shows that we can achieve the goal without *any* type system changes. + +Let's take that goal apart, piece by piece, from the perspective of the futures (i.e. async/await) use case: + +- **Reference type**. The reason we need a reference type is that, when working with things like futures, we generally want to combine smaller futures into larger ones, and only at the top level put an entire resulting future into some immovable location. Thus, we need a reference type for methods like `poll`, so that we can break apart a large future into its smaller components, while retaining the guarantee about immobility. + +- **Never to move before being dropped**. Again looking at the futures case, once we being `poll`ing a future, we want it to be able to store references into itself, which is possible if we can guarantee that the whole future will never move. We don't try to track *whether* such references exist at the type level, since that would involve cumbersome typestate; instead, we simply decree that by the time you initially `poll`, you promise to never move an immobile future again. + +At the same time, we want to support futures (and iterators, etc.) that *can* move. While it's possible to do so by providing two distinct `Future` (or `Iterator`, etc) traits, such designs incur unacceptable ergonomic costs. + +The key insight of this RFC is that we can create a new library type, `Pin<'a, T>`, which encompasses *both* moveable and immobile referents. The type is paired with a new auto trait, `Move`, which determines the meaning of `Pin<'a, T>`: + +- If `T: Move` (which is the default), then `Pin<'a, T>` is entirely equivalent to `&'a mut T`. +- If `T: !Move`, then `Pin<'a, T>` provides a unique reference to a `T` with lifetime `'a`, but only provides `&'a T` access safely. It also guarantees that the referent will *never* be moved. However, getting `&'a mut T` access is unsafe, because operations like `mem::replace` mean that `&mut` access is enough to move data out of the referent; you must promise not to do so. + +To be clear: the *sole* function of `Move` is to control the meaning of `Pin`. Making `Move` an auto trait means that the vast majority of types are automatically "movable", so `Pin` degenerates to `&mut`. In the case that you need immobility, you *opt out* of `Move`, and then `Pin` becomes meaningful for your type. + +Putting this all together, we arrive at the following definition of `Future`: + +```rust +trait Future { + type Item; + type Error; + + fn poll(self: Pin, cx: task::Context) -> Poll; +} +``` + +By default when implementing `Future` for a struct, this definition is equivalent to today's, which takes `&mut self`. But if you want to allow self-referencing in your future, you just opt out of `Move`, and `Pin` takes care of the rest. + +The final piece of this RFC is the `Anchor` type, which is just a `Box` that doesn't allow moving out, but *does* allow you to acquire a `Pin` reference. + +# Reference-level explanation ## The `Move` auto trait @@ -50,7 +83,7 @@ enforced through library APIs which use `Move` as a marker. An anchor is a new kind of smart pointer. It is very much like a box - it is a heap-allocated, exclusive-ownership type - but it provides additional constraints. Unless the type it references implements `Move`, it is not -possible to mutably dereference the `Anchor` or move out of it. It does +possible to mutably dereference the `Anchor` or move out of it in safe code. It does implement immutable Deref for all types, including types that don't implement `Move`. From 30e44306f5a8c9dd97a1f5297a712851fd076c4e Mon Sep 17 00:00:00 2001 From: boats Date: Wed, 7 Mar 2018 18:40:27 -0800 Subject: [PATCH 11/14] Update pin RFC --- text/0000-pin.md | 408 ++++++++++++++++++++++++++++++++++++++ text/0000-pin_and_move.md | 288 --------------------------- 2 files changed, 408 insertions(+), 288 deletions(-) create mode 100644 text/0000-pin.md delete mode 100644 text/0000-pin_and_move.md diff --git a/text/0000-pin.md b/text/0000-pin.md new file mode 100644 index 00000000000..23b4c732534 --- /dev/null +++ b/text/0000-pin.md @@ -0,0 +1,408 @@ +- Feature Name: +- Start Date: 2018-02-19 +- RFC PR: (leave this empty) +- Rust Issue: (leave this empty) + +# Summary +[summary]: #summary + +Introduce new APIs to libcore / libstd to serve as safe abstractions for data +which cannot be safely moved around. + +# Motivation +[motivation]: #motivation + +A longstanding problem for Rust has been dealing with types that should not be +moved. A common motivation for this is when a struct contains a pointer into +its own representation - moving that struct would invalidate that pointer. This +use case has become especially important recently with work on generators. +Because generators essentially reify a stackframe into an object that can be +manipulated in code, it is likely for idiomatic usage of a generator to result +in such a self-referential type, if it is allowed. + +This proposal adds an API to std which would allow you to guarantee that a +particular value will never move again, enabling safe APIs that rely on +self-references to exist. + +# Guide-level explanation + +The core goal of this RFC is to **provide a reference type where the referent is guaranteed to never move before being dropped**. We want to do this with a minimum disruption to the type system, and in fact, this RFC shows that we can achieve the goal without *any* type system changes. + +Let's take that goal apart, piece by piece, from the perspective of the futures (i.e. async/await) use case: + +- **Reference type**. The reason we need a reference type is that, when working with things like futures, we generally want to combine smaller futures into larger ones, and only at the top level put an entire resulting future into some immovable location. Thus, we need a reference type for methods like `poll`, so that we can break apart a large future into its smaller components, while retaining the guarantee about immobility. + +- **Never to move before being dropped**. Again looking at the futures case, once we being `poll`ing a future, we want it to be able to store references into itself, which is possible if we can guarantee that the whole future will never move. We don't try to track *whether* such references exist at the type level, since that would involve cumbersome typestate; instead, we simply decree that by the time you initially `poll`, you promise to never move an immobile future again. + +At the same time, we want to support futures (and iterators, etc.) that *can* move. While it's possible to do so by providing two distinct `Future` (or `Iterator`, etc) traits, such designs incur unacceptable ergonomic costs. + +The key insight of this RFC is that we can create a new library type, `PinMut<'a, T>`, which encompasses *both* moveable and immobile referents. The type is paired with a new auto trait, `Unpin`, which determines the meaning of `PinMut<'a, T>`: + +- If `T: Unpin` (which is the default), then `PinMut<'a, T>` is entirely equivalent to `&'a mut T`. +- If `T: !Unpin`, then `PinMut<'a, T>` provides a unique reference to a `T` with lifetime `'a`, but only provides `&'a T` access safely. It also guarantees that the referent will *never* be moved. However, getting `&'a mut T` access is unsafe, because operations like `mem::replace` mean that `&mut` access is enough to move data out of the referent; you must promise not to do so. + +To be clear: the *sole* function of `Unpin` is to control the meaning of `PinMut`. Making `Unpin` an auto trait means that the vast majority of types are automatically "movable", so `PinMut` degenerates to `&mut`. In the case that you need immobility, you *opt out* of `Unpin`, and then `PinMut` becomes meaningful for your type. + +Putting this all together, we arrive at the following definition of `Future`: + +```rust +trait Future { + type Item; + type Error; + + fn poll(self: PinMut, cx: task::Context) -> Poll; +} +``` + +By default when implementing `Future` for a struct, this definition is equivalent to today's, which takes `&mut self`. But if you want to allow self-referencing in your future, you just opt out of `Unpin`, and `PinMut` takes care of the rest. + +This RFC also provides pinned analogies to `Box` and `&T` - `PinBox` and `Pin`. They work along the same lines as the `PinMut` type discussed here - if the type implements `Unpin`, they function the same as their unpinned varieties; if the type has opted out of `Unpin`, they guarantee that they type behind the reference will not be moved again. + +# Reference-level explanation + +## The `Unpin` auto trait + +This new auto trait is added to the `core::marker` and `std::marker` modules: + +```rust +pub unsafe auto trait Unpin { } +``` + +A type that implements `Unpin` can be moved out of one of the pinned reference +types discussed later in this RFC. Otherwise, they do not expose a safe API +which allows you to move a value out of them. Because `Unpin` is an auto trait, +most types in Rust implement `Unpin`. The types which don't are primarily +self-referential types, like certain generators. + +This trait is a lang item, but only to generate negative impls for certain +generators. Unlike previous `?Move` proposals, and unlike some traits like +`Sized` and `Copy`, this trait does not impose any compiler-based semantics +types that do or don't implement it. Instead, the semantics are entirely +enforced through library APIs which use `Unpin` as a marker. + +## `Pin` and `PinMut` + +`Pin` and `PinMut` are two types added to `core::mem` and `std::mem`. They are +analogous to `&T` and `&mut T` respectively. + +```rust +#[fundamental] +pub struct Pin<'a, T: ?Sized + 'a> { + data: &'a T, +} + +#[fundamental] +pub struct PinMut<'a, T: ?Sized + 'a> { + data: &'a mut T, +} +``` + +### Safe APIs + +They both implement `Deref`, but `PinMut` only implements `DerefMut` if the +type it references implements `Unpin`: + +```rust +impl<'a, T: ?Sized> Deref for Pin<'a, T> { ... } + +impl<'a, T: ?Sized> Deref for PinMut<'a, T> { ... } + +impl<'a, T: Unpin + ?Sized> DerefMut for PinMut<'a, T> { ... } +``` + +They can only be safely constructed from references to types that implement +`Unpin`: + +```rust +impl<'a, T: Unpin + ?Sized> Pin<'a, T> { + pub fn new(reference: &'a T) -> Pin<'a, T> { ... } +} + +impl<'a, T: Unpin + ?Sized> PinMut<'a, T> { + pub fn new(reference: &'a mut T) -> PinMut<'a, T> { ... } +} +``` + +They also have a `borrow` function, which allows them to be transformed to pins +with shorter lifetimes as may be necessary: + +```rust +impl<'a, T: ?Sized> Pin<'a, T> { + pub fn borrow<'b>(this: &'b Pin<'a, T>) -> Pin<'b, T> { ... } +} + +impl<'a, T: ?Sized> PinMut<'a, T> { + pub fn borrow<'b>(this: &'b PinMut<'a, T>) -> PinMut<'b, T> { ... } +} +``` + +They may also implement additional APIs as is useful for type conversions, such +as `AsRef`, `From`, and so on. They implement `CoerceUnsized` as necessary to +make coercing them into trait objects possible. + +### Unsafe APIs + +Both types can be unsafely constructed from references to types which may not +implement `Unpin`. Users who use these constructors must know that the type +they are passing a reference to will never be moved again after the Pin is +constructed. + +```rust +impl<'a, T: ?Sized> Pin<'a, T> { + pub unsafe fn new_unchecked(reference: &'a T) -> Pin<'a, T> { ... } +} + +impl<'a, T: ?Sized> PinMut<'a, T> { + pub unsafe fn new_unchecked(reference: &'a mut T) -> PinMut<'a, T> { ... } +} +``` + +`PinMut` also has an API which allows it to be converted into a mutable +reference for a type that doesn't implement `Unpin`. Users who use this API +must guarantee that they never move out of the mutable reference they receive. + +```rust +impl<'a, T: ?Sized> PinMut<'a, T> { + pub unsafe fn get_mut<'b>(this: &'b mut PinMut<'a, T>) -> &'b mut T { ... } +} +``` + +Finally, as a convenience, they both implement an unsafe `map` function, which +makes it easier to project through a field. Users calling this function must +guarantee that the value returned will not move as long as the referent of this +pin doesn't move (e.g. it is a private field of the value). They also must not +move out of the mutable reference they receive as the closure argument, in the +case of `PinMut`: + +```rust +impl<'a, T: ?Sized> Pin<'a, T> { + pub unsafe fn map<'b, U, F>(this: &'b Pin<'a, T>, f: F) -> Pin<'b, U> + where F: FnOnce(&T) -> &U + { ... } +} + +impl<'a, T: ?Sized> PinMut<'a, T> { + pub unsafe fn map<'b, U, F>(this: &'b mut PinMut<'a, T>, f: F) -> PinMut<'b, U> + where F: FnOnce(&mut T) -> &mut U + { ... } +} + +// for example: +struct Foo { + bar: Bar, +} + +let foo_pin: Pin; +// ... +let bar_pin: Pin = unsafe { Pin::map(&foo_pin, |foo| &foo.bar) }; +``` + +## `PinBox` + +The `PinBox` type is added to alloc::boxed and std::boxed. It is analogous to +the `Box` type in the same way that `Pin` and `PinMut` are analogous to the +reference types, and it has a similar API. + +```rust +#[fundamental] +pub struct PinBox { + inner: Box, +} +``` + +### Safe API + +Unlike the other pin types, it is safe to construct a `PinBox` from a `T` and +from a `Box`: + +```rust +impl PinBox { + pub fn new(data: T) -> PinBox { ... } +} + +impl From> for PinBox { + fn from(boxed: Box) -> PinBox { ... } +} +``` + +It also provides the same Deref impls as `PinMut` does: + +```rust +impl Deref for PinBox { ... } +impl DerefMut for PinBox { ... } +``` + +If the data implements `Unpin`, its also safe to convert a `PinBox` into a +`Box`: + +```rust +impl From> for Box { ... } +``` + +Finally, it is safe to get a `Pin` and a `PinMut` from borrows of `PinBox`: + +```rust +impl PinBox { + fn as_pin<'a>(&'a self) -> Pin<'a, T> { ... } + fn as_pin_mut<'a>(&'a mut self) -> PinMut<'a, T> { ... } +} +``` + +These APIs make `PinBox` a reasonable way of handling data which does not +implement `!Unpin`. Once you heap allocate that data inside of a `PinBox`, you +know that it will never change address again, and you can hand out `Pin` and +`PinMut` references to that data. + +### Unsafe API + +`PinBox` can be unsafely converted into `&mut T` and `Box` even if the type +it references does not implement `Unpin`, similar to `PinMut`: + +```rust +impl PinBox { + pub unsafe fn get_mut<'a>(this: &'a mut PinBox) -> &'a mut T { ... } + pub unsafe fn into_inner(this: PinBox) -> Box { ... } +} +``` + +## Immovable generators + +Today, the unstable generators feature has an option to create generators which +contain references that live across yield points - these are, in effect, +internal references into the generator's state machine. Because internal +references are invalidated if the type is moved, these kinds of generators +("immovable generators") are currently unsafe to create. + +Once the arbitrary_self_types feature becomes object safe, we will make three +changes to the generator API: + +1. We will change the `resume` method to take self by `self: PinMut` + instead of `&mut self`. +2. We will implement `!Unpin` for the anonymous type of an immovable generator. +3. We will make it safe to define an immovable generator. + +This is an example of how the APIs in this RFC allow for self-referential data +types to be created safely. + +# Drawbacks +[drawbacks]: #drawbacks + +This adds additional APIs to std, including an auto trait. Such additions +should not be taken lightly, and only included if they are well-justified by +the abstractions they express. + +# Rationale and alternatives +[alternatives]: #alternatives + +## Comparison to `?Move` + +One previous proposal was to add a built-in `Move` trait, similar to `Sized`. A +type that did not implement `Move` could not be moved after it had been +referenced. + +This solution had some problems. First, the `?Move` bound ended up "infecting" +many different APIs where it wasn't relevant, and introduced a breaking change +in several cases where the API bound changed in a non-backwards compatible way. + +In a certain sense, this proposal is a much more narrowly scoped version of +`?Move`. With `?Move`, *any* reference could act as the "Pin" reference does +here. However, because of this flexibility, the negative consequences of having +a type that can't be moved had a much broader impact. + +Instead, we require APIs to opt into supporting immovability (a niche case) by +operating with the `Pin` type, avoiding "infecting" the basic reference type +with concerns around immovable types. + +## Comparison to using `unsafe` APIs + +Another alternative we've considered was to just have the APIs which require +immovability be `unsafe`. It would be up to the users of these APIs to review +and guarantee that they never moved the self-referential types. For example, +generator would look like this: + +```rust +trait Generator { + type Yield; + type Return; + + unsafe fn resume(&mut self) -> CoResult; +} +``` + +This would require no extensions to the standard library, but would place the +burden on every user who wants to call resume to guarantee (at the risk of +memory insafety) that their types were not moved, or that they were moveable. +This seemed like a worse trade off than adding these APIs. + +## Anchor as a wrapper type and `StableDeref` + +In a previous iteration of this RFC, there was a wrapper type called `Anchor` +that could "anchor" any smart pointer, and there was a hierarchy of traits +relating to the stability of the referent of different pointer types. This has +been replaced with `PinBox`. + +The primary benefit of this approach was that it was partially integrated with +crates like owning-ref and rental, which also use a hierarchy of stability +traits. However, because of differences in the requirements, the traits used by +owning-ref et al ended up being a non-overlapping subset of the traits proposed +by this RFC from the traits used by the Anchor type. Merging these into a +single hierarchy provided relatively little benefit. + +And the only types that implemented all of the necessary traits to be put into +an Anchor before were `Box` and `Vec`. Because you cannot get mutable +access to the smart pointer (unless the referent implements `Unpin`), an +`Anchor>` was not really any different from an `Anchor>` in the +previous iteration of the RFC. For this reason, replacing `Anchor` with +`PinBox` and just supporting `PinBox<[T]>` reduced the API complexity without +losing any expressiveness. + +## Stack pinning API (potential future extension) + +This API supports pinning `!Unpin` types in the heap. However, they can also +be safely held in place in the stack, allowing a safe API for creating a `Pin` +referencing a stack allocated `!Unpin` type. + +This API is small, and does not become a part of anyone's public API. For that +reason, we'll start by allowing it to grow out of tree, in third party crates, +before including it in std. Here a version of the API, for reference purposes: + +```rust +pub fn pinned(data: T) -> PinTemporary<'a, T> { + PinTemporary { data, _marker: PhantomData } +} + +struct PinTemporary<'a, T: 'a> { + data: T, + _marker: PhantomData<&'a &'a mut ()>, +} + +impl<'a, T> PinTemporary<'a, T> { + pub fn into_pin(&'a self) -> Pin<'a, T> { + unsafe { Pin::new_unchecked(&self.data) } + } + + pub fn into_pin_mut(&'a mut self) -> PinMut<'a, T> { + unsafe { PinMut::new_unchecked(&mut self.data) } + } +} +``` + +## Making `Pin` a built-in type (potential future extension) + +The `Pin` type could instead be a new kind of first-class reference - `&'a pin +T`. This would have some advantages - it would be trivial to project through +fields, for example, and "stack pinning" would not require an API, it would be +natural. However, it has the downside of adding a new reference type, a very +big language change. + +For now, we're happy to stick with the `Pin` struct in std, and if this type is +ever added, turn the `Pin` type into an alias for the reference type. + +# Unresolved questions +[unresolved]: #unresolved-questions + +In addition to the future extensions discussed above, the APIs of the three pin +types in std will grow over time as they implement more common conversion +traits and so on. + +[stable-deref]: https://crates.io/crates/stable_deref_trait diff --git a/text/0000-pin_and_move.md b/text/0000-pin_and_move.md deleted file mode 100644 index 367548fdd25..00000000000 --- a/text/0000-pin_and_move.md +++ /dev/null @@ -1,288 +0,0 @@ -- Feature Name: pin_and_move -- Start Date: 2018-02-19 -- RFC PR: (leave this empty) -- Rust Issue: (leave this empty) - -# Summary -[summary]: #summary - -Introduce new APIs to libcore / libstd to serve as safe abstractions for data -which cannot be safely moved around. - -# Motivation -[motivation]: #motivation - -A longstanding problem for Rust has been dealing with types that should not be -moved. A common motivation for this is when a struct contains a pointer into -its own representation - moving that struct would invalidate that pointer. This -use case has become especially important recently with work on generators. -Because generators essentially reify a stackframe into an object that can be -manipulated in code, it is likely for idiomatic usage of a generator to result -in such a self-referential type, if it is allowed. - -This proposal adds an API to std which would allow you to guarantee that a -particular value will never move again, enabling safe APIs that rely on -self-references to exist. - -# Guide-level explanation - -The core goal of this RFC is to **provide a reference type where the referent is guaranteed to never move before being dropped**. We want to do this with a minimum disruption to the type system, and in fact, this RFC shows that we can achieve the goal without *any* type system changes. - -Let's take that goal apart, piece by piece, from the perspective of the futures (i.e. async/await) use case: - -- **Reference type**. The reason we need a reference type is that, when working with things like futures, we generally want to combine smaller futures into larger ones, and only at the top level put an entire resulting future into some immovable location. Thus, we need a reference type for methods like `poll`, so that we can break apart a large future into its smaller components, while retaining the guarantee about immobility. - -- **Never to move before being dropped**. Again looking at the futures case, once we being `poll`ing a future, we want it to be able to store references into itself, which is possible if we can guarantee that the whole future will never move. We don't try to track *whether* such references exist at the type level, since that would involve cumbersome typestate; instead, we simply decree that by the time you initially `poll`, you promise to never move an immobile future again. - -At the same time, we want to support futures (and iterators, etc.) that *can* move. While it's possible to do so by providing two distinct `Future` (or `Iterator`, etc) traits, such designs incur unacceptable ergonomic costs. - -The key insight of this RFC is that we can create a new library type, `Pin<'a, T>`, which encompasses *both* moveable and immobile referents. The type is paired with a new auto trait, `Move`, which determines the meaning of `Pin<'a, T>`: - -- If `T: Move` (which is the default), then `Pin<'a, T>` is entirely equivalent to `&'a mut T`. -- If `T: !Move`, then `Pin<'a, T>` provides a unique reference to a `T` with lifetime `'a`, but only provides `&'a T` access safely. It also guarantees that the referent will *never* be moved. However, getting `&'a mut T` access is unsafe, because operations like `mem::replace` mean that `&mut` access is enough to move data out of the referent; you must promise not to do so. - -To be clear: the *sole* function of `Move` is to control the meaning of `Pin`. Making `Move` an auto trait means that the vast majority of types are automatically "movable", so `Pin` degenerates to `&mut`. In the case that you need immobility, you *opt out* of `Move`, and then `Pin` becomes meaningful for your type. - -Putting this all together, we arrive at the following definition of `Future`: - -```rust -trait Future { - type Item; - type Error; - - fn poll(self: Pin, cx: task::Context) -> Poll; -} -``` - -By default when implementing `Future` for a struct, this definition is equivalent to today's, which takes `&mut self`. But if you want to allow self-referencing in your future, you just opt out of `Move`, and `Pin` takes care of the rest. - -The final piece of this RFC is the `Anchor` type, which is just a `Box` that doesn't allow moving out, but *does* allow you to acquire a `Pin` reference. - -# Reference-level explanation - -## The `Move` auto trait - -This new auto trait is added to the `core::marker` and `std::marker` modules: - -```rust -pub unsafe auto trait Move { } -``` - -A type implements `Move` if in its stack representation, it does not contain -internal references to other positions within its stack representation. Nearly -every type in Rust is `Move`. - -This trait is a lang item, but only to generate negative impls for certain -generators. Unlike previous `?Move` proposals, and unlike some traits like -`Sized` and `Copy`, this trait does not impose any compiler-based semantics -types that do or don't implement it. Instead, the semantics are entirely -enforced through library APIs which use `Move` as a marker. - -## The `Anchor` type - -An anchor is a new kind of smart pointer. It is very much like a box - it is a -heap-allocated, exclusive-ownership type - but it provides additional -constraints. Unless the type it references implements `Move`, it is not -possible to mutably dereference the `Anchor` or move out of it in safe code. It does -implement immutable Deref for all types, including types that don't implement -`Move`. - -```rust -#[fundamental] -struct Anchor { - inner: Box, -} - -impl Anchor { - pub fn new(data: T) -> Anchor; -} - -impl Anchor { - pub fn as_pin<'a>(&'a mut self) -> Pin<'a, T>; - - pub unsafe fn get_mut(this: &mut Anchor) -> &mut T; - - pub unsafe fn into_inner_unchecked(this: Anchor) -> T; -} - -impl Anchor { - pub unsafe fn into_inner(this: Anchor) -> T; -} - -impl Deref for Anchor { - type Target = T; -} - -impl DerefMut for Anchor { } - -unsafe impl Move for Anchor { } -``` - -For types that do not implement `Move`, instead of using mutable references, -users of `Anchor` will use the `Pin` type, described in the next section. - -## The `Pin` type - -The `Pin` type is a wrapper around a mutable reference. If the type it -references is `!Move`, the `Pin` type guarantees that the referenced data will -never be moved again. - -```rust -#[fundamental] -struct Pin<'a, T: ?Sized + 'a> { - data: &'a mut T, -} - -impl<'a, T: ?Sized + Move> Pin<'a, T> { - pub fn new(data: &'a mut T) -> Pin<'a, T>; -} - -impl<'a, T: ?Sized> Pin<'a, T> { - pub unsafe fn new_unchecked(data: &'a mut T) -> Pin<'a, T>; - - pub unsafe fn get_mut(this: Pin<'a, T>) -> &'a mut T; - - pub fn borrow<'b>(this: &'b mut Pin<'a, T>) -> Pin<'b, T>; -} - -impl<'a, T: ?Sized> Deref for Pin<'a, T> { - type Target = T; -} - -impl<'a, T: ?Sized + Move> DerefMut for Pin<'a, T> { } -``` - -For types which implement `Move`, `Pin` is essentially the same as an `&mut T`. -But for types which do not, the conversion between `&mut T` and `Pin` is -unsafe. - -The contract on the unsafe part of `Pin`s API is that a Pin cannot be -constructed if the data it references would ever move again, and that it cannot -be converted into a mutable reference if the data might ever be moved out of -that reference. In other words, if you have a `Pin` containing data which does -not implement `Move`, you have a guarantee that that data will never move. - -The `Anchor` type has a method `as_pin`, which returns a `Pin`, because it -upholds the guarantees necessary to safely construct a `Pin`. - -## Immovable generators - -Today, the unstable generators feature has an option to create generators which -contain references that live across yield points - these are, in effect, -internal references into the generator's state machine. Because internal -references are invalidated if the type is moved, these kinds of generators -("immovable generators") are currently unsafe to create. - -Once the arbitrary_self_types feature becomes object safe, we will make three -changes to the generator API: - -1. We will change the `resume` method to take self by `self: Pin` instead - of `&mut self`. -2. We will implement `!Move` for the anonymous type of an immovable generator. -3. We will make it safe to define an immovable generator. - -This is an example of how the APIs in this RFC allow for self-referential data -types to be created safely. - -# Drawbacks -[drawbacks]: #drawbacks - -This adds additional APIs to std, including an auto trait. Such additions -should not be taken lightly, and only included if they are well-justified by -the abstractions they express. - -# Rationale and alternatives -[alternatives]: #alternatives - -## Comparison to `?Move` - -One previous proposal was to add a built-in `Move` trait, similar to `Sized`. A -type that did not implement `Move` could not be moved after it had been -referenced. - -This solution had some problems. First, the `?Move` bound ended up "infecting" -many different APIs where it wasn't relevant, and introduced a breaking change -in several cases where the API bound changed in a non-backwards compatible way. - -In a certain sense, this proposal is a much more narrowly scoped version of -`?Move`. With `?Move`, *any* reference could act as the "Pin" reference does -here. However, because of this flexibility, the negative consequences of having -a type that can't be moved had a much broader impact. - -Instead, we require APIs to opt into supporting immovability (a niche case) by -operating with the `Pin` type, avoiding "infecting" the basic reference type -with concerns around immovable types. - -## Comparison to using `unsafe` APIs - -Another alternative we've considered was to just have the APIs which require -immovability be `unsafe`. It would be up to the users of these APIs to review -and guarantee that they never moved the self-referential types. For example, -generator would look like this: - -```rust -trait Generator { - type Yield; - type Return; - - unsafe fn resume(&mut self) -> CoResult; -} -``` - -This would require no extensions to the standard library, but would place the -burden on every user who wants to call resume to guarantee (at the risk of -memory insafety) that their types were not moved, or that they were moveable. -This seemed like a worse trade off than adding these APIs. - -## Anchor as a wrapper type and `StableDeref` - -In a previous iteration of this RFC, `Anchor` was a wrapper type that could -"anchor" any smart pointer, and there was a hierarchy of traits relating to the -stability of the referent of different pointer types. - -The primary benefit of this approach was that it was partially integrated with -crates like owning-ref and rental, which also use a hierarchy of stability -traits. However, because of differences in the requirements, the traits used by -owning-ref et al ended up being a non-overlapping subset of the traits proposed -by this RFC from the traits used by the Anchor type. Merging these into a -single hierarchy provided relatively little benefit. - -And the only types that implemented all of the necessary traits to be put into -an Anchor before were `Box` and `Vec`. Because you cannot get mutable -access to the smart pointer (unless the referent implements `Move`), an -`Anchor>` was not really any different from an `Anchor>` in the -previous iteration of the RFC. For this reason, making `Anchor` always a box, -and just supporting `Anchor<[T]>`, reduced the API complexity without losing -any expressiveness. - -## Stack pinning API (potential future extension) - -This API supports "anchoring" `!Move` types in the heap. However, they can also -be safely held in place in the stack, allowing a safe API for creating a `Pin` -referencing a stack allocated `!Move` type. - -This API is small, and does not become a part of anyone's public API. For that -reason, we'll start by allowing it to grow out of tree, in third party crates, -before including it in std. - -## Making `Pin` a built-in type (potential future extension) - -The `Pin` type could instead be a new kind of first-class reference - `&'a pin -T`. This would have some advantages - it would be trivial to project through -fields, for example, and "stack pinning" would not require an API, it would be -natural. However, it has the downside of adding a new reference type, a very -big language change. - -For now, we're happy to stick with the `Pin` struct in std, and if this type is -ever added, turn the `Pin` type into an alias for the reference type. - -# Unresolved questions -[unresolved]: #unresolved-questions - -The names used in this RFC are all entirely up for debate. Some of the items -introduced (especially the `Move` trait) have evolved away from their original -design, making the names a bit of a misnomer (`Move` really means that its safe -to convert between `Pin` and `&mut T`, for example). We want to make sure we -have adequate names before stabilizing these APIs. - -[stable-deref]: https://crates.io/crates/stable_deref_trait From 4c14cad30d43055705f41ba1bd4988522fdde45e Mon Sep 17 00:00:00 2001 From: boats Date: Wed, 7 Mar 2018 18:43:07 -0800 Subject: [PATCH 12/14] Feature name --- text/0000-pin.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0000-pin.md b/text/0000-pin.md index 23b4c732534..ce8c7b8c374 100644 --- a/text/0000-pin.md +++ b/text/0000-pin.md @@ -1,4 +1,4 @@ -- Feature Name: +- Feature Name: pins_and_needles - Start Date: 2018-02-19 - RFC PR: (leave this empty) - Rust Issue: (leave this empty) From 8642b9f65599dafe3a4e90843b40df547b690655 Mon Sep 17 00:00:00 2001 From: boats Date: Wed, 14 Mar 2018 15:28:25 -0700 Subject: [PATCH 13/14] No Pin/PinMut distinction. --- text/0000-pin.md | 149 ++++++++++++++++++++++------------------------- 1 file changed, 70 insertions(+), 79 deletions(-) diff --git a/text/0000-pin.md b/text/0000-pin.md index ce8c7b8c374..8fc851a36bc 100644 --- a/text/0000-pin.md +++ b/text/0000-pin.md @@ -36,12 +36,12 @@ Let's take that goal apart, piece by piece, from the perspective of the futures At the same time, we want to support futures (and iterators, etc.) that *can* move. While it's possible to do so by providing two distinct `Future` (or `Iterator`, etc) traits, such designs incur unacceptable ergonomic costs. -The key insight of this RFC is that we can create a new library type, `PinMut<'a, T>`, which encompasses *both* moveable and immobile referents. The type is paired with a new auto trait, `Unpin`, which determines the meaning of `PinMut<'a, T>`: +The key insight of this RFC is that we can create a new library type, `Pin<'a, T>`, which encompasses *both* moveable and immobile referents. The type is paired with a new auto trait, `Unpin`, which determines the meaning of `Pin<'a, T>`: -- If `T: Unpin` (which is the default), then `PinMut<'a, T>` is entirely equivalent to `&'a mut T`. -- If `T: !Unpin`, then `PinMut<'a, T>` provides a unique reference to a `T` with lifetime `'a`, but only provides `&'a T` access safely. It also guarantees that the referent will *never* be moved. However, getting `&'a mut T` access is unsafe, because operations like `mem::replace` mean that `&mut` access is enough to move data out of the referent; you must promise not to do so. +- If `T: Unpin` (which is the default), then `Pin<'a, T>` is entirely equivalent to `&'a mut T`. +- If `T: !Unpin`, then `Pin<'a, T>` provides a unique reference to a `T` with lifetime `'a`, but only provides `&'a T` access safely. It also guarantees that the referent will *never* be moved. However, getting `&'a mut T` access is unsafe, because operations like `mem::replace` mean that `&mut` access is enough to move data out of the referent; you must promise not to do so. -To be clear: the *sole* function of `Unpin` is to control the meaning of `PinMut`. Making `Unpin` an auto trait means that the vast majority of types are automatically "movable", so `PinMut` degenerates to `&mut`. In the case that you need immobility, you *opt out* of `Unpin`, and then `PinMut` becomes meaningful for your type. +To be clear: the *sole* function of `Unpin` is to control the meaning of `Pin`. Making `Unpin` an auto trait means that the vast majority of types are automatically "movable", so `Pin` degenerates to `&mut`. In the case that you need immobility, you *opt out* of `Unpin`, and then `Pin` becomes meaningful for your type. Putting this all together, we arrive at the following definition of `Future`: @@ -50,13 +50,13 @@ trait Future { type Item; type Error; - fn poll(self: PinMut, cx: task::Context) -> Poll; + fn poll(self: Pin, cx: &mut task::Context) -> Poll; } ``` -By default when implementing `Future` for a struct, this definition is equivalent to today's, which takes `&mut self`. But if you want to allow self-referencing in your future, you just opt out of `Unpin`, and `PinMut` takes care of the rest. +By default when implementing `Future` for a struct, this definition is equivalent to today's, which takes `&mut self`. But if you want to allow self-referencing in your future, you just opt out of `Unpin`, and `Pin` takes care of the rest. -This RFC also provides pinned analogies to `Box` and `&T` - `PinBox` and `Pin`. They work along the same lines as the `PinMut` type discussed here - if the type implements `Unpin`, they function the same as their unpinned varieties; if the type has opted out of `Unpin`, they guarantee that they type behind the reference will not be moved again. +This RFC also provides a pinned analogiy to `Box` called `PinBox`. It work alongs the same lines as the `Pin` type discussed here - if the type implements `Unpin`, it functions the same as the unpinned `Box`; if the type has opted out of `Unpin`, it guarantees that they type behind the reference will not be moved again. # Reference-level explanation @@ -80,109 +80,87 @@ generators. Unlike previous `?Move` proposals, and unlike some traits like types that do or don't implement it. Instead, the semantics are entirely enforced through library APIs which use `Unpin` as a marker. -## `Pin` and `PinMut` +## `Pin` -`Pin` and `PinMut` are two types added to `core::mem` and `std::mem`. They are -analogous to `&T` and `&mut T` respectively. +The `Pin` struct is added to both `core::mem` and `std::mem`. It is a new kind +of reference, with stronger requirements than `&mut T` ```rust #[fundamental] pub struct Pin<'a, T: ?Sized + 'a> { - data: &'a T, -} - -#[fundamental] -pub struct PinMut<'a, T: ?Sized + 'a> { data: &'a mut T, } ``` ### Safe APIs -They both implement `Deref`, but `PinMut` only implements `DerefMut` if the -type it references implements `Unpin`: +`Pin` implements `Deref`, but only implements `DerefMut` if the type it +references implements `Unpin`. This way, it is not safe to call `mem::swap` or +`mem::replace` when the type referenced does not implement `Unpin`. ```rust impl<'a, T: ?Sized> Deref for Pin<'a, T> { ... } -impl<'a, T: ?Sized> Deref for PinMut<'a, T> { ... } - -impl<'a, T: Unpin + ?Sized> DerefMut for PinMut<'a, T> { ... } +impl<'a, T: Unpin + ?Sized> DerefMut for Pin<'a, T> { ... } ``` -They can only be safely constructed from references to types that implement +It can only be safely constructed from references to types that implement `Unpin`: ```rust impl<'a, T: Unpin + ?Sized> Pin<'a, T> { - pub fn new(reference: &'a T) -> Pin<'a, T> { ... } -} - -impl<'a, T: Unpin + ?Sized> PinMut<'a, T> { - pub fn new(reference: &'a mut T) -> PinMut<'a, T> { ... } + pub fn new(reference: &'a mut T) -> Pin<'a, T> { ... } } ``` -They also have a `borrow` function, which allows them to be transformed to pins -with shorter lifetimes as may be necessary: +It also has a function called `borrow`, which allows it to be transformed to a +pin of a shorter lifetime: ```rust impl<'a, T: ?Sized> Pin<'a, T> { - pub fn borrow<'b>(this: &'b Pin<'a, T>) -> Pin<'b, T> { ... } -} - -impl<'a, T: ?Sized> PinMut<'a, T> { - pub fn borrow<'b>(this: &'b PinMut<'a, T>) -> PinMut<'b, T> { ... } + pub fn borrow<'b>(this: &'b mut Pin<'a, T>) -> Pin<'b, T> { ... } } ``` -They may also implement additional APIs as is useful for type conversions, such -as `AsRef`, `From`, and so on. They implement `CoerceUnsized` as necessary to +It may also implement additional APIs as is useful for type conversions, such +as `AsRef`, `From`, and so on. `Pin` implements `CoerceUnsized` as necessary to make coercing them into trait objects possible. ### Unsafe APIs -Both types can be unsafely constructed from references to types which may not -implement `Unpin`. Users who use these constructors must know that the type -they are passing a reference to will never be moved again after the Pin is -constructed. +`Pin` can be unsafely constructed from mutable references to types that may not +implement `Unpin`. Users who use this constructor must know that the type +they are passing a reference to will never be moved again after the `Pin` is +constructed, even after the lifetime of the reference has ended. (For example, +it is always unsafe to construct a `Pin` from a reference you did not create, +because you don't know what will happen once the lifetime of that reference +ends.) ```rust impl<'a, T: ?Sized> Pin<'a, T> { - pub unsafe fn new_unchecked(reference: &'a T) -> Pin<'a, T> { ... } -} - -impl<'a, T: ?Sized> PinMut<'a, T> { - pub unsafe fn new_unchecked(reference: &'a mut T) -> PinMut<'a, T> { ... } + pub unsafe fn new_unchecked(reference: &'a mut T) -> Pin<'a, T> { ... } } ``` -`PinMut` also has an API which allows it to be converted into a mutable -reference for a type that doesn't implement `Unpin`. Users who use this API -must guarantee that they never move out of the mutable reference they receive. +`Pin` also has an API which allows it to be converted into a mutable reference +for a type that doesn't implement `Unpin`. Users who use this API must +guarantee that they never move out of the mutable reference they receive. ```rust -impl<'a, T: ?Sized> PinMut<'a, T> { - pub unsafe fn get_mut<'b>(this: &'b mut PinMut<'a, T>) -> &'b mut T { ... } +impl<'a, T: ?Sized> Pin<'a, T> { + pub unsafe fn get_mut<'b>(this: &'b mut Pin<'a, T>) -> &'b mut T { ... } } ``` -Finally, as a convenience, they both implement an unsafe `map` function, which +Finally, as a convenience, `Pin` implements an unsafe `map` function, which makes it easier to project through a field. Users calling this function must guarantee that the value returned will not move as long as the referent of this pin doesn't move (e.g. it is a private field of the value). They also must not -move out of the mutable reference they receive as the closure argument, in the -case of `PinMut`: +move out of the mutable reference they receive as the closure argument: ```rust impl<'a, T: ?Sized> Pin<'a, T> { - pub unsafe fn map<'b, U, F>(this: &'b Pin<'a, T>, f: F) -> Pin<'b, U> - where F: FnOnce(&T) -> &U - { ... } -} - -impl<'a, T: ?Sized> PinMut<'a, T> { - pub unsafe fn map<'b, U, F>(this: &'b mut PinMut<'a, T>, f: F) -> PinMut<'b, U> + pub unsafe fn map<'b, U, F>(this: &'b mut Pin<'a, T>, f: F) -> Pin<'b, U> where F: FnOnce(&mut T) -> &mut U { ... } } @@ -193,15 +171,20 @@ struct Foo { } let foo_pin: Pin; -// ... -let bar_pin: Pin = unsafe { Pin::map(&foo_pin, |foo| &foo.bar) }; + +let bar_pin: Pin = unsafe { Pin::map(&mut foo_pin, |foo| &mut foo.bar) }; +// Equivalent to: +let bar_pin: Pin = unsafe { + let foo: &mut Foo = Pin::get_mut(&mut foo_pin); + Pin::new_unchecked(&mut foo.bar) +}; ``` ## `PinBox` The `PinBox` type is added to alloc::boxed and std::boxed. It is analogous to -the `Box` type in the same way that `Pin` and `PinMut` are analogous to the -reference types, and it has a similar API. +the `Box` type in the same way that `Pin` is analogous to the reference types, +and it has a similar API. ```rust #[fundamental] @@ -212,8 +195,8 @@ pub struct PinBox { ### Safe API -Unlike the other pin types, it is safe to construct a `PinBox` from a `T` and -from a `Box`: +Unlike `Pin`, it is safe to construct a `PinBox` from a `T` and from a +`Box`, even if the type does not implement `Unpin`: ```rust impl PinBox { @@ -225,7 +208,7 @@ impl From> for PinBox { } ``` -It also provides the same Deref impls as `PinMut` does: +It also provides the same Deref impls as `Pin` does: ```rust impl Deref for PinBox { ... } @@ -239,24 +222,23 @@ If the data implements `Unpin`, its also safe to convert a `PinBox` into a impl From> for Box { ... } ``` -Finally, it is safe to get a `Pin` and a `PinMut` from borrows of `PinBox`: +Finally, it is safe to get a `Pin` from borrows of `PinBox`: ```rust impl PinBox { - fn as_pin<'a>(&'a self) -> Pin<'a, T> { ... } - fn as_pin_mut<'a>(&'a mut self) -> PinMut<'a, T> { ... } + fn as_pin<'a>(&'a mut self) -> Pin<'a, T> { ... } } ``` These APIs make `PinBox` a reasonable way of handling data which does not implement `!Unpin`. Once you heap allocate that data inside of a `PinBox`, you -know that it will never change address again, and you can hand out `Pin` and -`PinMut` references to that data. +know that it will never change address again, and you can hand out `Pin` +references to that data. ### Unsafe API `PinBox` can be unsafely converted into `&mut T` and `Box` even if the type -it references does not implement `Unpin`, similar to `PinMut`: +it references does not implement `Unpin`, similar to `Pin`: ```rust impl PinBox { @@ -276,7 +258,7 @@ references are invalidated if the type is moved, these kinds of generators Once the arbitrary_self_types feature becomes object safe, we will make three changes to the generator API: -1. We will change the `resume` method to take self by `self: PinMut` +1. We will change the `resume` method to take self by `self: Pin` instead of `&mut self`. 2. We will implement `!Unpin` for the anonymous type of an immovable generator. 3. We will make it safe to define an immovable generator. @@ -377,12 +359,8 @@ struct PinTemporary<'a, T: 'a> { } impl<'a, T> PinTemporary<'a, T> { - pub fn into_pin(&'a self) -> Pin<'a, T> { - unsafe { Pin::new_unchecked(&self.data) } - } - - pub fn into_pin_mut(&'a mut self) -> PinMut<'a, T> { - unsafe { PinMut::new_unchecked(&mut self.data) } + pub fn into_pin(&'a mut self) -> Pin<'a, T> { + unsafe { Pin::new_unchecked(&mut self.data) } } } ``` @@ -398,6 +376,19 @@ big language change. For now, we're happy to stick with the `Pin` struct in std, and if this type is ever added, turn the `Pin` type into an alias for the reference type. +## Having both `Pin` and `PinMut` + +Instead of just having `Pin`, the type called `Pin` could instead be `PinMut`, +and we could have a type called `Pin`, which is like `PinMut`, but only +contains a shared, immutable reference. + +Because we've determined that it should be safe to immutably dereference +`Pin`/`PinMut`, this `Pin` type would not provide significant guarantees that a +normal immutable reference does not. If a user needs to pass around references +to data stored pinned, an `&Pin` (under the definition of `Pin` provided in +this RFC) would suffice. For this reason, the `Pin`/`PinMut` distinction +introduced extra types and complexity without any impactful benefit. + # Unresolved questions [unresolved]: #unresolved-questions From 708caf183e71b6495ac86911a6ec3eb77af89403 Mon Sep 17 00:00:00 2001 From: boats Date: Sun, 18 Mar 2018 14:55:12 -0700 Subject: [PATCH 14/14] Add unresolved question for leaking. --- text/0000-pin.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/text/0000-pin.md b/text/0000-pin.md index 8fc851a36bc..7facb8ea260 100644 --- a/text/0000-pin.md +++ b/text/0000-pin.md @@ -396,4 +396,8 @@ In addition to the future extensions discussed above, the APIs of the three pin types in std will grow over time as they implement more common conversion traits and so on. -[stable-deref]: https://crates.io/crates/stable_deref_trait +We may also choose to require that `Pin` uphold stricter guarantees, requiring +that `Unpin` data inside the `Pin` not leak unless the memory remains valid for +the remainder of the program lifetime. This would make the stack API documented +above unsound, but might also enable other APIs to make use of these guarantees +to ensure that a destructor always runs if the memory becomes invalid.