Struct corona::coroutine::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

pub fn new() -> 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.

Examples

use corona::Coroutine;
use tokio::prelude::*;
use tokio::runtime::current_thread;

Coroutine::new()
    .run(|| {})
    .unwrap();

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

Configures the stack size used for coroutines.

Coroutines spawned from this builder will get stack of this size. The default is something small, so if you use recursion, you might want to use this.

The stack size might be rounded up to a valid platform-dependent stack size (usually the nearest multiple of 4096).

It is possible the stack size would still be invalid after this rounding up on given platform (eg. too large). In such case, attempts to spawn coroutines will fail with error.

Parameters

• size: The stack size to use for newly spawned coroutines, in bytes.

pub fn cleanup_strategy(&mut self, strategy: CleanupStrategy) -> &mut Self

Configures how the coroutines should be cleaned up if the core is dropped before the coroutine resolves.

See the details of CleanupStrategy.

pub fn with_defaults<R, Task>(task: Task) -> CoroutineResult<R> where
    R: 'static,
    Task: FnOnce() -> 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).

Parameters

• task: The closure to run inside the coroutine.

Returns

A future that'll resolve once the coroutine completes, with the result of the task, or with an error explaining why the coroutine failed.

Examples

use corona::Coroutine;
use tokio::prelude::*;
use tokio::runtime::current_thread;

current_thread::block_on_all(future::lazy(|| {
    Coroutine::with_defaults(|| {})
})).unwrap();

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

Spawns a coroutine with configuration from the builder.

This spawns a new coroutine with the values previously set in the builder.

Parameters

• task: The closure to run inside the coroutine.

Returns

A future that'll resolve once the coroutine terminates and will yield the result of task, or an error explaining why the coroutine failed.

This returns a StackError if the configured stack size is invalid.

Examples

use corona::Coroutine;
use tokio::prelude::*;
use tokio::runtime::current_thread;

Coroutine::new()
    .stack_size(40_960)
    .run(|| { })
    .unwrap();

Panic handling

If the coroutine panics, the panic is propagated. This usually means the executor, unless the panic happens before the first suspension point, in which case it is the spawn itself which panics.

pub fn spawn_catch_panic<R, Task>(
    &self,
    task: Task
) -> Result<CoroutineResult<R>, StackError> where
    R: 'static,
    Task: FnOnce() -> R + UnwindSafe + 'static, 

Spawns a coroutine, preventing the panics in it from killing the parent task.

This is just like spawn, but any panic in the coroutine is captured and returned through the result instead of propagating.

Note that you need to ensure the task is unwind safe for that reason.

pub fn wait<I, E, Fut>(fut: Fut) -> Result<Result<I, E>, Dropped> where
    Fut: Future<Item = I, Error = E>, 

Waits for completion of a future.

This suspends the execution of the current coroutine until the provided future is completed, possibly switching to other coroutines in the meantime.

This is the low-level implementation of the waiting. It is expected user code will use the interface in prelude instead.

Parameters

• fut: The future to wait on.

Returns

• Ok(result) with the result the future resolved to (which is in itself a Result).
• Err(Dropped) when the executor was dropped before the future had a chance to resolve.

Panics

If called outside of a coroutine (there's nothing to suspend).

Also, panics from within the provided future are propagated into the calling coroutine.

pub fn verify(&self) -> Result<(), StackError>

Checks if the current configuration is able spawn coroutines.

The ability of a configuration is deterministic on the given system. Therefore, it is possible to check if further coroutines spawned by this builder would succeed. This does the check.

pub fn set_thread_local(&self) -> Result<(), StackError>

Puts the builder into a thread-local storage.

This first verifies (see verify) the configuration in the builder is usable and then sets it into a thread-local storage.

The thread-local storage is then used by the spawn stand-alone function (in contrast to the spawn method).

If the verification fails, the original value is preserved. If not called, the thread-local storage contains a default configuration created by Coroutine::new.

pub fn from_thread_local() -> Self

Gets a copy of the builder in thread-local storage.

This may help if you want to use the same builder as spawn does, but you want to do something more fancy, like spawn_catch_panic.

pub fn run<R, Task>(&self, task: Task) -> Result<R, StackError> where
    R: 'static,
    Task: FnOnce() -> R + 'static, 

Starts a whole runtime and waits for a main coroutine.

While it is possible to create the tokio::runtime::current_thread::Runtime manually, feed it with a lazy future and then run a coroutine inside it (or reuse the runtime when something else creates it), this method is provided to take care of all these things, making it more convenient.

In addition to starting the main coroutine passed to it, it sets the coroutine builder into a thread-local storage (see set_thread_local.

extern crate corona;
extern crate tokio;

use corona::prelude::*;
use corona::spawn;
use tokio::prelude::*;

let result = Coroutine::new()
    // 40kB of stack size for all the coroutines.
    .stack_size(40960)
    .run(|| {
        // Everything (builder in thread local storage, coroutine, tokio runtime) is set up
        // in here.
        future::ok::<(), ()>(()).coro_wait();
        let sub_coroutine = spawn(|| {
            42
        });
        sub_coroutine.coro_wait().unwrap()
    }).unwrap();
assert_eq!(42, result);

Trait Implementations

impl Default for Coroutine

fn default() -> Self

Returns the "default value" for a type.

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.

impl Debug for Coroutine

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.