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ยง
pub use by_move_body::coroutine_by_move_body_def_id;
Modulesยง
- by_
move_ ๐body This pass constructs a second coroutine body sufficient for return fromFnOnce
/AsyncFnOnce
implementations for coroutine-closures (e.g. async closures).
Structsยง
- Coroutine
Saved ๐Locals The set ofLocal
s that must be saved across yield points. - Deref
ArgVisitor ๐ - 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 - Liveness
Info ๐ - PinArg
Visitor ๐ - Rename
Local ๐Visitor - Suspend
Check ๐Data - Suspension
Point ๐Ayield
point in the coroutine. - Transform
Visitor ๐
Enumsยง
- Operation ๐An operation that can be performed on a coroutine.
Constantsยง
- POISONED ๐Coroutine has panicked and is poisoned.
- RESERVE
D_ ๐VARIANTS Number of reserved variants of coroutine state. - RETURNED ๐Coroutine has returned / is completed.
- SELF_
ARG ๐ - UNRESUMED ๐Coroutine has not been resumed yet.
Functionsยง
- can_
return ๐ - can_
unwind ๐ - check_
suspend_ ๐tys - compute_
layout ๐ - 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 ๐ - insert_
clean_ ๐drop - insert_
panic_ ๐block - insert_
switch ๐Replaces the entry point ofbody
with a block that switches on the coroutine discriminant and dispatches to blocks according tocases
. - insert_
term_ ๐block - Computes which locals have to be stored in the state-machine for the given coroutine.
- replace_
base ๐ - replace_
local ๐Allocates a new local and replaces all references oflocal
with it. Returns the new local. - Transforms the
body
of the coroutine applying the following transforms: - Transforms the
body
of the coroutine applying the following transform: