,
62 | }
63 |
64 | fn make_foo() {
65 | let s = vec![1, 2, 3];
66 | let p = &s;
67 |
68 | let foo = AlmostFoo { s, p };
69 |
70 | do_stuff(foo); // call a function that expects an AlmostFoo
71 | }
72 | ```
73 |
74 | Of course `make_foo()` cannot return an `AlmostFoo` instance since it would be
75 | referencing values from its stack, but what it can do is call other functions
76 | and pass an `AlmostFoo` to them. In other words, as long as the code that wants
77 | to use `AlmostFoo` is above `make_foo()` we can use this technique and work
78 | with almost-self-references.
79 |
80 | 
81 |
82 | This is pretty restrictive though. Ideally we'd lke to be able return some
83 | owned value and be free to move it around, put it on the heap, etc.
84 |
85 | ### Actually returning an `AlmostFoo`
86 |
87 | > **Note:** The description of async stacks bellow is not what actually happens
88 | > in rustc but is enough to illustrate the point. `escher`'s API does make use
89 | > that the desired values are held across an await point to force them to be
90 | > included in the generated Future.
91 |
92 | As we saw, it is impossible to return an `AlmostFoo` instance since it
93 | references values from the stack. But what if we could freeze the stack after
94 | an `AlmostFoo` instance got constructed and then returned the whole stack?
95 |
96 | Well, there is no way for a regular function to capture its own stack and
97 | return it but that is exactly what the async/await transformation does! Let's
98 | make `make_foo` from above async and also make it never terminate:
99 |
100 | ```rust
101 | async fn make_foo() {
102 | let s = vec![1, 2, 3];
103 | let p = &s;
104 | let foo = AlmostFoo { s, p };
105 | std::future::pending().await
106 | }
107 | ```
108 |
109 | Now when someone calls `make_foo()` what they get back is some struct that
110 | implements Future. This struct is in fact a representation of the stack of
111 | `make_foo` at its initial state, i.e in the state that the function has not be
112 | called yet.
113 |
114 | What we need to do now is to step the execution of the returned Future until
115 | the instance of `AlmostFoo` is constructed. In this case we know that there is
116 | a single await point so we only need to poll the Future once. Before we do that
117 | though we need to put it in a Pinned Box to ensure that as we poll the future
118 | no moves will occur. This is the same restriction as with normal function but
119 | with async it is enforced using the `Pin` type.
120 |
121 | ```rust
122 | let foo = make_foo(); // construct a stack that will eventually make an AlmostFoo in it
123 | let mut foo = Box::pin(foo_fut); // pin it so that it never moves again
124 | foo.poll(); // poll it once
125 |
126 | // now we know that somewhere inside `foo` there is a valid AlmostFoo instance!
127 | ```
128 |
129 | We're almost there! We now have an owned value, the future, that somewhere
130 | inside it has an AlmostFoo instance. However we have no way of retrieving the
131 | exact memory location of it or accessing it in any way. The Future is opaque.
132 |
133 | 
134 |
135 | ### Putting it all together
136 |
137 | `escher` builds upon the techniques described above and provides a solution for
138 | getting the pointer from within the opaque future struct. Each `Escher`
139 | instance holds a Pinned Future and a raw pointer to T. The pointer to T is
140 | computed by polling the Future just enough times for the desired T to be
141 | constructed.
142 |
143 | As its API, it provides the `as_ref()` and `as_mut()` methods that unsafely
144 | turn the raw pointer to T into a &T with its lifetime bound to the lifetime of
145 | `Escher` itself. This ensures that the future will outlive any usage of the
146 | self-reference!
147 |
148 | Thank you for reading this far! If you would like to learn how escher uses the
149 | above concepts in detail please take a look at the implementation.
150 |
151 | ## License
152 |
153 | Licensed under either of
154 |
155 | * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or https://www.apache.org/licenses/LICENSE-2.0)
156 | * MIT license ([LICENSE-MIT](LICENSE-MIT) or https://opensource.org/licenses/MIT)
157 |
158 | at your option.
159 |
160 | ### Contribution
161 |
162 | Unless you explicitly state otherwise, any contribution intentionally
163 | submitted for inclusion in the work by you, as defined in the Apache-2.0
164 | license, shall be dual licensed as above, without any additional terms or
165 | conditions.
166 |
--------------------------------------------------------------------------------
/escher/src/escher.rs:
--------------------------------------------------------------------------------
1 | use std::future::Future;
2 | use std::pin::Pin;
3 | use std::ptr::NonNull;
4 | use std::sync::atomic::{AtomicPtr, Ordering};
5 | use std::sync::Arc;
6 | use std::task::Context;
7 |
8 | use futures_task::noop_waker;
9 |
10 | /// The `RebindTo` trait defines a type level function that allows you convert a type that holds
11 | /// references of lifetime `'a` to a type that holds references of lifetime `'b`.
12 | ///
13 | /// The trait is unsafe because the implementer needs to make sure that the associated type
14 | /// differs with the implementing type only on their lifetimes. In other words, it's meant to
15 | /// prevent incantations like:
16 | ///
17 | /// ```ignore
18 | /// unsafe impl<'a> RebindTo<'a> for Foo<'_> {
19 | /// type Out = Bar<'a>; // !!WRONG!!
20 | /// }
21 | ///
22 | /// unsafe impl<'a> RebindTo<'a> for Foo<'_> {
23 | /// type Out = Foo<'a>; // CORRECT
24 | /// }
25 | /// ```
26 | ///
27 | /// Users should avoid implementing this trait manually and derive
28 | /// [Rebindable](escher_derive::Rebindable) instead.
29 | pub unsafe trait RebindTo<'a> {
30 | type Out: 'a;
31 | }
32 |
33 | /// Blanket implementation for any reference to owned data
34 | unsafe impl<'a, T: ?Sized + 'static> RebindTo<'a> for &'_ T {
35 | type Out = &'a T;
36 | }
37 |
38 | /// Blanket implementation for any mutable reference to owned data
39 | unsafe impl<'a, T: ?Sized + 'static> RebindTo<'a> for &'_ mut T {
40 | type Out = &'a mut T;
41 | }
42 |
43 | /// Marker trait for any type that implements [RebindTo] for any lifetime. All types can derive
44 | /// this trait using the [Rebindable](escher_derive::Rebindable) derive macro.
45 | pub trait Rebindable: for<'a> RebindTo<'a> {
46 | fn rebind<'short, 'long: 'short>(&'long self) -> &'short Rebind<'short, Self>
47 | where Self: 'long;
48 | }
49 |
50 | /// Type-level function that takes a lifetime `'a` and a type `T` computes a new type `U` that is
51 | /// identical to `T` except for its lifetimes that are now bound to `'a`.
52 | ///
53 | /// A type `T` must implement [Rebindable] in order to use this type level function.
54 | ///
55 | /// For example:
56 | ///
57 | /// * `Rebind<'a, &'static str> == &'a str`
58 | /// * `Rebind<'static, &'a str> == &'static str`
59 | /// * `Rebind<'c, T<'a, 'b>> == T<'c, 'c>`
60 | pub type Rebind<'a, T> = >::Out;
61 |
62 | /// A containter of a self referencial struct. The self-referencial struct is constructed with the
63 | /// aid of the async/await machinery of rustc, see [Escher::new].
64 | pub struct Escher<'fut, T> {
65 | _fut: Pin + 'fut>>,
66 | ptr: NonNull,
67 | }
68 |
69 | impl<'fut, T: Rebindable> Escher<'fut, T> {
70 | /// Construct a self referencial struct using the provided closure. The user is expected to
71 | /// construct the desired data and references to them in the async stack and capture the
72 | /// desired state when ready.
73 | ///
74 | /// ```rust
75 | /// use escher::{Escher, Rebindable};
76 | ///
77 | /// #[derive(Rebindable)]
78 | /// struct MyStr<'a>(&'a str);
79 | ///
80 | /// let escher_heart = Escher::new(|r| async move {
81 | /// let data: Vec = vec![240, 159, 146, 150];
82 | /// let sparkle_heart = std::str::from_utf8(&data).unwrap();
83 | ///
84 | /// r.capture(MyStr(sparkle_heart)).await;
85 | /// });
86 | ///
87 | /// assert_eq!("💖", escher_heart.as_ref().0);
88 | /// ```
89 | pub fn new(builder: B) -> Self
90 | where
91 | B: FnOnce(Capturer) -> F,
92 | F: Future
910 |
911 | 
1002 |
1003 | 
167 | 
212 | 
268 |