Trait next_gen::generator::Generator

source · [−]
pub trait Generator<ResumeArg = ()> {
    type Yield;
    type Return;
    fn resume(
        self: Pin<&mut Self>, 
        resume_arg: ResumeArg
    ) -> GeneratorState<Self::Yield, Self::Return>;
}
Expand description

The trait implemented by GeneratorFns.

Generators, also commonly referred to as coroutines, provide an ergonomic definition for iterators and other primitives, allowing to write iterators and iterator adapters in a much more imperative way, which may sometimes improve the readability of such iterators / iterator adapters.

Example

use ::next_gen::prelude::*;

fn main ()
{
    #[generator(yield(i32))]
    fn generator_fn ()
      -> &'static str
    {
        yield_!(1);
        return "foo";
    }

    mk_gen!(let mut generator = generator_fn());

    let mut next = || generator.as_mut().resume(());

    match next() {
        | GeneratorState::Yielded(yielded) => assert_eq!(yielded, 1),
        | GeneratorState::Returned(_) => panic!("unexpected return from resume"),
    }
    match next() {
        | GeneratorState::Yielded(_) => panic!("unexpected yield from resume"),
        | GeneratorState::Returned(returned) => assert_eq!(returned, "foo"),
    }
}

Generator vs. Iterator

  • a Generator can return a non-trivial value when exhausted, contrary to an Iterator,

  • but they require to be Pin-ned in order to be polled.

We thus have the following impls:

impl<Item, R, F>
    Iterator
for
    Pin<&'_ mut (
        GeneratorFn<Item, F, ()>
    )>
where
    GeneratorFn<Item, F, ()> : Generator<(), Yield = Item, Return = R>,

impl<Item, R>
    Iterator
for
    Pin<&'_ mut (
        dyn '_ + Generator<(), Yield = Item, Return = R>
    )>

and, when under #[cfg(feature = "alloc")], we also have:

impl<Item, R, F>
    Iterator
for
    Pin<Box<
        GeneratorFn<Item, F, ()>,
    >>
where
    GeneratorFn<Item, F, ()> : Generator<(), Yield = Item, Return = R>,

impl<Item, R>
    Iterator
for
    Pin<Box<
        dyn '_ + Generator<(), Yield = Item, Return = R>,
    >>
  • A remark regarding the lack of blanket impl and coherence

    Since {,Into}Iterator is defined in ::core, and this definition of Generator is a third-party library one, for coherence reasons, it is not possible to implement {,Into}Iterator for all the impl Generators.

    That being said, the above impls do cover the dyn Generator and GeneratorFn cases, which ought to cover all the #[generator] fn-originating generator instances.

    Should such impls not be enough, there is always the .boxed_gen_into_iter() and .gen_into_iter() methods to convert any pinned generator (provided ResumeArg = ()) into an interator.

Associated Types

The type of value this generator yields.

This associated type corresponds to the yield_! expression and the values which are allowed to be returned each time a generator yields. For example an iterator-as-a-generator would likely have this type as T, the type being iterated over.

The type of value this generator returns.

This corresponds to the type returned from a generator either with a return statement or implicitly as the last expression of a generator literal.

Required methods

Resumes the execution of this generator.

This function will resume execution of the generator or start execution if it hasn’t already. This call will return back into the generator’s last suspension point, resuming execution from the latest yield_!. The generator will continue executing until it either yields or returns, at which point this function will return.

Return value

The GeneratorState enum returned from this function indicates what state the generator is in upon returning.

If the Yield variant is returned then the generator has reached a suspension point and a value has been yielded out. Generators in this state are available for resumption at a later point.

If Return is returned then the generator has completely finished with the value provided. It is invalid for the generator to be resumed again.

Panics

This function may panic if it is called after the Return variant has been returned previously. While generator literals in the language are guaranteed to panic on resuming after Return, this is not guaranteed for all implementations of the Generator trait.

Implementations on Foreign Types

Implementors