Module drone_core::fib

The Fibers module.

NOTE A Drone platform crate may re-export this module with its own additions under the same name, in which case it should be used instead.

A fiber is a task unit of Drone. It is a stack-less co-routine programmed with async/await, generator, or closure Rust syntaxes. Any number of fibers can be added to a particular thread. A thread executes its fibers in LIFO order. When a fiber yields, the thread keeps it for the next time it resumes and proceeds to the next fiber. When a fiber returns, the thread drops it and proceeds to the next fiber. When there are no fibers left, the thread suspends.

Basic Fibers

A basic fiber can be created with fib::new, fib::new_fn, or fib::new_once:

use drone_core::fib;

// A fiber based on a generator.
// This is `impl Fiber<Input = (), Yield = i32, Return = i32>`
let a = fib::new(|| {
    // do some work and yield
    yield 1;
    // do some work and yield
    yield 2;
    // do some work and return
    3
});

// A fiber based on an `FnMut` closure.
// This is `impl Fiber<Input = (), Yield = i32, Return = i32>`
let b = fib::new_fn(|| {
    // check some condition
    if true {
        // do some work and yield
        fib::Yielded(1)
    } else {
        // do some work and return
        fib::Complete(2)
    }
});

// A fiber based on an `FnOnce` closure.
// This is `impl Fiber<Input = (), Yield = !, Return = i32>`
let c = fib::new_once(|| {
    // do some work and immediately return
    4
});

A basic fiber can be attached to a thread with token.add(...), token.add_fn(...), or token.add_once(...). Note that fibers that are directly attached to threads can’t have yield and return values other than () or !.

use drone_core::{fib, thr::prelude::*};

// A fiber based on a generator.
// This is `impl Fiber<Input = (), Yield = (), Return = ()>`
thr.sys_tick.add(|| {
    // do some work and yield
    yield;
    // do some work and yield
    yield;
    // do some work and return
});

// A fiber based on an `FnMut` closure.
// This is `impl Fiber<Input = (), Yield = (), Return = !>`
thr.sys_tick.add_fn(|| {
    // do some work and yield
    fib::Yielded::<(), !>(())
});

// A fiber based on an `FnOnce` closure.
// This is `impl Fiber<Input = (), Yield = !, Return = ()>`
thr.sys_tick.add_once(|| {
    // do some work and immediately return
});

Compound Fibers

There is a number of useful compound fibers implemented in this module:

Method	Input / Output
token.add_future(...)	Fiber<Input = (), Yield = ()/!, Return = T>
->	Future<Output = T>
token.add_saturating_pulse_stream(...)	Fiber<Input = (), Yield = Option<usize>, Return = Option<usize>>
->	Stream<Item = NonZeroUsize>
token.add_pulse_try_stream(...)	Fiber<Input = (), Yield = Option<usize>, Return = Result<Option<usize>, E>>
->	Stream<Item = Result<NonZeroUsize, E>>
token.add_saturating_stream(...)	Fiber<Input = (), Yield = Option<T>, Return = Option<T>>
->	Stream<Item = T>
token.add_try_stream(...)	Fiber<Input = (), Yield = Option<T>, Return = Result<Option<T>, E>>
->	Stream<Item = Result<T, E>>
token.add_overwriting_stream(...)	Fiber<Input = (), Yield = Option<T>, Return = Option<T>>
->	Stream<Item = T>
token.add_overwriting_try_stream(...)	Fiber<Input = (), Yield = Option<T>, Return = Result<Option<T>, E>>
->	Stream<Item = Result<T, E>>

In addition, each of the above methods has *_factory modification, which is useful for creating non-Send fibers.

Examples

use drone_core::{fib, thr::prelude::*};

let a = thr.sys_tick.add_future(fib::new(|| {
    yield;
    yield;
    123
}));

// `b` will have the value of 123 after the SYS_TICK thread has triggered 3
// times.
let b = a.await;

Re-exports

pub use FiberState::*;

Structs

Chain	A lock-free list of fibers.
FiberFn	Fiber for FnMut closure.
FiberFuture	A future that resolves on completion of the fiber from another thread.
FiberGen	Fiber for Generator.
FiberOnce	Fiber for FnOnce closure.
FiberStreamPulse	A stream of pulses from the fiber in another thread.
FiberStreamRing	A stream of T from the fiber in another thread.
TryFiberStreamPulse	A fallible stream of pulses from the fiber in another thread.
TryFiberStreamRing	A stream of Result<T, E> from the fiber in another thread.

Enums

FiberState

The result of a fiber resumption.

Traits

Fiber	The main task unit of Drone.
RootFiber	The root fiber trait.
ThrFiberClosure	Extends ThrToken types with add_fn, add_fn_factory, and add_once methods.
ThrFiberFuture	Extends ThrToken types with add_future and add_future_factory methods.
ThrFiberGen	Extends ThrToken types with add and add_factory methods.
ThrFiberStreamPulse	Extends ThrToken types with pulse stream methods.
ThrFiberStreamRing	Extends ThrToken types with ring stream methods.

Functions

new	Creates a fiber from the generator gen.
new_fn	Creates a fiber that runs the closure f until FiberState::Complete is returned.
new_once	Creates a fiber that calls the closure f once.