fiber.c

Go to the documentation of this file.

/* -*- C -*-
 * Serene programming language
 * Copyright (C) 2019-2026 Sameer Rahmani <[email protected]>
 *
 * 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 "serene/rt/context.h"
#include "serene/utils.h"
 
#include <string.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
}
 
void srn_fiber_init_thread(srn_fiber_t *f) {
  // Represent the calling thread as the running fiber. Its stack bounds are not
  // queried here (there is no portable way). Under the sanitizer the first
  // fiber's srn_fiber_on_entry records them. 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;
  f->name = "thread";
#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.
  srn_fiber_result_t v = fiber->entry(fiber->ctx, fiber->arg);
  PANIC_IF_NULL(v);
  fiber->result = v;
  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, srn_fiber_entry_t entry,
                            void *arg, size_t stack_size) {
 
  srn_fiber_t *f = ALLOC(ctx, srn_fiber_t);
  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.
  f->stack = srn_fiber_stack_alloc(stack_size);
  f->ctx = ctx;
  f->state = SRN_FIBER_NEW;
  f->entry = entry;
  f->arg = arg;
#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);
 
  // TODO(lxsameer): revisit whether make should auto-enqueue (spawn semantics)
  // or stay NEW and require an explicit srn_fiber_ready to start. For now
  // make == spawn: the fiber is runnable the moment it is created.
  srn_sched_enqueue(sched, f);
  return f;
}