Struct tarantool_module::fiber::Fiber

pub struct Fiber<'a, T: 'a> { /* fields omitted */ }

A fiber is a set of instructions which are executed with cooperative multitasking.

Fibers managed by the fiber module are associated with a user-supplied function called the fiber function.

A fiber has three possible states: running, suspended or dead. When a fiber is started with fiber.start(), it is running. When a fiber is created with Fiber::new() (and has not been started yet) or yields control with sleep(), it is suspended. When a fiber ends (because the fiber function ends), it is dead.

A runaway fiber can be stopped with fiber.cancel(). However, fiber.cancel() is advisory — it works only if the runaway fiber calls is_cancelled() occasionally. In practice, a runaway fiber can only become unresponsive if it does many computations and does not check whether it has been cancelled.

The other potential problem comes from fibers which never get scheduled, because they are not subscribed to any events, or because no relevant events occur. Such morphing fibers can be killed with fiber.cancel() at any time, since fiber.cancel() sends an asynchronous wakeup event to the fiber, and is_cancelled() is checked whenever such a wakeup event occurs.

Example:

use tarantool_module::fiber::Fiber;
let mut fiber = Fiber::new("test_fiber", &mut |_| {
    println!("I'm a fiber");
    0
});
fiber.start(());
println!("Fiber started")

I'm a fiber
Fiber started

Implementations

impl<'a, T> Fiber<'a, T>

pub fn new<F>(name: &str, callback: &mut F) -> Self where
    F: FnMut(Box<T>) -> i32, 

Create a new fiber.

Takes a fiber from fiber cache, if it's not empty. Can fail only if there is not enough memory for the fiber structure or fiber stack.

The created fiber automatically returns itself to the fiber cache when its main function completes. The initial fiber state is suspended.

Ordinarily Fiber::new() is used in conjunction with fiber.set_joinable() and fiber.join()

• name - string with fiber name
• callback - function for run inside fiber

See also: fiber.start()

pub fn new_with_attr<F>(name: &str, attr: &FiberAttr, callback: &mut F) -> Self where
    F: FnMut(Box<T>) -> i32, 

Create a new fiber with defined attributes.

Can fail only if there is not enough memory for the fiber structure or fiber stack.

The created fiber automatically returns itself to the fiber cache if has default stack size when its main function completes. The initial fiber state is suspended.

• name - string with fiber name
• fiber_attr - fiber attributes
• callback - function for run inside fiber

See also: fiber.start()

pub fn start(&mut self, arg: T)

Start execution of created fiber.

• arg - argument to start the fiber with

See also: fiber.new()

pub fn wakeup(&self)

Interrupt a synchronous wait of a fiber.

pub fn join(&self) -> i32

Wait until the fiber is dead and then move its execution status to the caller.

“Join” a joinable fiber. That is, let the fiber’s function run and wait until the fiber’s status is dead (normally a status becomes dead when the function execution finishes). Joining will cause a yield, therefore, if the fiber is currently in a suspended state, execution of its fiber function will resume.

This kind of waiting is more convenient than going into a loop and periodically checking the status; however, it works only if the fiber was created with fiber.new() and was made joinable with fiber.set_joinable().

The fiber must not be detached (See also: fiber.set_joinable()).

Return: fiber function return code

pub fn set_joinable(&mut self, is_joinable: bool)

Set fiber to be joinable (false by default).

• is_joinable - status to set

pub fn cancel(&mut self)

Cancel a fiber. (set FIBER_IS_CANCELLED flag)

Running and suspended fibers can be cancelled. After a fiber has been cancelled, attempts to operate on it will cause error: the fiber is dead. But a dead fiber can still report its id and status. Possible errors: cancel is not permitted for the specified fiber object.

If target fiber's flag FIBER_IS_CANCELLABLE set, then it would be woken up (maybe prematurely). Then current fiber yields until the target fiber is dead (or is woken up by fiber.wakeup()).