Struct corona::Coroutine

pub struct Coroutine { /* fields omitted */ }

A builder of coroutines.

This struct is the main entry point and a way to start coroutines of various kinds. It allows both starting them with default parameters and configuring them with the builder pattern.

Methods

impl Coroutine

fn new(handle: Handle) -> Self

Starts building a coroutine.

This constructor produces a new builder for coroutines. The builder can then be used to specify configuration of the coroutines.

It is possible to spawn multiple coroutines from the same builder.

Parameters

• handle: The coroutines need a reactor core to run on and schedule their control switches. This is the handle to the reactor core to be used.

Examples

use corona::Coroutine;
use futures::stream;
use tokio_core::reactor::Core;

let core = Core::new().unwrap();
let builder = Coroutine::new(core.handle());

let coroutine = builder.spawn(|await| { });

fn with_defaults<R, Task>(handle: Handle, task: Task) -> CoroutineResult<R> where
    R: 'static,
    Task: FnOnce(&Await) -> R + 'static, 

Spawns a coroutine directly.

This constructor spawns a coroutine with default parameters without the inconvenience of handling a builder. It is equivalent to spawning it with an unconfigured builder.

Unlike the spawn, this one can't fail, since the default parameters of the builder are expected to always work (if they don't, file a bug).

Examples

use corona::Coroutine;
use futures::stream;
use tokio_core::reactor::Core;

let core = Core::new().unwrap();

let coroutine = Coroutine::with_defaults(core.handle(), |await| { });

fn spawn<R, Task>(&self, task: Task) -> CoroutineResult<R> where
    R: 'static,
    Task: FnOnce(&Await) -> R + 'static, 

Spawns a coroutine.

Spawns the given closure as a coroutine with the parameters configured in the current builder.

The closure is started right away and is run inside the call until it either yields the control or terminates. If it yields (for whatever reason, not only through the Await::yield_now method), it'll get a chance to continue only through running the reactor core.

Parameters

• task: The closure to run.

Panics

• In case an invalid stack size has been configured. This is a panic and not an error for two reasons. It's very unlikely an application using coroutines could continue if it can't spawn them. Also, configuring invalid stack size is a programmer bug.

Result

On successful call to this method, a Future representing the completion of the task is provided. The future resolves either to the result of the closure or an error if the closure panics.

fn generator<Item, Task>(&self, task: Task) -> GeneratorResult<Item> where
    Item: 'static,
    Task: FnOnce(&Producer<Item>) + 'static, 

Spawns a generator.

A generator is just like a coroutine (and this method is very similar to the spawn method, so most of its notes apply). It can, however, produce a stream of items of a certain kind and has no direct return value. The return value is not a Future, but a Stream of the produced items.

fn stack_size(&mut self, size: usize) -> &mut Self

Configures a stack size for the coroutines.

The method sets the stack size of the coroutines that'll be spawned from this builder. The default stack size is platform dependent, but usually something relatively small. It is fine for most uses that don't use recursion or big on-stack allocations.

Also, using too many different stack sizes in the same thread is inefficient. The library caches and reuses stacks, but it can do so only with stacks of the same size.

Notes

If the configured stack size is invalid, attempts to spawn coroutines will fail with a panic. However, it is platform dependent what is considered valid (multiples of 4096 usually work).

fn leak_on_panic(&mut self, leak: bool) -> &mut Self

Configures the leak on panic option.

If the reactor Core is dropped, any outstanding coroutines are cleaned up by panicking from the function they block on (if it is not one of the _cleanup variants). However, if the Core is dropped during panick, panicking inside the coroutine would abort the program.

This option allows skipping the cleanups. Instead of aborting the program, the resources on the coroutines' stacks are leaked.

The _cleanup routines still return Err(Dropped) and allow for manual cleanup.

Trait Implementations

impl Clone for Coroutine

fn clone(&self) -> Coroutine

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.