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:
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 |
FiberFuture | A future that resolves on completion of the fiber from another thread. |
FiberGen | Fiber for |
FiberOnce | Fiber for |
FiberStreamPulse | A stream of pulses from the fiber in another thread. |
FiberStreamRing | A stream of |
TryFiberStreamPulse | A fallible stream of pulses from the fiber in another thread. |
TryFiberStreamRing | A stream of |
Enums
FiberState | The result of a fiber resumption. |
Traits
Fiber | The main task unit of Drone. |
RootFiber | The root fiber trait. |
ThrFiberClosure | Extends |
ThrFiberFuture | Extends |
ThrFiberGen | Extends |
ThrFiberStreamPulse | Extends |
ThrFiberStreamRing | Extends |
Functions
new | Creates a fiber from the generator |
new_fn | Creates a fiber that runs the closure |
new_once | Creates a fiber that calls the closure |