Dex – 1: Schedulers & Fibers
Description: Reference for Dex-1: Schedulers & Fibers

#### Schedulers & Fibers

# Schedulers

The `DexScheduler` is responsible for running work items on a thread. This is performed by integrating with the threads `GMainContext`.

The main thread of your application will have a `DexMainScheduler` as the assigned scheduler.

The scheduler manages callbacks such as work items created with `dex_scheduler_push()`.

You can get the default scheduler for the application’s main thread using `dex_scheduler_get_default()`.

The thread’s scheduler can be retrieved with `dex_scheduler_ref_thread_default()`.

# Thread Pool Scheduling

Libdex manages a thread pool which may be retrieved using `dex_thread_pool_scheduler_get_default()`.

The thread pool scheduler will manage a number of threads that is deemed useful based on the number of CPU available.

Work items created from outside of the thread pool are placed into a global queue. Thread pool workers will take items from the global queue when they have no more items to process.

All thread pool workers have a local `DexScheduler` so use of timeouts and other `GSource` features continue to work.

If you need to interact with long-blocking API calls it is better to use `dex_thread_spawn()` rather than a thread pool thread.

Thread pool workers use a work-stealing wait-free queue which allows the worker to push work items onto one side of the queue quickly. Doing so also helps improve cacheline effectiveness.

# Fibers

Fibers are a type of stackful co-routine. A new stack is created and a trampoline is performed onto the stack from the current thread.

Use `dex_scheduler_spawn()` to create a new fiber.

When a fiber calls a `dex_await()`, similar function, or returns the fiber is suspended and execution returns to the scheduler.

By default, fibers have a 128-kb stack with a guard page at the end. Fiber stacks are pooled so that they may be reused during heavy use.

Fibers are a `DexFuture` which means you can await the completion of a fiber just like any other future.

Note that fibers are pinned to a scheduler. They will not be migrated between schedulers even when a thread pool is in use.

# Stackless Coroutines

Coroutines are a stackless alternative that are still futures managed by the same `DexScheduler`. Use `dex_scheduler_spawn_coroutine()` to create them.

A coroutine function is given a `DexCoroutineContext` and is expected to return a `DexFuture` or suspend by returning `NULL`.

Stackless coroutines generally have lower memory overhead than fibers when you are mainly waiting on futures between steps.

Use `DEX_COROUTINE_BEGIN` and `DEX_COROUTINE_END` when writing coroutines. Suspend with one of the `DEX_COROUTINE_SUSPEND_*` helpers. See Coroutines for more guidance.

## Cancellation

Fibers may be cancelled if the fiber has been discarded by all futures awaiting completion. Fibers will always exit through a natural exit point such as a pending “await”. All attempts to await will reject with error once a fiber has been cancelled.

If you want to ignore cancellation of fibers, use `dex_future_disown()` on the fiber after creation.