Macro new_static

macro_rules! new_static {
    () => { ... };
}

Safely constructs a new StaticScheduler instance in a static initializer.

This macro is intended to be used as a static initializer:

use maitake::scheduler;

// look ma, no `unsafe`!
static SCHEDULER: scheduler::StaticScheduler = scheduler::new_static!();

Note that this macro is re-exported in the scheduler module as scheduler::new_static!, which feels somewhat more idiomatic than using it at the crate-level; however, it is also available at the crate-level as new_static_scheduler!.

The StaticScheduler::new_with_static_stub constructor is unsafe to call, because it requires that the TaskStub passed to the scheduler not be used by other scheduler instances. This macro is a safe alternative to manually initializing a StaticScheduler instance using new_with_static_stub, as it creates the stub task inside a scope, ensuring that it cannot be referenceed by other StaticScheduler instances.

This macro expands to the following code:

{
    static STUB_TASK: maitake::scheduler::TaskStub = maitake::scheduler::TaskStub::new();
    unsafe {
        // safety: `StaticScheduler::new_with_static_stub` is unsafe because
        // the stub task must not be shared with any other `StaticScheduler`
        // instance. because the `new_static` macro creates the stub task
        // inside the scope of the static initializer, it is guaranteed that
        // no other `StaticScheduler` instance can reference the `STUB_TASK`
        // static, so this is always safe.
        maitake::scheduler::StaticScheduler::new_with_static_stub(&STUB_TASK)
    }
}