Struct Context

Source

pub struct Context<'env> { /* private fields */ }

Expand description

The context in which threads run, including their scope and thread group status.

Implementations§

Source §

impl<'env> Context<'env>

Source

pub fn done(&self) -> bool

Check if the current context has finished. Threads performing work should regularly check and return early if cancellation has been signalled. Usually this indicates some critical failure in a sibling thread, thus making the result of the current thread inconsequential.

§Examples

use ctx_thread::scope;

scope(|ctx| {
    ctx.spawn(|ctx| {
        assert_eq!(ctx.active(), !ctx.done());
        ctx.spawn(|ctx| {
           ctx.cancel()
        });

        while ctx.active() {}
    });
}).unwrap();

Source

pub fn cancel(&self)

Signals cancellation of the current context, causing [done] to return true. A cancelled context cannot be re-enabled. [done]: Context::done

Source

pub fn active(&self) -> bool

Alias for !ctx.done(); which is easier on the eyes in for loops.

Source

pub fn spawn<'scope, F, T>(&'scope self, f: F) -> ContextJoinHandle<'scope, T>
where F: FnOnce(&Context<'env>) -> T + Send + 'env, T: Send + 'env,

Spawns a scoped thread, providing a derived context.

This method is similar to the spawn function in Rust’s standard library. The difference is that this thread is scoped, meaning it’s guaranteed to terminate before the scope exits, allowing it to reference variables outside the scope.

The scoped thread is passed a reference to this scope as an argument, which can be used for spawning nested threads.

The returned handle can be used to manually join the thread before the scope exits.

This will create a thread using default parameters of [ScopedThreadBuilder], if you want to specify the stack size or the name of the thread, use this API instead.

§Panics

Panics if the OS fails to create a thread; use [ScopedThreadBuilder::spawn] to recover from such errors.

§Examples

use ctx_thread::scope;

scope(|ctx| {
    let handle = ctx.spawn(|_| {
        println!("A child thread is running");
        42
    });

    // Join the thread and retrieve its result.
    let res = handle.join().unwrap();
    assert_eq!(res, 42);
}).unwrap();

Source

pub fn builder<'scope>(&'scope self) -> ContextThreadBuilder<'scope, 'env>

Creates a builder that can configure a thread before spawning.

§Examples

use ctx_thread::scope;

scope(|ctx| {
    ctx.builder()
        .name(String::from("child"))
        .stack_size(1024)
        .spawn(|_| println!("A child thread is running"))
        .unwrap();
}).unwrap();