Module rustc_mir_transform::coroutine

source ยท
Expand description

This is the implementation of the pass which transforms coroutines into state machines.

MIR generation for coroutines creates a function which has a self argument which passes by value. This argument is effectively a coroutine type which only contains upvars and is only used for this argument inside the MIR for the coroutine. It is passed by value to enable upvars to be moved out of it. Drop elaboration runs on that MIR before this pass and creates drop flags for MIR locals. It will also drop the coroutine argument (which only consists of upvars) if any of the upvars are moved out of. This pass elaborates the drops of upvars / coroutine argument in the case that none of the upvars were moved out of. This is because we cannot have any drops of this coroutine in the MIR, since it is used to create the drop glue for the coroutine. Weโ€™d get infinite recursion otherwise.

This pass creates the implementation for either the Coroutine::resume or Future::poll function and the drop shim for the coroutine based on the MIR input. It converts the coroutine argument from Self to &mut Self adding derefs in the MIR as needed. It computes the final layout of the coroutine struct which looks like this: First upvars are stored It is followed by the coroutine state field. Then finally the MIR locals which are live across a suspension point are stored. ignore (illustrative) struct Coroutine { upvars..., state: u32, mir_locals..., } This pass computes the meaning of the state field and the MIR locals which are live across a suspension point. There are however three hardcoded coroutine states: 0 - Coroutine have not been resumed yet 1 - Coroutine has returned / is completed 2 - Coroutine has been poisoned

It also rewrites return x and yield y as setting a new coroutine state and returning CoroutineState::Complete(x) and CoroutineState::Yielded(y), or Poll::Ready(x) and Poll::Pending respectively. MIR locals which are live across a suspension point are moved to the coroutine struct with references to them being updated with references to the coroutine struct.

The pass creates two functions which have a switch on the coroutine state giving the action to take.

One of them is the implementation of Coroutine::resume / Future::poll. For coroutines with state 0 (unresumed) it starts the execution of the coroutine. For coroutines with state 1 (returned) and state 2 (poisoned) it panics. Otherwise it continues the execution from the last suspension point.

The other function is the drop glue for the coroutine. For coroutines with state 0 (unresumed) it drops the upvars of the coroutine. For coroutines with state 1 (returned) and state 2 (poisoned) it does nothing. Otherwise it drops all the values in scope at the last suspension point.

Re-exportsยง

Modulesยง

  • by_move_body ๐Ÿ”’
    This pass constructs a second coroutine body sufficient for return from FnOnce/AsyncFnOnce implementations for coroutine-closures (e.g. async closures).

Structsยง

Enumsยง

  • Operation ๐Ÿ”’
    An operation that can be performed on a coroutine.

Constantsยง

  • POISONED ๐Ÿ”’
    Coroutine has panicked and is poisoned.
  • RESERVED_VARIANTS ๐Ÿ”’
    Number of variants to reserve in coroutine state. Corresponds to UNRESUMED (beginning of a coroutine) and RETURNED/POISONED (end of a coroutine) states.
  • RETURNED ๐Ÿ”’
    Coroutine has returned / is completed.
  • SELF_ARG ๐Ÿ”’
  • UNRESUMED ๐Ÿ”’
    Coroutine has not been resumed yet.

Functionsยง