fiber.c File Reference

#include "serene/rt/fiber.h"
#include <inttypes.h>
#include <stdio.h>
#include <string.h>
#include "serene/rt/context.h"
#include "serene/rt/engine.h"
#include "serene/utils.h"

Include dependency graph for fiber.c:

Go to the source code of this file.

Functions
void	srn_fiber_switch (srn_fiber_t *from, srn_fiber_t *to)
	Compiled without AddressSanitizer instrumentation, in stack-use-after-return mode ASan would place from/to on a fake stack that __sanitizer_start_switch_fiber releases before srn_fiber_swap reads them.
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.
static void	srn_fiber_launcher (void *fiber_ptr)
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.
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.

Function Documentation

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 154 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_launcher()

void srn_fiber_launcher ( void * fiber_ptr )

static

Definition at line 184 of file fiber.c.

                                                {
  PANIC_IF_NULL(fiber_ptr);
 
  srn_fiber_t *fiber = fiber_ptr;
  // The resumer is the worker loop that switched us in, on_entry records its
  // stack bounds, and switch_final hands control back to it when the entry
  // returns.
  srn_fiber_on_entry(srn_fiber_worker_loop());
  // The worker loop already set the state to RUNNING before switching in, for
  // both the first run and every resume, so it is not set again here.
  // A null result is legal, the result is type erased and "no result" is a
  // reasonable outcome for an entry run for its effects.
  fiber->result = fiber->entry(fiber->ctx, fiber->arg);
  fiber->state  = SRN_FIBER_DONE;
  srn_fiber_switch_final(srn_fiber_worker_loop());
}

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 201 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 {
    // The autogenerated name makes logs tell fibers apart with no caller
    // input. Ids come from the engine wide object id counter, so a fiber
    // never shares its number with another runtime object.
    (void)snprintf(f->name, sizeof(f->name), "f#%" PRIu64, srn_allocate_object_id(ctx->engine));
  }
 
#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 111 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 133 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_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 247 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 255 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_switch()

void srn_fiber_switch	(	srn_fiber_t *	from,
		srn_fiber_t *	to )

Compiled without AddressSanitizer instrumentation, in stack-use-after-return mode ASan would place from/to on a fake stack that __sanitizer_start_switch_fiber releases before srn_fiber_swap reads them.

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 66 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 88 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: