04_suspend_resume.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 04 -- suspend and resume, the building block for blocking.
//
// `srn_fiber_yield` keeps a fiber runnable. `srn_fiber_suspend` parks it off
// every queue until some party calls `srn_fiber_ready` on it. This is the seam
// a lock, a channel, or an IO reactor uses to block a fiber on an event and
// wake it when the event arrives.
//
// Suspending is race free by construction. The fiber switches off its stack
// FIRST, and only then does the scheduler run the commit callback on its own
// side. The commit registers the fiber with whatever will wake it and re-checks
// the condition. A waker can never see a half parked fiber, because the commit
// runs after the park is complete. The commit returns false to decline parking
// when the condition already holds, so the fiber resumes at once.
//
// A one slot mailbox shows the handoff. The consumer runs first and finds the
// slot empty, so it parks and registers itself as the waiter. The producer
// fills the slot and readies the consumer, which resumes and reads the value.
 
#include <stdio.h>
 
#include "serene/rt/context.h"
#include "serene/rt/engine.h"
#include "serene/rt/fiber.h"
#include "serene/rt/mm/interface.h"
 
static int ok;
 
typedef struct {
  int value;
  bool has_value;
  // The fiber waiting for a value, or null if none is waiting.
  srn_fiber_t *waiter;
} mailbox_t;
 
static mailbox_t mailbox;
 
// Park commit. It runs on the worker after the consumer has parked. If a value
// is already there it declines to park, so the consumer resumes immediately.
// Otherwise it records the consumer as the waiter and stays parked.
static bool park_on_empty(srn_fiber_t *self, void *arg) {
  mailbox_t *mb = arg;
  if (mb->has_value) {
    return false;
  }
  mb->waiter = self;
  return true;
}
 
static srn_fiber_result_t consumer(srn_context_t *ctx, void *arg) {
  (void)ctx;
  (void)arg;
  printf("consumer: waiting for a value\n");
  srn_fiber_suspend(park_on_empty, &mailbox);
  printf("consumer: received %d\n", mailbox.value);
  return &ok;
}
 
static srn_fiber_result_t producer(srn_context_t *ctx, void *arg) {
  (void)ctx;
  (void)arg;
  mailbox.value = 42;
  mailbox.has_value = true;
  printf("producer: put %d in the mailbox\n", mailbox.value);
  // Wake the consumer if one is parked on the mailbox.
  if (mailbox.waiter != nullptr) {
    srn_fiber_t *w = mailbox.waiter;
    mailbox.waiter = nullptr;
    srn_fiber_ready(w);
  }
  return &ok;
}
 
int main(void) {
  srn_mm_t *mm = srn_mm_init();
  srn_engine_t *engine = srn_engine_make(mm);
  srn_context_t *ctx = srn_context_make(engine);
  srn_scheduler_t *sched = engine->scheduler;
 
  // The consumer is created first so it runs and parks before the producer
  // fills the slot.
  (void)srn_fiber_make(ctx, sched, consumer, nullptr, 0);
  (void)srn_fiber_make(ctx, sched, producer, nullptr, 0);
 
  srn_sched_run(sched, 1);
 
  srn_context_release(ctx);
  srn_engine_shutdown(engine);
  srn_mm_shutdown(mm);
  return 0;
}