fiber.h File Reference

AI Generated (🤦) Fiber subsystem overview. More...

#include <stddef.h>
#include <stdint.h>
#include "serene/rt/trace.h"

Include dependency graph for fiber.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	srn_fiber_ctx_t
	The saved context of a suspended fiber is a single word, its stack pointer at the moment it was switched away from. More...
struct	srn_fiber_stack_t
	One stack per fiber, mapped with a guard page at the low end so an overflow faults deterministically instead of corrupting a neighbour. More...
struct	srn_fiber_t

Macros
#define	SRN_ASAN   0
#define	SRN_TSAN   0
#define	FIBER_TRACEPOINT(...)
#define	srn_fiber_get_scheduler_m(fiber)
#define	SRN_FIBER_DEFAULT_STACK_SIZE   (128U * 1024U)
	Default size of every fiber stack.
#define	SRN_FIBER_NAME_MAX   32U
	Size of the embedded debug name buffer on every fiber, terminator included.
#define	SRN_FIBER_SPAWN_COPY(ctx, entry, value)
	srn_fiber_spawn_copy for an lvalue, the address and size are taken for the caller.

Typedefs
typedef struct srn_fiber_t	srn_fiber_t
typedef size_t	srn_worker_id_t
typedef void *	srn_fiber_result_t
	What a fiber's entry produces, type-erased.
typedef struct srn_fiber_ctx_t	srn_fiber_ctx_t
	The saved context of a suspended fiber is a single word, its stack pointer at the moment it was switched away from.
typedef struct srn_fiber_stack_t	srn_fiber_stack_t
	One stack per fiber, mapped with a guard page at the low end so an overflow faults deterministically instead of corrupting a neighbour.
typedef enum srn_fiber_state_e	srn_fiber_state_t
typedef srn_fiber_result_t(*	srn_fiber_entry_t) (srn_context_t *ctx, void *arg)
	The function a fiber runs.
typedef bool(*	srn_fiber_park_fn) (srn_fiber_t *self, void *arg)
	Suspend commit callback.

Enumerations
enum	srn_fiber_state_e : uint8_t {   SRN_FIBER_NEW = 0 , SRN_FIBER_READY , SRN_FIBER_RUNNING , SRN_FIBER_SUSPENDED ,   SRN_FIBER_DONE }

Functions
srn_scheduler_t *	srn_sched_init (srn_engine_t *engine)
void	srn_sched_shutdown (srn_scheduler_t *sched)
	The one stop tear down of the fiber subsystem, should be called once srn_sched_run has returned.
void	srn_sched_run (srn_scheduler_t *sched, size_t nworkers)
	Run the scheduler with nworkers os threads draining it, returning once the pool goes quiescent (every os thread parked on an empty queue) or a stop is requested with srn_sched_stop.
void	srn_sched_stop (srn_scheduler_t *sched)
	Ask a running scheduler to stop.
void	srn_sched_drain (srn_scheduler_t *sched)
	Ask a running scheduler to wind down gracefully.
void	srn_sched_register (srn_scheduler_t *sched, srn_fiber_t *fiber)
	Record a fiber in the scheduler's registry of live fibers, where it stays until it is reaped.
void	srn_sched_enqueue (srn_scheduler_t *sched, srn_fiber_t *fiber)
	Place a fiber on a scheduler's ready queue, making it eligible to run.
srn_fiber_t *	srn_fiber_make (srn_context_t *ctx, srn_scheduler_t *sched, const char *name, srn_fiber_entry_t entry, void *arg, size_t stack_size)
	Create a fiber that will run entry(ctx, arg), registered with sched but NOT scheduled.
void	srn_fiber_autoname (srn_engine_t *engine, char *dst, size_t size)
	Write the autogenerated debug name for a new fiber into dst.
void	srn_fiber_schedule (srn_fiber_t *fiber)
	Schedule a NEW fiber, making it eligible to run.
srn_fiber_t *	srn_fiber_spawn (srn_context_t *ctx, srn_fiber_entry_t entry, void *arg)
	Make and schedule a fiber with every default, the engine's scheduler, the configured stack size, and an autogenerated name.
srn_fiber_t *	srn_fiber_spawn_copy (srn_context_t *ctx, srn_fiber_entry_t entry, const void *arg, size_t size)
	srn_fiber_spawn with size bytes of *arg copied into ctx first, so the fiber owns its argument and the caller's stack frame can die freely.
void	srn_fiber_yield (void)
	Yield cooperatively, re-enqueue the running fiber and run the next ready one.
void	srn_fiber_suspend (srn_fiber_park_fn commit, void *arg)
	Park the running fiber until a party calls srn_fiber_ready.
void	srn_fiber_ready (srn_fiber_t *fiber)
	Mark a suspended fiber runnable again, waking it when the event it awaited occurs.
srn_fiber_result_t	srn_fiber_wait_for (srn_fiber_t *target)
	Block the calling fiber until target finishes, then return its result.
srn_fiber_t *	srn_fiber_current (void)
	The fiber currently running on this os thread, or null when the calling thread is not a worker or the worker is running its own loop rather than a fiber.
srn_fiber_t *	srn_fiber_worker_loop (void)
	The worker's loop of the worker running on the calling os thread.
void	srn_fiber_swap (srn_fiber_ctx_t *from, srn_fiber_ctx_t *to)
	Save the current execution context into from, restore to, and resume on to's stack.
void	srn_fiber_ctx_make (srn_fiber_ctx_t *fiber_ctx, srn_fiber_stack_t stack, void(*fn)(void *), void *arg)
	Initialise a fresh fiber context so the first srn_fiber_swap into it begins executing fn(arg) on stack.
void	srn_fiber_switch (srn_fiber_t *from, srn_fiber_t *to)
	Switch from from to to, both live fibers, telling AddressSanitizer about the stack change.
void	srn_fiber_switch_final (srn_fiber_t *to)
	Like srn_fiber_switch, but for a fiber that has finished and must not be resumed, control transfers to to and never comes back.
void	srn_fiber_on_entry (srn_fiber_t *from)
	Call as the first action inside a fresh fiber's entry.
void	srn_fiber_on_reap (srn_fiber_t *fiber)
	Call when a finished fiber is reaped, after it has switched away for the last time.
void	srn_fiber_init_thread (srn_fiber_t *f)
	Represent the calling OS thread as the running fiber ("#0"), so the scheduler or a test can switch away from it and back.
srn_fiber_stack_t	srn_fiber_stack_alloc (size_t size)
	Allocate a stack of at least size usable bytes plus a guard page, or SRN_FIBER_DEFAULT_STACK_SIZE when size is 0.
void	srn_fiber_stack_free (srn_fiber_stack_t stack)
static size_t	srn_fiber_stack_size (srn_fiber_stack_t s)
srn_worker_id_t	srn_sched_current_worker_id (void)
	Return the id of the worker that the calling os thread is running, or SIZE_MAX when the calling thread is not a worker.
bool	srn_sched_accepting_submissions (srn_scheduler_t *sched)
	Whether the scheduler still accepts new IO submissions.
void	srn_sched_wake_worker (srn_scheduler_t *sched, size_t channel)
	Rouse parked workers so the owner of channel consumes its completions.

Detailed Description

AI Generated (🤦) Fiber subsystem overview.

Stackful, cooperative fibers for the runtime. A fiber is a function plus its own stack, so it can pause at any call depth and resume later. Nothing is preempted. A fiber runs until it explicitly yields, suspends, or finishes.

Terminology (used throughout the fiber subsystem) fiber a unit of work with its own stack. It can pause and resume. os thread a thread the operating system schedules. worker the state one os thread uses to run fibers. It holds a local queue of ready fibers and a worker's loop. There is one worker per os thread. worker's loop a special fiber that stands in for the os thread. A running fiber switches back to it to hand control over, and it picks the next fiber to run. worker routine the steps an os thread repeats. It takes a fiber, switches into it, deals with how the fiber gave up control, and parks when no fiber is runnable. scheduler there is exactly one. It owns the shared ready queue and the list of live fibers and decides what runs next. It does not run fibers itself, workers do. suspend a fiber steps off every queue and waits to be woken. Its os thread stays free to run other fibers. park an os thread blocks because no fiber is runnable anywhere. A notify wakes it.

Every fiber stack is the same fixed size (SRN_FIBER_DEFAULT_STACK_SIZE), one mapping with a guard page that never grows. Uniform size is a deliberate constraint, not an accident. It lets a finished fiber's stack be handed to any later fiber (the stack ring TODO below) without tracking size classes, and it keeps switch and mapping costs predictable.

Control flow is a hub. A fiber never jumps to another fiber. It switches back to its worker's loop, which picks the next one.

scheduler ready queue:  [F2] -> [F5] -> ...
                           |  the os thread takes the head
                           v
   +----------->  worker's loop  --- switch --->  running fiber
   |                                                  |
   |  yield    (re-enqueue, run next) ----------------+
   |  suspend  (off-queue until srn_fiber_ready) -----+
   |  finish   (reap) --------------------------------+
   +--------------------------------------------------+

A running fiber gives up control three ways:

• yield still runnable, so it moves to the back of the ready queue.
• suspend off every queue until some party calls srn_fiber_ready. Fibers, workers, and the reactor may wake it; the reactor is the only waker outside the worker pool (see srn_fiber_ready).
• finish its entry returns and the fiber is reaped.

Signal handling is not part of this subsystem. No scheduler entry point is async signal safe, and by design: a runtime that owns an event loop folds signals into it rather than promising handler safety call by call. srn_sched_stop and srn_sched_drain take the scheduler mutex and signal its condition variable, so calling them from a signal handler can self-deadlock. A signal-initiated shutdown routes the signal into ordinary thread context first (a dedicated thread in sigwait, or a signalfd registered with the reactor) and calls stop or drain from there.

The spec book's fibers chapter (docs/spec/fibers.typ) is the long-form reference. Keep this overview in step with it.

Definition in file fiber.h.

Macro Definition Documentation

FIBER_TRACEPOINT

#define FIBER_TRACEPOINT

(

...

)

Value:

SRN_TRACEPOINT_WITH_GROUP(fiber __VA_OPT__(, ) __VA_ARGS__)

Definition at line 146 of file fiber.h.

SRN_ASAN

#define SRN_ASAN   0

Definition at line 132 of file fiber.h.

SRN_FIBER_DEFAULT_STACK_SIZE

#define SRN_FIBER_DEFAULT_STACK_SIZE   (128U * 1024U)

Default size of every fiber stack.

All fiber stacks share one size (see the subsystem overview), so this is a process-wide value, not a per-fiber one: the default here, eventually overridable through a CLI argument.

A fiber stack is fixed and cannot grow (see the fibers chapter), so the size must hold realistic call chains yet stay cheap to reserve in bulk. 128 KiB strikes that balance, deep enough for the runtime's C and JIT frames, while lazy page commit means a shallow fiber faults in only the one or two pages it touches and leaves the rest a virtual reservation. For scale, an OS thread stack is far too large to spawn fibers by the thousand, and a few KiB would overflow on modest nesting.

Definition at line 184 of file fiber.h.

srn_fiber_get_scheduler_m

#define srn_fiber_get_scheduler_m

(

fiber

)

Value:

fiber->ctx->engine->scheduler

Definition at line 163 of file fiber.h.

SRN_FIBER_NAME_MAX

#define SRN_FIBER_NAME_MAX   32U

Size of the embedded debug name buffer on every fiber, terminator included.

Large enough for the autogenerated fiber_<id> spelling of any 64 bit id.

Definition at line 191 of file fiber.h.

SRN_FIBER_SPAWN_COPY

#define SRN_FIBER_SPAWN_COPY	(		ctx,
			entry,
			value )

Value:

srn_fiber_spawn_copy(ctx, entry, &(value), sizeof(value))

srn_fiber_spawn_copy for an lvalue, the address and size are taken for the caller.

Definition at line 474 of file fiber.h.

#define SRN_FIBER_SPAWN_COPY(ctx, entry, value) \
  srn_fiber_spawn_copy(ctx, entry, &(value), sizeof(value))

SRN_TSAN

#define SRN_TSAN   0

Definition at line 143 of file fiber.h.

Typedef Documentation

srn_fiber_ctx_t

typedef struct srn_fiber_ctx_t srn_fiber_ctx_t

The saved context of a suspended fiber is a single word, its stack pointer at the moment it was switched away from.

The callee-saved registers live on the fiber's own stack, pushed by srn_fiber_swap and popped when it is resumed.

srn_fiber_entry_t

typedef srn_fiber_result_t(* srn_fiber_entry_t) (srn_context_t *ctx, void *arg)

The function a fiber runs.

Allocations made through ctx land in the context's block. TODO(lxsameer): The shape is generic until code generation produces fibers, at which point it adopts the Serene ABI. TODO(lxsameer): Should we support two types of entry functions? one for C calling convention and one for FastC?

Definition at line 255 of file fiber.h.

srn_fiber_park_fn

typedef bool(* srn_fiber_park_fn) (srn_fiber_t *self, void *arg)

Suspend commit callback.

The worker routine runs it on its own side once the fiber has switched out. It re-checks the awaited condition and only then registers self with whatever will wake it, returning true to stay suspended, or false to resume self at once because the condition already holds. The order matters, registering before the re-check can leave a live registration behind a false return, and that stale waker would wake the fiber's NEXT suspend. It must not switch fibers.

Definition at line 266 of file fiber.h.

srn_fiber_result_t

typedef void* srn_fiber_result_t

What a fiber's entry produces, type-erased.

It is an alias for void *, so the fiber subsystem carries no dependency on the value model. A caller that runs fibers over Serene values casts to and from its own type at the boundary.

Definition at line 161 of file fiber.h.

srn_fiber_stack_t

typedef struct srn_fiber_stack_t srn_fiber_stack_t

One stack per fiber, mapped with a guard page at the low end so an overflow faults deterministically instead of corrupting a neighbour.

With addresses increasing to the right, the layout is:

|... guard page ...|.......... frames ..........| ^ guard ^ limit ^ start

guard is the mmap base, the lowest page of the region. The stack grows downward, so frames start at the high end (start) and grow toward limit; one step past limit lands on the protected guard page and faults.

srn_fiber_state_t

typedef enum srn_fiber_state_e srn_fiber_state_t

srn_fiber_t

typedef struct srn_fiber_t srn_fiber_t

Definition at line 150 of file fiber.h.

srn_worker_id_t

typedef size_t srn_worker_id_t

Definition at line 153 of file fiber.h.

Enumeration Type Documentation

srn_fiber_state_e

enum srn_fiber_state_e : uint8_t

Enumerator
SRN_FIBER_NEW	Created, stack mapped, never resumed.
SRN_FIBER_READY	On the run queue, eligible to run.
SRN_FIBER_RUNNING	Currently executing.
SRN_FIBER_SUSPENDED	Parked off the run queue, awaits srn_fiber_ready.
SRN_FIBER_DONE	Entry returned. The result is final.

Definition at line 234 of file fiber.h.

                               : uint8_t {
  /// Created, stack mapped, never resumed
  SRN_FIBER_NEW = 0,
  /// On the run queue, eligible to run
  SRN_FIBER_READY,
  /// Currently executing
  SRN_FIBER_RUNNING,
  /// Parked off the run queue, awaits srn_fiber_ready
  SRN_FIBER_SUSPENDED,
  /// Entry returned. The result is final
  SRN_FIBER_DONE,
} srn_fiber_state_t;

Function Documentation

srn_fiber_autoname()

void srn_fiber_autoname	(	srn_engine_t *	engine,
		char *	dst,
		size_t	size )

Write the autogenerated debug name for a new fiber into dst.

Created on a worker the tag is f#<worker>:<n>, the creating worker's id and its spawn count. Created off the pool it is f#m:<id> from the engine wide object id counter. The worker part is provenance, not placement, a stolen fiber runs anywhere. srn_fiber_make uses this when given no name.

Definition at line 1141 of file scheduler.c.

                                                                      {
  PANIC_IF_NULL(engine);
  PANIC_IF_NULL(dst);
 
  srn_worker_t *w = current_worker;
  if (w != nullptr) {
    // The tag names the creating worker and its spawn count. Provenance, not
    // placement, the fiber may be stolen and run anywhere.
    (void)snprintf(dst, size, "f#%zu:%" PRIu64, (size_t)w->id, ++w->spawned);
    return;
  }
  // Off the pool there is no worker id. The tag is `m` and the engine wide
  // object id keeps names unique across every creating thread.
  (void)snprintf(dst, size, "f#m:%" PRIu64, srn_allocate_object_id(engine));
}

Here is the call graph for this function:

Here is the caller graph for this function:

srn_fiber_ctx_make()

void srn_fiber_ctx_make	(	srn_fiber_ctx_t *	fiber_ctx,
		srn_fiber_stack_t	stack,
		void(*	fn )(void *),
		void *	arg )

Initialise a fresh fiber context so the first srn_fiber_swap into it begins executing fn(arg) on stack.

fn is the fiber's entry, a void (*)(void *) that runs on the new stack and receives arg. It must NEVER return – there is no frame beneath it, so a return traps in the trampoline. Instead it transfers control away with srn_fiber_switch (to yield) or srn_fiber_switch_final (when finished), and as its first action it calls srn_fiber_on_entry(). Typical shape:

static void worker(void *arg) { srn_fiber_on_entry(&scheduler); // hand the switch to the sanitizer ... do the fiber's work using arg ... srn_fiber_switch_final(&scheduler); // finished, never returns }

Here is the caller graph for this function:

srn_fiber_current()

srn_fiber_t * srn_fiber_current

(

void

)

The fiber currently running on this os thread, or null when the calling thread is not a worker or the worker is running its own loop rather than a fiber.

Definition at line 1097 of file scheduler.c.

                                     {
  return current_worker != nullptr ? current_worker->current : nullptr;
}

Here is the caller graph for this function:

srn_fiber_init_thread()

void srn_fiber_init_thread

(

srn_fiber_t *

f

)

Represent the calling OS thread as the running fiber ("#0"), so the scheduler or a test can switch away from it and back.

The thread's stack bounds are not queried here (there is no portable way). Under the sanitizer they are recorded by the first fiber's srn_fiber_on_entry. The saved context is written by the first switch away.

Definition at line 153 of file fiber.c.

                                           {
  // Represent the calling thread as the running fiber. The saved context
  // (fiber_ctx) stays empty, and the first switch away from the thread fills
  // it.
  memset(f, 0, sizeof(*f));
  f->state = SRN_FIBER_RUNNING;
  (void)snprintf(f->name, sizeof(f->name), "thread");
#if SRN_ASAN
  // ASan needs this loop's stack bounds on every switch back to it, and a
  // worker that only ever resumes stolen fibers never launches a fresh
  // fiber, so srn_fiber_on_entry would never report them. Run a throwaway
  // fiber once, its entry records the bounds through the same protocol
  // every real fiber uses. The probe finishes before the switch back, so
  // srn_fiber_switch_final already has real bounds to announce.
  srn_fiber_t probe;
  memset(&probe, 0, sizeof(probe));
  probe.state = SRN_FIBER_READY;
  (void)snprintf(probe.name, sizeof(probe.name), "stack-bounds-probe");
  probe.stack = srn_fiber_stack_alloc(1); // rounds up to one page plus guard
  srn_fiber_ctx_make(&probe.fiber_ctx, probe.stack, stack_bounds_probe, f);
  srn_fiber_switch(f, &probe);
  srn_fiber_stack_free(probe.stack);
#endif
#if SRN_TSAN
  // The loop fiber stands in for this OS thread, so it takes the thread's own
  // current TSan fiber rather than a freshly created one.
  f->tsan_fiber = __tsan_get_current_fiber();
#endif
}

Here is the call graph for this function:

Here is the caller graph for this function:

srn_fiber_make()

srn_fiber_t * srn_fiber_make ( srn_context_t * ctx, srn_scheduler_t * sched, const char * name, srn_fiber_entry_t entry, void * arg, size_t stack_size )

nodiscard

Create a fiber that will run entry(ctx, arg), registered with sched but NOT scheduled.

The fiber stays NEW until srn_fiber_schedule starts it, so a caller can build several fibers and wire them up before any of them runs. Registration at creation means the scheduler reaps every fiber at shutdown, scheduled or not.

name is a debug label copied into the fiber, truncated to SRN_FIBER_NAME_MAX - 1 bytes, or nullptr for an autogenerated unique one. A stack_size of 0 selects the configured per fiber default.

Definition at line 200 of file fiber.c.

  {
 
  srn_fiber_t *f = ALLOC(ctx, srn_fiber_t);
  PANIC_IF_NULL(f);
  memset((void *)f, 0, sizeof(srn_fiber_t));
 
  // TODO(lxsameer): Make the fiber stack configurable via cli arg or something.
  // This is the acquire side of the stack-ring TODO in fiber.h: a pooled stack
  // would be pulled from the per-thread ring here, falling back to a fresh
  // mapping only on a miss.
  // A zero `stack_size` falls back to the configured per fiber default.
  f->stack =
    srn_fiber_stack_alloc(stack_size != 0 ? stack_size : ctx->engine->config.fiber.stack_size);
  f->ctx   = ctx;
  f->state = SRN_FIBER_NEW;
  f->entry = entry;
  f->arg   = arg;
 
  if (name != nullptr) {
    (void)snprintf(f->name, sizeof(f->name), "%s", name);
  } else {
    srn_fiber_autoname(ctx->engine, f->name, sizeof(f->name));
  }
 
  FIBER_TRACEPOINT(fiber_created, f->name, srn_fiber_stack_size(f->stack));
 
#if SRN_TSAN
  f->tsan_fiber = __tsan_create_fiber(0);
#endif
  srn_fiber_ctx_make(&f->fiber_ctx, f->stack, &srn_fiber_launcher, (void *)f);
 
  // Register before enqueuing, the scheduler must know about the fiber for its
  // whole life, independent of which queue (if any) it currently sits on. The
  // registry is how a SUSPENDED fiber, off every run queue, stays reachable for
  // cleanup and cancellation.
  srn_sched_register(sched, f);
 
  // The fiber stays NEW. srn_fiber_schedule makes it runnable, so a caller
  // can build several fibers and wire them up before any of them runs.
  return f;
}

Here is the call graph for this function:

Here is the caller graph for this function:

srn_fiber_on_entry()

void srn_fiber_on_entry

(

srn_fiber_t *

from

)

Call as the first action inside a fresh fiber's entry.

from is the fiber that started this one (the scheduler, or the bootstrap thread fiber). It completes the switch for AddressSanitizer and, since from's stack bounds only become discoverable here, records them into from so a later switch back is tracked. from may be null. A no-op when the sanitizer is not in use.

Definition at line 110 of file fiber.c.

                                           {
#if SRN_ASAN
  // A nullptr fake-stack, a fresh fiber has no previously saved bookkeeping.
  // The out-params report the stack this fiber was started from -- this is the
  // one chance to learn `from`'s bounds (there is no portable way to query a
  // thread's own stack), and a later switch back to `from` needs them, so
  // record them. They flow through the sanitizer rather than libc.
  const void *bottom = nullptr;
  size_t size        = 0;
  __sanitizer_finish_switch_fiber(nullptr, &bottom, &size);
 
  if (from != nullptr) {
    // ASan reports the came-from stack as (bottom, size). The struct keeps the
    // low and high boundaries, so limit = bottom and start = bottom + size.
    from->stack.limit = (void *)bottom;
    from->stack.start = (char *)bottom + size;
  }
#else
  UNUSED(from);
#endif
}

Here is the caller graph for this function:

srn_fiber_on_reap()

void srn_fiber_on_reap

(

srn_fiber_t *

fiber

)

Call when a finished fiber is reaped, after it has switched away for the last time.

Releases the fiber's ThreadSanitizer handle. A no-op when the sanitizer is not in use.

Definition at line 132 of file fiber.c.

                                           {
#if SRN_TSAN
  __tsan_destroy_fiber(fiber->tsan_fiber);
#else
  UNUSED(fiber);
#endif
}

Here is the caller graph for this function:

srn_fiber_ready()

void srn_fiber_ready

(

srn_fiber_t *

fiber

)

Mark a suspended fiber runnable again, waking it when the event it awaited occurs.

Callable from a fiber, a worker, or the reactor. The reactor is the only legitimate waker outside the worker pool.

Definition at line 1083 of file scheduler.c.

                                         {
  PANIC_IF_NULL(fiber);
 
  // Wake a suspended fiber. The flip in `ready_fiber` lets exactly one of
  // several racing wakers enqueue it (an IO completion and a timeout firing on
  // it, say), while the rest find it no longer `SUSPENDED` and do nothing. The
  // scheduler is resolved from the fiber, not the calling os thread, so the
  // reactor -- the one legitimate waker outside the worker pool, since
  // quiescence accounts for its in-flight ops -- can wake it too. An
  // unrelated os thread must not, its pending wake is invisible to
  // quiescence, so the run can end before the wake arrives.
  ready_fiber(srn_fiber_get_scheduler_m(fiber), fiber);
}

Here is the call graph for this function:

Here is the caller graph for this function:

srn_fiber_schedule()

void srn_fiber_schedule

(

srn_fiber_t *

fiber

)

Schedule a NEW fiber, making it eligible to run.

A fiber is scheduled exactly once, scheduling one that is not NEW panics, and waking a suspended fiber is srn_fiber_ready's job instead.

Definition at line 638 of file scheduler.c.

                                            {
  PANIC_IF_NULL(fiber);
 
  // The NEW to READY flip admits exactly one scheduler of this fiber, the
  // same guard ready_fiber uses for SUSPENDED, so a double schedule panics
  // at the losing call site instead of double enqueuing.
  srn_fiber_state_t expected = SRN_FIBER_NEW;
  PANIC_IF(
    !atomic_compare_exchange_strong(&fiber->state, &expected, SRN_FIBER_READY),
    "srn_fiber_schedule needs a NEW fiber. A fiber is scheduled exactly once, "
    "and a suspended one is woken with srn_fiber_ready"
  );
  push_ready(srn_fiber_get_scheduler_m(fiber), fiber);
}

Here is the call graph for this function:

Here is the caller graph for this function:

srn_fiber_spawn()

srn_fiber_t * srn_fiber_spawn	(	srn_context_t *	ctx,
		srn_fiber_entry_t	entry,
		void *	arg )

Make and schedule a fiber with every default, the engine's scheduler, the configured stack size, and an autogenerated name.

The caller keeps ownership of arg and must keep it alive until the fiber is done with it, srn_fiber_spawn_copy lifts that burden.

Definition at line 245 of file fiber.c.

                                                                                     {
  PANIC_IF_NULL(ctx);
  srn_fiber_t *f = srn_fiber_make(ctx, ctx->engine->scheduler, nullptr, entry, arg, 0);
  srn_fiber_schedule(f);
  return f;
}

Here is the call graph for this function:

Here is the caller graph for this function:

srn_fiber_spawn_copy()

srn_fiber_t * srn_fiber_spawn_copy	(	srn_context_t *	ctx,
		srn_fiber_entry_t	entry,
		const void *	arg,
		size_t	size )

srn_fiber_spawn with size bytes of *arg copied into ctx first, so the fiber owns its argument and the caller's stack frame can die freely.

The copy lives until the context is released, like the fiber itself.

Definition at line 253 of file fiber.c.

                                                                                                {
  PANIC_IF_NULL(ctx);
  PANIC_IF_NULL(arg);
  // max_align_t suits any argument type, the caller only hands over bytes.
  void *copy = srn_allocate(ctx, size, alignof(max_align_t));
  PANIC_IF_NULL(copy);
  memcpy(copy, arg, size);
  return srn_fiber_spawn(ctx, entry, copy);
}

Here is the call graph for this function:

srn_fiber_stack_alloc()

srn_fiber_stack_t srn_fiber_stack_alloc ( size_t size )

nodiscard

Allocate a stack of at least size usable bytes plus a guard page, or SRN_FIBER_DEFAULT_STACK_SIZE when size is 0.

Platform specific.

Here is the caller graph for this function:

srn_fiber_stack_free()

void srn_fiber_stack_free

(

srn_fiber_stack_t

stack

)

Here is the caller graph for this function:

srn_fiber_stack_size()

size_t srn_fiber_stack_size ( srn_fiber_stack_t s )

inlinestatic

Definition at line 625 of file fiber.h.

                                                               {
  return (size_t)((char *)s.start - (char *)s.limit);
}

Here is the caller graph for this function:

srn_fiber_suspend()

void srn_fiber_suspend	(	srn_fiber_park_fn	commit,
		void *	arg )

Park the running fiber until a party calls srn_fiber_ready.

The fiber switches out first. Only then does the scheduler run commit (see srn_fiber_park_fn) to register it and confirm it should stay parked. Registering only after the park completes is what makes it race free – a waker can never observe a half parked fiber. Acts on the fiber currently running on this thread.

Park the running fiber until a party calls srn_fiber_ready.

The commit callback runs on the worker's loop side once the fiber has switched out. It hands the fiber's pointer to the event source it blocks on (a peer fiber, a lock's waiter list, the IO reactor's fd table), so that party can call srn_fiber_ready when the awaited event occurs. Running commit only after the suspend completes is what makes the hand-off race free, a waker can never observe a half-suspended fiber. If commit registers the fiber nowhere, it is genuinely lost – a deadlock, like an os thread blocking on a condition nobody signals.

Definition at line 1063 of file scheduler.c.

                                                            {
  PANIC_IF_NULL(commit);
 
  srn_worker_t *worker = current_worker;
  PANIC_IF_NULL(worker);
 
  srn_fiber_t *self = worker->current;
  PANIC_IF_NULL(self);
 
  // The fiber carries its own commit. The worker routine runs it after we
  // switch out -- the one safe point to publish a fully suspended fiber to its
  // waker. The routine also stamps the `SUSPENDED` state once the switch
  // completes, so the `state` never marks a fiber that is still suspending.
  // This call leaves the `state` as `RUNNING` and lets the switch carry the
  // fiber off the os thread.
  self->park_commit = commit;
  self->park_arg    = arg;
  srn_fiber_switch(self, &worker->loop);
}

Here is the call graph for this function:

Here is the caller graph for this function:

srn_fiber_swap()

void srn_fiber_swap	(	srn_fiber_ctx_t *	from,
		srn_fiber_ctx_t *	to )

Save the current execution context into from, restore to, and resume on to's stack.

Returns, on from's stack, when a fiber later switches back into from.

Here is the caller graph for this function:

srn_fiber_switch()

void srn_fiber_switch	(	srn_fiber_t *	from,
		srn_fiber_t *	to )

Switch from from to to, both live fibers, telling AddressSanitizer about the stack change.

from resumes where it left off when something later switches back into it.

Switch from from to to, both live fibers, telling AddressSanitizer about the stack change.

Not instrumented by either sanitizer, the stack swaps mid-function, which confuses ASan's fake stack and TSan's shadow stack. The explicit annotations keep each sanitizer's fiber tracking correct across the swap instead.

Definition at line 65 of file fiber.c.

                                                          {
 
#if SRN_ASAN
  const size_t size = srn_fiber_stack_size(to->stack);
  __sanitizer_start_switch_fiber(&from->fake_stack, to->stack.limit, size);
#endif
#if SRN_TSAN
  // Move TSan's notion of the running fiber to `to` before the stack swaps. A
  // fiber built outside srn_fiber_make / srn_fiber_init_thread has no handle
  // and is simply not tracked. Only the low-level switch tests build such a
  // fiber. Every fiber the scheduler runs has one.
  if (to->tsan_fiber != nullptr) {
    __tsan_switch_to_fiber(to->tsan_fiber, 0);
  }
#endif
  srn_fiber_swap(&from->fiber_ctx, &to->fiber_ctx);
#if SRN_ASAN
  __sanitizer_finish_switch_fiber(from->fake_stack, nullptr, nullptr);
#endif
}

Here is the call graph for this function:

Here is the caller graph for this function:

srn_fiber_switch_final()

void srn_fiber_switch_final

(

srn_fiber_t *

to

)

Like srn_fiber_switch, but for a fiber that has finished and must not be resumed, control transfers to to and never comes back.

The fiber's entry function therefore ends at this call – any code after it is unreachable, which is why this is [[noreturn]]. Nothing is freed here. The spent fiber's stack is left frozen and reclaimed later by its owner (the scheduler reaps a finished fiber and frees its stack via srn_fiber_stack_free).

Definition at line 87 of file fiber.c.

                                             {
#if SRN_ASAN
  // A nullptr fake-stack tells ASan the current fiber is finished and will not
  // resume, so it can discard the bookkeeping rather than leak it.
  const size_t size = srn_fiber_stack_size(to->stack);
  __sanitizer_start_switch_fiber(nullptr, to->stack.limit, size);
#endif
#if SRN_TSAN
  // The finished fiber's handle is released later, at reap. Here just move
  // TSan to `to` before the swap, when `to` has a handle (see
  // srn_fiber_switch).
  if (to->tsan_fiber != nullptr) {
    __tsan_switch_to_fiber(to->tsan_fiber, 0);
  }
#endif
  // srn_fiber_swap always writes the outgoing sp somewhere. This fiber is done,
  // so discard it. Control loads `to` and never comes back.
  srn_fiber_ctx_t discard;
  srn_fiber_swap(&discard, &to->fiber_ctx);
  SHOULD_NOT_HAPPEN;
}

Here is the call graph for this function:

Here is the caller graph for this function:

srn_fiber_wait_for()

srn_fiber_result_t srn_fiber_wait_for

(

srn_fiber_t *

target

)

Block the calling fiber until target finishes, then return its result.

If the target is already done, returns immediately.

Definition at line 1130 of file scheduler.c.

                                                           {
  PANIC_IF_NULL(target);
  PANIC_IF(target == srn_fiber_current(), "srn_fiber_wait_for: a fiber cannot wait for itself");
 
  // Suspend until the target finishes (wait_for_park registers us on its waiter
  // list). The target's DONE handling in the worker routine wakes us. The
  // result is read from the struct, which survives the target's reap.
  srn_fiber_suspend(wait_for_park, target);
  return target->result;
}

Here is the call graph for this function:

Here is the caller graph for this function:

srn_fiber_worker_loop()

srn_fiber_t * srn_fiber_worker_loop

(

void

)

The worker's loop of the worker running on the calling os thread.

The fiber that resumes when the current fiber yields, suspends, or finishes, the resumer a fiber's launcher hands control back to. Each worker has its own, so this is valid only on an os thread that is currently running the worker routine.

Definition at line 1101 of file scheduler.c.

                                         {
  PANIC_IF_NULL(current_worker);
  return &current_worker->loop;
}

Here is the caller graph for this function:

srn_fiber_yield()

void srn_fiber_yield

(

void

)

Yield cooperatively, re-enqueue the running fiber and run the next ready one.

Acts on the fiber currently running on this thread.

Definition at line 1039 of file scheduler.c.

                           {
  srn_worker_t *worker = current_worker;
  PANIC_IF_NULL(worker);
 
  // Switch to the worker's loop without enqueuing first. The worker routine
  // puts this fiber back on the ready queue once the switch has saved its
  // context. Enqueuing here, before the switch, would let another os thread
  // dequeue and resume the fiber while this os thread is still saving its
  // context -- two os threads on one fiber stack, which corrupts the switch.
  srn_fiber_t *self = worker->current;
  PANIC_IF_NULL(self);
  srn_fiber_switch(self, &worker->loop);
}

Here is the call graph for this function:

Here is the caller graph for this function:

srn_sched_accepting_submissions()

bool srn_sched_accepting_submissions

(

srn_scheduler_t *

sched

)

Whether the scheduler still accepts new IO submissions.

True only while RUNNING; false once srn_sched_drain or srn_sched_stop has begun winding the pool down. The IO bridge reads this to fence submissions during a wind-down, so a fiber's IO call comes back cancelled instead of parking on an op the wind-down would have to wait out.

Definition at line 1163 of file scheduler.c.

                                                             {
  PANIC_IF_NULL(sched);
  // Only a RUNNING scheduler takes new IO. Once DRAINING or STOPPING, the IO
  // bridge fences submissions so fibers unwind instead of parking on ops the
  // wind-down would have to wait out.
  return atomic_load(&sched->state) == SRN_SCHED_RUNNING;
}

Here is the caller graph for this function:

srn_sched_current_worker_id()

srn_worker_id_t srn_sched_current_worker_id

(

void

)

Return the id of the worker that the calling os thread is running, or SIZE_MAX when the calling thread is not a worker.

Definition at line 1157 of file scheduler.c.

                                              {
  // We use the SIZE_MAX as an idicator that there is no current
  // worker for the running os thread. (size_t)-1 == SIZE_MAX
  return current_worker == nullptr ? (srn_worker_id_t)-1 : current_worker->id;
}

Here is the caller graph for this function:

srn_sched_drain()

void srn_sched_drain

(

srn_scheduler_t *

sched

)

Ask a running scheduler to wind down gracefully.

Unlike srn_sched_stop, the workers keep running every runnable fiber and let in-flight IO complete; only new IO submissions are fenced, so a fiber's next IO call returns -ECANCELED and the fiber unwinds rather than parking on a fresh op. The pool then reaches the same quiescence as a natural finish and srn_sched_run returns. An in-flight op that never completes (an idle recv, a long sleep) stalls the wind-down until it finishes; bounding that needs op cancellation and is not provided yet. Does not wait. Safe to call from any os thread or a fiber. A no-op if the scheduler is not running.

Definition at line 1002 of file scheduler.c.

                                             {
  PANIC_IF_NULL(sched);
  // Begin a graceful winddown, only a RUNNING scheduler can enter DRAINING.
  // Already draining or stopping, or not running at all, leaves the state as
  // is.
  srn_sched_state_t expected = SRN_SCHED_RUNNING;
 
  if (!atomic_compare_exchange_strong(&sched->state, &expected, SRN_SCHED_DRAINING)) {
    return;
  }
 
  // From here `srn_sched_accepting_submissions` returns false, so the next IO a
  // fiber attempts is fenced into a cancelled completion and the fiber unwinds
  // rather than parking on a fresh op. Workers do NOT break on DRAINING, so
  // every runnable fiber still runs and every in-flight op still completes; the
  // pool converges to the same quiescence as a natural finish, which then moves
  // the state to STOPPING. A never-completing in-flight op (an idle recv, a
  // long sleep) stalls this until it finishes -- bounding that needs op CANCEL
  // (E1) and is out of scope here.
  //
  // The notify wakes any os thread already parked so it re-checks state. A
  // worker parked on outstanding IO simply re-parks (DRAINING keeps it
  // parking), which is harmless.
  srn_mutex_lock(&sched->lock);
  srn_cond_notify_all(&sched->work);
  srn_mutex_unlock(&sched->lock);
  SCHED_LOG("drain requested");
}

Here is the call graph for this function:

Here is the caller graph for this function:

srn_sched_enqueue()

void srn_sched_enqueue	(	srn_scheduler_t *	sched,
		srn_fiber_t *	fiber )

Place a fiber on a scheduler's ready queue, making it eligible to run.

Definition at line 630 of file scheduler.c.

                                                                   {
  PANIC_IF_NULL(sched);
  PANIC_IF_NULL(fiber);
 
  fiber->state = SRN_FIBER_READY;
  push_ready(sched, fiber);
}

Here is the call graph for this function:

srn_sched_init()

srn_scheduler_t * srn_sched_init ( srn_engine_t * engine )

nodiscard

Definition at line 263 of file scheduler.c.

                                                      {
  PANIC_IF_NULL(engine);
  // The scheduler outlives every context and fiber, so it is allocated from the
  // immortal region rather than a releasable block.
  srn_scheduler_t *sched = srn_mm_immortal_allocate(engine->mm, srn_scheduler_t);
  PANIC_IF_NULL(sched);
 
  sched->engine     = engine;
  sched->ready_head = nullptr;
  sched->ready_tail = nullptr;
  sched->registry   = nullptr;
  sched->idle       = 0;
  sched->runnable   = 0;
  sched->nworkers   = 0;
  sched->state      = SRN_SCHED_IDLE;
  sched->workers    = nullptr;
  sched->os_threads = nullptr;
  sched->destroyed  = false;
  atomic_init(&sched->run_active, false);
 
  PANIC_IF(
    srn_mutex_init(&sched->lock) != SRN_THREAD_OK, "failed to initialise the scheduler lock"
  );
 
  PANIC_IF(
    srn_cond_init(&sched->work) != SRN_THREAD_OK, "failed to initialise the scheduler condition"
  );
 
  // srn_engine_make will store this scheduler in the engine
  return sched;
}

Here is the call graph for this function:

Here is the caller graph for this function:

srn_sched_register()

void srn_sched_register	(	srn_scheduler_t *	sched,
		srn_fiber_t *	fiber )

Record a fiber in the scheduler's registry of live fibers, where it stays until it is reaped.

Definition at line 324 of file scheduler.c.

                                                                    {
  PANIC_IF_NULL(sched);
  PANIC_IF_NULL(fiber);
 
  srn_mutex_lock(&sched->lock);
  registry_add(sched, fiber);
  srn_mutex_unlock(&sched->lock);
}

Here is the call graph for this function:

Here is the caller graph for this function:

srn_sched_run()

void srn_sched_run	(	srn_scheduler_t *	sched,
		size_t	nworkers )

Run the scheduler with nworkers os threads draining it, returning once the pool goes quiescent (every os thread parked on an empty queue) or a stop is requested with srn_sched_stop.

The calling os thread becomes worker 0, so it does not return until then. nworkers is clamped to at least 1; with 1 it is the calling os thread alone, which keeps execution single-threaded and cooperatively ordered. The spawned os threads are not joined here – srn_sched_shutdown joins them as part of tearing the subsystem down.

Definition at line 875 of file scheduler.c.

                                                            {
  PANIC_IF_NULL(sched);
  PANIC_IF(sched->destroyed, "srn_sched_run called on a scheduler that was already shut down");
 
  // Claiming run_active up front turns an overlapping run into a clean panic
  // instead of two runs clobbering the worker arrays under each other.
  PANIC_IF(
    atomic_exchange(&sched->run_active, true),
    "srn_sched_run called while another run is active on this scheduler"
  );
 
  // A finished run leaves its worker arrays behind for shutdown to join and
  // free. A second run would replace them while stragglers from the first may
  // still be winding down, reviving those stragglers against the new run's
  // state, and the reactor cannot be activated twice either. A scheduler
  // therefore runs once; re-run support requires reactor reactivation.
  PANIC_IF(
    sched->workers != nullptr,
    "srn_sched_run called on a scheduler that has already run; re-run is not "
    "supported (the reactor cannot be reactivated)"
  );
 
  // A caller that does not pick a count gets the configured one, and every
  // request is clamped to the configured ceiling. SRN_MAX_WORKERS stays the
  // absolute ceiling above whatever the configuration asks for.
  const srn_configuration_t *config = &sched->engine->config;
  nworkers                          = nworkers == 0 ? config->fiber.workers : nworkers;
 
  if (nworkers == 0) {
    // A configured count of zero delegates to the machine, one worker per
    // CPU the process may run on.
    nworkers = srn_thread_cpu_count();
  }
 
  if (nworkers > config->fiber.max_workers) {
    nworkers = config->fiber.max_workers;
  }
 
  if (nworkers > SRN_MAX_WORKERS) {
    nworkers = SRN_MAX_WORKERS;
  }
 
  // Allocate `workers` and `os_threads` on the scheduler so
  // `srn_sched_shutdown` can join the threads and free them later. `workers`
  // has one entry per worker. `os_threads` has one per spawned thread, with
  // slot 0 left empty because the caller runs worker 0 inline (see the struct
  // comment). `runnable` is left alone, it already counts the fibers queued
  // before the run.
  sched->workers = srn_mm_malloc(sched->engine->mm, nworkers * sizeof(srn_worker_t));
  PANIC_IF_NULL(sched->workers);
 
  sched->os_threads = srn_mm_malloc(sched->engine->mm, nworkers * sizeof(srn_thread_t));
  PANIC_IF_NULL(sched->os_threads);
 
  for (size_t i = 0; i < nworkers; i++) {
    srn_worker_t *w = &sched->workers[i];
    w->sched        = sched;
    w->id           = i;
    w->current      = nullptr;
    w->spawned      = 0;
    // The deque indices start empty. Its ring slots are written before they are
    // read, and the worker's loop is set up by worker_main on its own os
    // thread.
    atomic_init(&w->top, 0);
    atomic_init(&w->bottom, 0);
  }
 
  // Publish the coordination state before any os thread starts. `nworkers` must
  // be set first so the quiescence check counts the right total, and the state
  // must be RUNNING before an os thread can observe it. `run_active` was
  // claimed at the top of this call; shutdown reads it to see a run in flight.
  sched->idle     = 0;
  sched->nworkers = nworkers;
  atomic_store(&sched->state, SRN_SCHED_RUNNING);
 
  // Bring the reactor up with one channel per worker before any worker starts,
  // so a fiber's first IO has a channel to submit on. The notify seam wakes the
  // worker that owns the channel a completion lands on.
  srn_reactor_activate(sched->engine->reactor, nworkers, srn_sched_wake_worker);
 
  FIBER_TRACEPOINT(sched_run, nworkers);
 
  // Spawn nworkers - 1 os threads. The calling os thread runs worker 0 inline.
  // A spawn failure at startup is fatal, a partial pool would never reach `idle
  // == nworkers` and so never quiesce.
  for (size_t i = 1; i < nworkers; i++) {
    if (srn_thread_spawn(&sched->os_threads[i], worker_main, &sched->workers[i]) != SRN_THREAD_OK) {
      PANIC("failed to spawn an os thread");
    }
    FIBER_TRACEPOINT(sched_thread_spawn, i);
  }
 
  worker_main(&sched->workers[0]);
 
  // Worker 0 has stopped, so the run is over from the caller's point of view.
  // The spawned os threads may still be winding down, so they are NOT joined
  // here. `srn_sched_shutdown` joins them (the `os_threads` live on the
  // scheduler) as part of tearing the subsystem down. Clearing `run_active`
  // lets shutdown proceed. The state stays STOPPING, which keeps any os thread
  // still looping on its way out.
  atomic_store(&sched->run_active, false);
}

Here is the call graph for this function:

Here is the caller graph for this function:

srn_sched_shutdown()

void srn_sched_shutdown

(

srn_scheduler_t *

sched

)

The one stop tear down of the fiber subsystem, should be called once srn_sched_run has returned.

It joins the os threads, then releases the stack of every fiber still registered (any left unreaped, such as one suspended with no party to wake it, or one left queued when the run stopped early), and frees the scheduler's own resources. The fiber structs themselves live in context blocks and are reclaimed with those blocks, not here.

The scheduler is NOT usable after this. A later srn_sched_run panics, and a repeated srn_sched_shutdown is a no-op (so the engine can call it unconditionally even after a caller already did).

Must be called from outside the pool, never from an os thread that is running a worker nor from a fiber, and only after srn_sched_run has returned. Calling it on a live pool panics – stop the pool with srn_sched_stop, let srn_sched_run return, then shut down.

Definition at line 333 of file scheduler.c.

                                                {
  PANIC_IF_NULL(sched);
 
  if (sched->destroyed) {
    return;
  }
 
  // It must run on a thread outside the pool, a worker, or a fiber (which runs
  // on a worker), would be tearing down the scheduler it is itself running on.
  // `current_worker` is null only off a worker, so it is the test for that.
  PANIC_IF(
    current_worker != nullptr, "srn_sched_shutdown must be called from outside the worker pool"
  );
 
  // And it must run after `srn_sched_run` has returned, not while a run is in
  // flight. Stop a running pool with `srn_sched_stop` and let `srn_sched_run`
  // return first.
  PANIC_IF(
    atomic_load(&sched->run_active),
    "srn_sched_shutdown called while srn_sched_run is active; call "
    "srn_sched_stop and let the run return first"
  );
 
  // The run has returned, so worker 0 has stopped. The spawned os threads may
  // still be winding down (`srn_sched_run` does not join them), so join them
  // now. `os_threads` slot 0 is the inline worker 0, never spawned, so the
  // spawned os threads to join are 1..nworkers-1.
  for (size_t i = 1; i < sched->nworkers; i++) {
    (void)srn_thread_join(&sched->os_threads[i]);
  }
 
  // Every worker is gone, so this runs single threaded now.
  //
  // Any fiber still in the registry never finished, it was left parked in
  // SRN_FIBER_SUSPENDED with no party able to wake it (a deadlock), or was left
  // queued when the run stopped early. Release its stack so it does not leak.
  // The fiber structs themselves live in context blocks and are reclaimed with
  // those blocks, not here. The scheduler is immortal-allocated, so it is not
  // freed either.
  //
  // Unlike the reap path, this unmaps for good, shutdown runs after the workers
  // are gone, so the per-thread stack ring from the fiber.h TODO no longer
  // exists and there is nothing to recycle into. (Draining that ring, when it
  // exists, also belongs here.)
  srn_fiber_t *fiber = sched->registry;
  while (fiber != nullptr) {
    srn_fiber_t *next = fiber->reg_next;
    SCHED_LOG(
      "shutdown reaping unfinished fiber '%s' (never scheduled, or suspended with no waker?)",
      fiber->name
    );
    // TODO(lxsameer): Free up the ring here as well
    FIBER_TRACEPOINT(fiber_stack_free, (void *)fiber, fiber->name);
    srn_fiber_stack_free(fiber->stack);
    srn_fiber_on_reap(fiber);
    fiber->reg_prev = nullptr;
    fiber->reg_next = nullptr;
    fiber           = next;
  }
  sched->registry = nullptr;
 
  // Release the run-scoped storage (srn_mm_free tolerates null, so a scheduler
  // that never ran is fine).
  srn_mm_free(sched->engine->mm, sched->os_threads);
  srn_mm_free(sched->engine->mm, sched->workers);
  sched->os_threads = nullptr;
  sched->workers    = nullptr;
  sched->nworkers   = 0;
 
  // Destroy the synchronisation primitives. The scheduler is not usable after
  // this, so they are not re-initialised. No worker holds or waits on them now,
  // the join above made sure of that.
  (void)srn_cond_destroy(&sched->work);
  (void)srn_mutex_destroy(&sched->lock);
 
  sched->destroyed = true;
}

Here is the call graph for this function:

Here is the caller graph for this function:

srn_sched_stop()

void srn_sched_stop

(

srn_scheduler_t *

sched

)

Ask a running scheduler to stop.

Each worker routine checks the request at the top of each turn and stops once the fiber it is running yields or finishes, so a slice in flight is never cut mid-execution. srn_sched_run then returns. Fibers left queued stay unrun and are reclaimed by srn_sched_shutdown. Does not wait. Safe to call from any os thread or a fiber, but NOT from a signal handler. It takes the scheduler mutex and signals the condition variable, neither of which is async signal safe.

Definition at line 978 of file scheduler.c.

                                            {
  PANIC_IF_NULL(sched);
  // Flip RUNNING or DRAINING to STOPPING once. A drain stalled on an op that
  // never completes must remain abortable, so stop escalates a drain rather
  // than deferring to it. If the scheduler is not running, or is already
  // stopping, there is nothing to do.
  srn_sched_state_t expected = SRN_SCHED_RUNNING;
 
  if (!atomic_compare_exchange_strong(&sched->state, &expected, SRN_SCHED_STOPPING)) {
    expected = SRN_SCHED_DRAINING;
    if (!atomic_compare_exchange_strong(&sched->state, &expected, SRN_SCHED_STOPPING)) {
      return;
    }
  }
 
  // Running os threads see STOPPING at the top of their next turn. Parked os
  // threads are roused to observe it. The notify is under the lock, paired with
  // the park path, so no wakeup is lost.
  srn_mutex_lock(&sched->lock);
  srn_cond_notify_all(&sched->work);
  srn_mutex_unlock(&sched->lock);
  SCHED_LOG("stop requested");
}

Here is the call graph for this function:

Here is the caller graph for this function:

srn_sched_wake_worker()

void srn_sched_wake_worker	(	srn_scheduler_t *	sched,
		size_t	channel )

Rouse parked workers so the owner of channel consumes its completions.

The reactor's notify hook. The wake is currently a broadcast, channel names the worker that must look, but every parked worker is notified and the ones with nothing to do re-park.

Definition at line 1171 of file scheduler.c.

                                                                   {
  // TODO(lxsameer): Wake up the worker in charge of the given channel. instead
  // of waking all.
  UNUSED(channel);
  srn_mutex_lock(&sched->lock);
  srn_cond_notify_all(&sched->work);
  srn_mutex_unlock(&sched->lock);
}

Here is the call graph for this function:

Here is the caller graph for this function: