06_request_term.c

Go to the documentation of this file.

/* -*- C -*-
 * Serene programming language
 * Copyright (C) 2019-2026 Sameer Rahmani <[email protected]>
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program 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 General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */
 
// Example 06 -- asking the scheduler to stop.
//
// A scheduler normally runs until it goes quiescent, every worker idle with no
// work left. `srn_sched_stop` stops it before that point. Each worker
// notices the request at the top of its loop and stops once the fiber it is
// running yields or finishes, so a fiber is never cut off mid step. Work still
// queued is left unrun, and its stacks are reclaimed at shutdown through the
// scheduler's registry. The call is safe from any thread but NOT from a
// signal handler, it takes the scheduler mutex and signals its condition
// variable. A Ctrl-C or SIGTERM shutdown routes the signal into ordinary
// thread context first (a thread in sigwait, or a signalfd registered with
// the reactor) and stops from there.
//
// A controller fiber runs first and requests termination, then returns
// normally. It is the slice in flight, and termination lets it finish cleanly.
// A batch of task fibers sit queued behind it. Because the controller stops the
// scheduler before they get a turn, they never run, and the final count of
// tasks that ran is zero. That is the point: a requested stop abandons queued
// work rather than draining it.
 
#include <stdatomic.h>
#include <stdio.h>
 
#include <serene/runtime.h>
 
#define TASK_COUNT 16
 
static atomic_int tasks_ran;
 
static srn_fiber_result_t task(srn_context_t *ctx, void *arg) {
  (void)ctx;
  (void)arg;
  atomic_fetch_add(&tasks_ran, 1);
  return nullptr;
}
 
static srn_fiber_result_t controller(srn_context_t *ctx, void *arg) {
  (void)ctx;
  // The scheduler arrives through the argument, so the controller can act on
  // it.
  srn_scheduler_t *sched = arg;
  printf("controller: stopping the scheduler before the tasks run\n");
  srn_sched_stop(sched);
  // Returning normally is the clean boundary the worker stops on.
  return nullptr;
}
 
int main(void) {
  SERENE_RUNTIME_INIT_WITH_SCHED(engine, sched, nullptr);
  srn_context_t *ctx = srn_context_make(engine);
 
  atomic_store(&tasks_ran, 0);
 
  // The controller is created first so it reaches the front of the ready queue
  // first and requests the stop before any task is dequeued.
  (void)srn_fiber_spawn(ctx, controller, sched);
  for (int i = 0; i < TASK_COUNT; i++) {
    (void)srn_fiber_spawn(ctx, task, nullptr);
  }
 
  // One worker keeps the order deterministic: the controller runs, stops the
  // scheduler, and the worker exits at the top of its next loop with the tasks
  // still queued.
  srn_sched_run(sched, 1);
 
  int ran = atomic_load(&tasks_ran);
  printf("%d of %d tasks ran before termination\n", ran, TASK_COUNT);
  printf("the rest were left queued and are reclaimed at shutdown\n");
 
  // Teardown order matters once a run stops with work still queued. The unrun
  // tasks are still on the scheduler's registry, yet their fiber structs live
  // in this context's blocks, so the context must not be released while they
  // are unreaped. SERENE_RUNTIME_SHUTDOWN reaps the scheduler first and the
  // memory manager then reclaims every context chain, this one included.
  SERENE_RUNTIME_SHUTDOWN(engine);
  return 0;
}