11use crate :: marker:: Unpin ;
22use crate :: pin:: Pin ;
33
4- /// The result of a generator resumption.
4+ /// The result of a coroutine resumption.
55///
66/// This enum is returned from the `Coroutine::resume` method and indicates the
7- /// possible return values of a generator . Currently this corresponds to either
7+ /// possible return values of a coroutine . Currently this corresponds to either
88/// a suspension point (`Yielded`) or a termination point (`Complete`).
99#[ derive( Clone , Copy , PartialEq , PartialOrd , Eq , Ord , Debug , Hash ) ]
10- #[ lang = "generator_state" ]
11- #[ unstable( feature = "generator_trait" , issue = "43122" ) ]
10+ #[ cfg_attr( bootstrap, lang = "generator_state" ) ]
11+ #[ cfg_attr( not( bootstrap) , lang = "coroutine_state" ) ]
12+ #[ unstable( feature = "coroutine_trait" , issue = "43122" ) ]
1213pub enum CoroutineState < Y , R > {
13- /// The generator suspended with a value.
14+ /// The coroutine suspended with a value.
1415///
15- /// This state indicates that a generator has been suspended, and typically
16+ /// This state indicates that a coroutine has been suspended, and typically
1617/// corresponds to a `yield` statement. The value provided in this variant
17- /// corresponds to the expression passed to `yield` and allows generators to
18+ /// corresponds to the expression passed to `yield` and allows coroutines to
1819/// provide a value each time they yield.
1920Yielded ( Y ) ,
2021
21- /// The generator completed with a return value.
22+ /// The coroutine completed with a return value.
2223///
23- /// This state indicates that a generator has finished execution with the
24- /// provided value. Once a generator has returned `Complete` it is
24+ /// This state indicates that a coroutine has finished execution with the
25+ /// provided value. Once a coroutine has returned `Complete` it is
2526/// considered a programmer error to call `resume` again.
2627Complete ( R ) ,
2728}
2829
29- /// The trait implemented by builtin generator types.
30+ /// The trait implemented by builtin coroutine types.
3031///
3132/// Coroutines, also commonly referred to as coroutines, are currently an
32- /// experimental language feature in Rust. Added in [RFC 2033] generators are
33+ /// experimental language feature in Rust. Added in [RFC 2033] coroutines are
3334/// currently intended to primarily provide a building block for async/await
3435/// syntax but will likely extend to also providing an ergonomic definition for
3536/// iterators and other primitives.
3637///
37- /// The syntax and semantics for generators is unstable and will require a
38+ /// The syntax and semantics for coroutines is unstable and will require a
3839/// further RFC for stabilization. At this time, though, the syntax is
3940/// closure-like:
4041///
4142/// ```rust
42- /// #![feature(generators, generator_trait )]
43+ /// #![feature(coroutines, coroutine_trait )]
4344///
4445/// use std::ops::{Coroutine, CoroutineState};
4546/// use std::pin::Pin;
4647///
4748/// fn main() {
48- /// let mut generator = || {
49+ /// let mut coroutine = || {
4950/// yield 1;
5051/// "foo"
5152/// };
5253///
53- /// match Pin::new(&mut generator ).resume(()) {
54+ /// match Pin::new(&mut coroutine ).resume(()) {
5455/// CoroutineState::Yielded(1) => {}
5556/// _ => panic!("unexpected return from resume"),
5657/// }
57- /// match Pin::new(&mut generator ).resume(()) {
58+ /// match Pin::new(&mut coroutine ).resume(()) {
5859/// CoroutineState::Complete("foo") => {}
5960/// _ => panic!("unexpected return from resume"),
6061/// }
6162/// }
6263/// ```
6364///
64- /// More documentation of generators can be found in the [unstable book].
65+ /// More documentation of coroutines can be found in the [unstable book].
6566///
6667/// [RFC 2033]: https://github.com/rust-lang/rfcs/pull/2033
67- /// [unstable book]: ../../unstable-book/language-features/generators.html
68- #[ lang = "generator" ]
69- #[ unstable( feature = "generator_trait" , issue = "43122" ) ]
68+ /// [unstable book]: ../../unstable-book/language-features/coroutines.html
69+ #[ cfg_attr( bootstrap, lang = "generator" ) ]
70+ #[ cfg_attr( not( bootstrap) , lang = "coroutine" ) ]
71+ #[ unstable( feature = "coroutine_trait" , issue = "43122" ) ]
7072#[ fundamental]
7173pub trait Coroutine < R = ( ) > {
72- /// The type of value this generator yields.
74+ /// The type of value this coroutine yields.
7375///
7476/// This associated type corresponds to the `yield` expression and the
75- /// values which are allowed to be returned each time a generator yields.
76- /// For example an iterator-as-a-generator would likely have this type as
77+ /// values which are allowed to be returned each time a coroutine yields.
78+ /// For example an iterator-as-a-coroutine would likely have this type as
7779/// `T`, the type being iterated over.
7880type Yield ;
7981
80- /// The type of value this generator returns.
82+ /// The type of value this coroutine returns.
8183///
82- /// This corresponds to the type returned from a generator either with a
83- /// `return` statement or implicitly as the last expression of a generator
84+ /// This corresponds to the type returned from a coroutine either with a
85+ /// `return` statement or implicitly as the last expression of a coroutine
8486/// literal. For example futures would use this as `Result<T, E>` as it
8587/// represents a completed future.
8688type Return ;
8789
88- /// Resumes the execution of this generator .
90+ /// Resumes the execution of this coroutine .
8991///
90- /// This function will resume execution of the generator or start execution
91- /// if it hasn't already. This call will return back into the generator 's
92+ /// This function will resume execution of the coroutine or start execution
93+ /// if it hasn't already. This call will return back into the coroutine 's
9294/// last suspension point, resuming execution from the latest `yield`. The
93- /// generator will continue executing until it either yields or returns, at
95+ /// coroutine will continue executing until it either yields or returns, at
9496/// which point this function will return.
9597///
9698/// # Return value
9799///
98100/// The `CoroutineState` enum returned from this function indicates what
99- /// state the generator is in upon returning. If the `Yielded` variant is
100- /// returned then the generator has reached a suspension point and a value
101+ /// state the coroutine is in upon returning. If the `Yielded` variant is
102+ /// returned then the coroutine has reached a suspension point and a value
101103/// has been yielded out. Coroutines in this state are available for
102104/// resumption at a later point.
103105///
104- /// If `Complete` is returned then the generator has completely finished
105- /// with the value provided. It is invalid for the generator to be resumed
106+ /// If `Complete` is returned then the coroutine has completely finished
107+ /// with the value provided. It is invalid for the coroutine to be resumed
106108/// again.
107109///
108110/// # Panics
109111///
110112/// This function may panic if it is called after the `Complete` variant has
111- /// been returned previously. While generator literals in the language are
113+ /// been returned previously. While coroutine literals in the language are
112114/// guaranteed to panic on resuming after `Complete`, this is not guaranteed
113115/// for all implementations of the `Coroutine` trait.
114116fn resume ( self : Pin < & mut Self > , arg : R ) -> CoroutineState < Self :: Yield , Self :: Return > ;
115117}
116118
117- #[ unstable( feature = "generator_trait " , issue = "43122" ) ]
119+ #[ unstable( feature = "coroutine_trait " , issue = "43122" ) ]
118120impl < G : ?Sized + Coroutine < R > , R > Coroutine < R > for Pin < & mut G > {
119121 type Yield = G :: Yield ;
120122 type Return = G :: Return ;
@@ -124,7 +126,7 @@ impl<G: ?Sized + Coroutine<R>, R> Coroutine<R> for Pin<&mut G> {
124126 }
125127}
126128
127- #[ unstable( feature = "generator_trait " , issue = "43122" ) ]
129+ #[ unstable( feature = "coroutine_trait " , issue = "43122" ) ]
128130impl < G : ?Sized + Coroutine < R > + Unpin , R > Coroutine < R > for & mut G {
129131 type Yield = G :: Yield ;
130132 type Return = G :: Return ;
0 commit comments