core::ops::Generator - Rust
Description: API documentation for the Rust `Generator` trait in crate `core`.
Keywords: rust, rustlang, rust-lang, Generator

# [−][src]Trait core::ops::Generator

    #[lang = "generator"]
    pub trait Generator {
        type Yield;
        type Return;
        unsafe fn resume(&mut self) -> GeneratorState<Self::Yield, Self::Return>;
    }

🔬 This is a nightly-only experimental API. (`generator_trait` #43122)

The trait implemented by builtin generator types.

Generators, also commonly referred to as coroutines, are currently an experimental language feature in Rust. Added in RFC 2033 generators are currently intended to primarily provide a building block for async/await syntax but will likely extend to also providing an ergonomic definition for iterators and other primitives.

The syntax and semantics for generators is unstable and will require a further RFC for stabilization. At this time, though, the syntax is closure-like:

    #![feature(generators, generator_trait)]

    use std::ops::{Generator, GeneratorState};

    fn main() {
        let mut generator = || {
            yield 1;
            return "foo"
        };

        match unsafe { generator.resume() } {
            GeneratorState::Yielded(1) => {}
            _ => panic!("unexpected return from resume"),
        }
        match unsafe { generator.resume() } {
            GeneratorState::Complete("foo") => {}
            _ => panic!("unexpected return from resume"),
        }
    }Run

More documentation of generators can be found in the unstable book.

## Associated Types

### `type Yield`

🔬 This is a nightly-only experimental API. (`generator_trait` #43122)

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.

### `type Return`

🔬 This is a nightly-only experimental API. (`generator_trait` #43122)

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. For example futures would use this as `Result<T, E>` as it represents a completed future.

## Required Methods

### `unsafe fn resume(&mut self) -> GeneratorState<Self::Yield, Self::Return>`

🔬 This is a nightly-only experimental API. (`generator_trait` #43122)

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.

The function is unsafe because it can be used on an immovable generator. After such a call, the immovable generator must not move again, but this is not enforced by the compiler.

# Return value

The `GeneratorState` enum returned from this function indicates what state the generator is in upon returning. If the `Yielded` 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 `Complete` 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 `Complete` variant has been returned previously. While generator literals in the language are guaranteed to panic on resuming after `Complete`, this is not guaranteed for all implementations of the `Generator` trait.

## Implementors

###

`impl<'a, T: ?Sized> Generator for &'a mut T where T: Generator,`

[src]

#### `type Yield = T::Yield`

🔬 This is a nightly-only experimental API. (`generator_trait` #43122)

#### `type Return = T::Return`

🔬 This is a nightly-only experimental API. (`generator_trait` #43122)

####

`unsafe fn resume(&mut self) -> GeneratorState<Self::Yield, Self::Return>`

[src]

🔬 This is a nightly-only experimental API. (`generator_trait` #43122)

# Help

## Keyboard Shortcuts

`?`
  Show this help dialog
`S`
  Focus the search field
`↑`
  Move up in search results
`↓`
  Move down in search results
`↹`
  Switch tab
`⏎`
  Go to active search result
`+`
  Expand all sections
`-`
  Collapse all sections

## Search Tricks

Prefix searches with a type followed by a colon (e.g. `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g. `vec -> usize` or `* -> vec`)

Search multiple things at once by splitting your query with comma (e.g. `str,u8` or `String,struct:Vec,test`)