Module drone_core::fib[][src]

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:

MethodInput / 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.