src/doc/reference/src/expressions/await-expr.md

   1 # Await expressions
   2
   3 > **<sup>Syntax</sup>**\
   4 > _AwaitExpression_ :\
   5 > &nbsp;&nbsp; [_Expression_] `.` `await`
   6
   7 Await expressions are legal only within an [async context], like an
   8 [`async fn`] or an [`async` block]. They operate on a [future]. Their effect
   9 is to suspend the current computation until the given future is ready
  10 to produce a value.
  11
  12 More specifically, an `<expr>.await` expression has the following effect.
  13
  14 1. Evaluate `<expr>` to a [future] `tmp`;
  15 2. Pin `tmp` using [`Pin::new_unchecked`];
  16 3. This pinned future is then polled by calling the [`Future::poll`] method and
  17    passing it the current [task context](#task-context);
  18 3. If the call to `poll` returns [`Poll::Pending`], then the future
  19    returns `Poll::Pending`, suspending its state so that, when the
  20    surrounding async context is re-polled, execution returns to step
  21    2;
  22 4. Otherwise the call to `poll` must have returned [`Poll::Ready`], in which case the
  23    value contained in the [`Poll::Ready`] variant is used as the result
  24    of the `await` expression itself.
  25
  26 [`async fn`]: ../items/functions.md#async-functions
  27 [`async` block]: block-expr.md#async-blocks
  28 [future]: ../../std/future/trait.Future.html
  29 [_Expression_]: ../expressions.md
  30 [`Future::poll`]: ../../std/future/trait.Future.html#tymethod.poll
  31 [`Context`]: ../../std/task/struct.Context.html
  32 [`Pin::new_unchecked`]: ../../std/pin/struct.Pin.html#method.new_unchecked
  33 [`Poll::Pending`]: ../../std/task/enum.Poll.html#variant.Pending
  34 [`Poll::Ready`]: ../../std/task/enum.Poll.html#variant.Ready
  35
  36 > **Edition differences**: Await expressions are only available beginning with
  37 > Rust 2018.
  38
  39 ## Task context
  40
  41 The task context refers to the [`Context`] which was supplied to the
  42 current [async context] when the async context itself was
  43 polled. Because `await` expressions are only legal in an async
  44 context, there must be some task context available.
  45
  46 [`Context`]: ../../std/task/struct.Context.html
  47 [async context]: ../expressions/block-expr.md#async-context
  48
  49 ## Approximate desugaring
  50
  51 Effectively, an `<expr>.await` expression is roughly
  52 equivalent to the following (this desugaring is not normative):
  53
  54 <!-- ignore: example expansion -->
  55 ```rust,ignore
  56 match /* <expr> */ {
  57     mut pinned => loop {
  58         let mut pin = unsafe { Pin::new_unchecked(&mut pinned) };
  59         match Pin::future::poll(Pin::borrow(&mut pin), &mut current_context) {
  60             Poll::Ready(r) => break r,
  61             Poll::Pending => yield Poll::Pending,
  62         }
  63     }
  64 }
  65 ```
  66
  67 where the `yield` pseudo-code returns `Poll::Pending` and, when
  68 re-invoked, resumes execution from that point. The variable
  69 `current_context` refers to the context taken from the async
  70 environment.