Struct may::coroutine::Builder

pub struct Builder { /* private fields */ }

Coroutine factory, which can be used in order to configure the properties of a new coroutine.

Methods can be chained on it in order to configure it.

The two configurations available are:

• name: specifies an associated name for the coroutine
• stack_size: specifies the desired stack size for the coroutine

The spawn method will take ownership of the builder and create an io::Result to the coroutine handle with the given configuration.

The coroutine::spawn free function uses a Builder with default configuration and unwraps its return value.

You may want to use spawn instead of coroutine::spawn, when you want to recover from a failure to launch a coroutine, indeed the free function will panics where the Builder method will return a io::Result.

Examples

use may::coroutine;

let builder = coroutine::Builder::new();
let code = || {
    // coroutine code
};

let handler = unsafe { builder.spawn(code).unwrap() };

handler.join().unwrap();

Implementations

impl Builder

pub fn new() -> Builder

Generates the base configuration for spawning a coroutine, from which configuration methods can be chained.

pub fn name(self, name: String) -> Builder

Names the thread-to-be. Currently the name is used for identification only in panic messages.

pub fn stack_size(self, size: usize) -> Builder

Sets the size of the stack for the new coroutine.

pub fn id(self, id: usize) -> Builder

Sets the id of the coroutine, would select a specific thread to run

pub unsafe fn spawn<F, T>(self, f: F) -> Result<JoinHandle<T>>

where F: FnOnce() -> T + Send + 'static, T: Send + 'static,

Spawns a new coroutine by taking ownership of the Builder, and returns an io::Result to its JoinHandle.

The spawned coroutine may outlive the caller. The join handle can be used to block on termination of the child thread, including recovering its panics.

Errors

Unlike the spawn free function, this method yields an io::Result to capture any failure to create the thread at the OS level.

Safety

• Access TLS in coroutine may trigger undefined behavior.
• If the coroutine exceed the stack during execution, this would trigger memory segment fault

If you find it annoying to wrap every thing in the unsafe block, you can use the go! macro instead.

Examples

use may::coroutine;

let builder = coroutine::Builder::new();

let handler = unsafe {
    builder.spawn(|| {
        // thread code
    }).unwrap()
};

handler.join().unwrap();

pub unsafe fn spawn_local<F, T>(self, f: F) -> Result<JoinHandle<T>>

where F: FnOnce() -> T + Send + 'static, T: Send + 'static,

first run the coroutine in current thread, you should always use spawn instead of this API.

Safety

Cancel would drop all the resource of the coroutine. Normally this is safe but for some cases you should take care of the side effect

Trait Implementations

impl Default for Builder

fn default() -> Builder

Returns the “default value” for a type.