Struct genawaiter::stack::Gen

pub struct Gen<'s, Y, R, F: Future> { /* fields omitted */ }

This is a generator which can be stack-allocated.

See the module-level docs for examples.

Methods

impl<'s, Y, R, F: Future> Gen<'s, Y, R, F>

pub unsafe fn new(
    shelf: &'s mut Shelf<Y, R, F>,
    producer: impl FnOnce(Co<'s, Y, R>) -> F
) -> Self

Creates a new generator from a function.

The state of the generator is stored in shelf, which will be pinned in place while this generator exists. The generator itself is movable, since it just holds a reference to the pinned state.

The function accepts a Co object, and returns a future. Every time the generator is resumed, the future is polled. Each time the future is polled, it should do one of two things:

• Call co.yield_(), and then return Poll::Pending.
• Drop the Co, and then return Poll::Ready.

Typically this exchange will happen in the context of an async fn.

Safety

The Co object must not outlive the returned Gen. By time the generator completes (i.e., by time the producer's Future returns Poll::Ready), the Co object should already have been dropped. If this invariant is not upheld, memory unsafety can result.

Afaik, the Rust compiler is not flexible enough to let you express this invariant in the type system, but I would love to be proven wrong!

Examples

let mut shelf = Shelf::new();
let gen = unsafe { Gen::new(&mut shelf, producer) };

pub fn resume_with(&mut self, arg: R) -> GeneratorState<Y, F::Output>

Resumes execution of the generator.

arg is the resume argument. If the generator was previously paused by awaiting a future returned from co.yield(), that future will complete, and return arg.

If the generator yields a value, Yielded is returned. Otherwise, Completed is returned.

See the module-level docs for examples.

impl<'s, Y, F: Future> Gen<'s, Y, (), F>

pub fn resume(&mut self) -> GeneratorState<Y, F::Output>

Resumes execution of the generator.

If the generator yields a value, Yielded is returned. Otherwise, Completed is returned.

See the module-level docs for examples.

pub fn async_resume(
    &mut self
) -> impl Future<Output = GeneratorState<Y, F::Output>> + '_

Resumes execution of the generator.

If the generator pauses without yielding, Poll::Pending is returned. If the generator yields a value, Poll::Ready(Yielded) is returned. Otherwise, Poll::Ready(Completed) is returned.

See the module-level docs for examples.

Trait Implementations

impl<'s, Y, R, F: Future> Coroutine for Gen<'s, Y, R, F>

type Yield = Y

The type of value this generator yields.

type Resume = R

The type of value this generator accepts as a resume argument.

type Return = F::Output

The type of value this generator returns upon completion.

fn resume_with(
    self: Pin<&mut Self>,
    arg: R
) -> GeneratorState<Self::Yield, Self::Return>

Resumes the execution of this generator.

impl<'s, Y, R, F: Future> Drop for Gen<'s, Y, R, F>

fn drop(&mut self)

Executes the destructor for this type.

impl<'s, Y, F: Future<Output = ()>> IntoIterator for Gen<'s, Y, (), F>

type Item = Y

The type of the elements being iterated over.

type IntoIter = IntoIter<'s, Y, F>

Which kind of iterator are we turning this into?

#[must_use] fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<'r, 's, Y, F: Future<Output = ()>> IntoIterator for &'r mut Gen<'s, Y, (), F>

type Item = Y

The type of the elements being iterated over.

type IntoIter = MutIntoIter<'r, 's, Y, F>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.