Module coroutine

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.

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

• CoroutineSavedLocals 🔒
  The set of Locals that must be saved across yield points.
• EnsureCoroutineFieldAssignmentsNeverAlias 🔒
  Looks for any assignments between locals (e.g., _4 = _5) that will both be converted to fields in the coroutine state machine but whose storage is not marked as conflicting
• LivenessInfo 🔒
• RenameLocalVisitor 🔒
• SelfArgVisitor 🔒
• StateTransform 🔒
• StorageConflictVisitor 🔒
• SuspendCheckData 🔒
• SuspensionPoint 🔒
  A yield point in the coroutine.
• TransformVisitor 🔒

Enums

• Operation 🔒
  An operation that can be performed on a coroutine.

Constants

• SELF_ARG 🔒

Functions

• can_return 🔒
• can_unwind 🔒
• check_field_tys_sized 🔒
• check_must_not_suspend_def 🔒
• check_must_not_suspend_ty 🔒
• check_suspend_tys 🔒
• compute_layout 🔒
• compute_storage_conflicts 🔒
  For every saved local, looks for which locals are StorageLive at the same time. Generates a bitset for every local of all the other locals that may be StorageLive simultaneously with that local. This is used in the layout computation; see CoroutineLayout for more.
• create_cases 🔒
• create_coroutine_drop_shim 🔒
• create_coroutine_resume_function 🔒
• elaborate_coroutine_drops 🔒
• eliminate_get_context_call 🔒
• insert_clean_drop 🔒
• insert_panic_block 🔒
• insert_switch 🔒
  Replaces the entry point of body with a block that switches on the coroutine discriminant and dispatches to blocks according to cases.
• insert_term_block 🔒
• locals_live_across_suspend_points 🔒
  Computes which locals have to be stored in the state-machine for the given coroutine.
• make_aggregate_adt 🔒
• make_coroutine_state_argument_indirect 🔒
• make_coroutine_state_argument_pinned 🔒
• mir_coroutine_witnesses 🔒
• replace_base 🔒
• replace_local 🔒
  Allocates a new local and replaces all references of local with it. Returns the new local.
• replace_resume_ty_local 🔒
• transform_async_context 🔒
  Transforms the body of the coroutine applying the following transforms:
• transform_gen_context 🔒
  Transforms the body of the coroutine applying the following transform: