fiber.c

Go to the documentation of this file.

/* -*- C -*-
 * Serene programming language
 * Copyright (C) 2019-2026 Sameer Rahmani <lxsameer@lxsameer.com>
 *
 * This library is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with this library.  If not, see <https://www.gnu.org/licenses/>.
 */
 
#include "serene/rt/fiber.h"
 
#include <stdio.h>
#include <string.h>
 
#include "serene/rt/context.h"
#include "serene/rt/engine.h"
#include "serene/utils.h"
 
#if SRN_ASAN
/// Declared directly rather than via <sanitizer/common_interface_defs.h> to
/// avoid a hard dependency on the sanitizer headers. These tell ASan when
/// execution moves between stacks, so it does not mistake a fiber switch for
/// corruption.
// NOLINTBEGIN(bugprone-*, cert-dcl*)
extern void __sanitizer_start_switch_fiber(void **fake_save, const void *bottom, size_t size);
extern void
__sanitizer_finish_switch_fiber(void *fake_save, const void **bottom_old, size_t *size_old);
// NOLINTEND(bugprone-*, cert-dcl*)
#endif
 
#if SRN_TSAN
/// Declared directly rather than via <sanitizer/tsan_interface.h> to avoid a
/// hard dependency on the sanitizer headers. TSan models each fiber as its own
/// execution context. Switching tells it which one is now running, so once
/// fibers migrate between threads it does not read one fiber's stack accesses
/// as another's.
// NOLINTBEGIN(bugprone-*, cert-dcl*)
extern void *__tsan_get_current_fiber(void);
extern void *__tsan_create_fiber(unsigned flags);
extern void __tsan_destroy_fiber(void *fiber);
extern void __tsan_switch_to_fiber(void *fiber, unsigned flags);
// NOLINTEND(bugprone-*, cert-dcl*)
#endif
 
// -----------------------------------------------------------------------------
// Fiber management
// -----------------------------------------------------------------------------
 
/// 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.
/// 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.
[[gnu::no_sanitize_address]] [[gnu::no_sanitize_thread]]
void srn_fiber_switch(srn_fiber_t *from, srn_fiber_t *to) {
 
#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
}
 
[[gnu::no_sanitize_address]] [[gnu::no_sanitize_thread]]
void srn_fiber_switch_final(srn_fiber_t *to) {
#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;
}
 
[[gnu::no_sanitize_address]]
void srn_fiber_on_entry(srn_fiber_t *from) {
#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
}
 
void srn_fiber_on_reap(srn_fiber_t *fiber) {
#if SRN_TSAN
  __tsan_destroy_fiber(fiber->tsan_fiber);
#else
  UNUSED(fiber);
#endif
}
 
#if SRN_ASAN
/**
 * Entry of the throwaway fiber srn_fiber_init_thread runs once per thread.
 * srn_fiber_on_entry makes ASan report the stack this fiber was started
 * from, the loop's own stack, and records its bounds on the loop fiber.
 */
static void stack_bounds_probe(void *loop_ptr) {
  srn_fiber_t *loop = loop_ptr;
  srn_fiber_on_entry(loop);
  srn_fiber_switch_final(loop);
}
#endif
 
void srn_fiber_init_thread(srn_fiber_t *f) {
  // 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");
  // One usable page and a one page guard. The probe only measures stack bounds
  // and is freed at once, so it does not need the configured guard band.
  probe.stack = srn_fiber_stack_alloc(1, 1);
  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
}
 
static void srn_fiber_launcher(void *fiber_ptr) {
  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());
}
 
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
) {
 
  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. The
  // guard band is engine wide, always taken from the configuration.
  f->stack = srn_fiber_stack_alloc(
    stack_size != 0 ? stack_size : ctx->engine->config.fiber.stack_size,
    ctx->engine->config.fiber.guard_pages
  );
  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;
}
 
srn_fiber_t *srn_fiber_spawn(srn_context_t *ctx, srn_fiber_entry_t entry, void *arg) {
  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;
}
 
srn_fiber_t *
srn_fiber_spawn_copy(srn_context_t *ctx, srn_fiber_entry_t entry, const void *arg, size_t size) {
  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);
}