configuration.h

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/>.
 */
 
/** @file
 The single place that holds every runtime knob.
 
 `srn_configuration_t` gathers the tunable values the runtime offers into one
 struct, grouped by subsystem (memory manager, fibers, reactor, limits). Code
 that needs a configurable value reads it from here rather than from a scattered
 `#define`, so there is one source of truth and one place to override.
 
 What lives here is policy: values that could reasonably differ between runs.
 What does NOT live here is structure or protocol -- types, memory-layout
 constants, and constants that size fixed C arrays or feed a `static_assert`
 (the seq branching factor, the value payload size, reserved id ranges). Those
 stay compile-time macros because the code cannot express them as a runtime
 field without being restructured.
 
 The configuration is read-only once the runtime is up, and it must exist before
 the memory manager is created (the MM needs `mm.block_size_magnitude` at
 init), so it is
 the first thing constructed.
*/
 
#pragma once
 
#include <stddef.h>
 
// -----------------------------------------------------------------------------
// Defaults
// -----------------------------------------------------------------------------
// One source for every default. `SRN_CONFIG_DEFAULTS` below builds a fully
// populated configuration from these.
 
/**
 * Magnitude of one memory-manager block. The block size is
 * `1 << block_size_magnitude` bytes, so 17 is 128 KiB.
 */
#define SRN_CONFIG_DEFAULT_BLOCK_SIZE_MAGNITUDE 17U
 
/**
 * The default block size in bytes, derived from the magnitude.
 */
#define SRN_CONFIG_DEFAULT_BLOCK_SIZE ((size_t)1 << SRN_CONFIG_DEFAULT_BLOCK_SIZE_MAGNITUDE)
 
/**
 * Size of every fiber stack, in bytes. All fiber stacks share one size.
 */
#define SRN_CONFIG_DEFAULT_FIBER_STACK_SIZE ((size_t)1024 * 1024 * 8)
 
/**
 * Pages in the guard band below every fiber stack. A band wider than one page
 * shrinks the chance that a single oversized frame in code compiled without
 * stack probing steps over the guard and corrupts a neighbouring stack. The
 * whole band is PROT_NONE and never faulted in.
 */
#define SRN_CONFIG_DEFAULT_FIBER_GUARD_PAGES ((size_t)16)
 
/**
 * Worker count a run uses when the caller does not specify one. Zero
 * delegates to the machine, one worker per CPU the process may run on,
 * resolved at run time by srn_thread_cpu_count.
 */
#define SRN_CONFIG_DEFAULT_WORKERS 0U
 
/**
 * Upper bound a requested worker count is clamped to.
 */
#define SRN_CONFIG_DEFAULT_MAX_WORKERS 256U
 
/**
 * The absolute worker ceiling. `fiber.max_workers` may not exceed it, and
 * the scheduler clamps every run to it regardless of the configuration.
 */
#define SRN_MAX_WORKERS 256U
 
/**
 * Magnitude of each reactor channel's SQ/CQ rings, capacity is `1 << magnitude`
 * slots, which also bounds a channel's in-flight operations.
 */
#define SRN_CONFIG_DEFAULT_REACTOR_RING_MAGNITUDE 8U
 
/**
 * Most completions a worker drains from a channel in one pass.
 */
#define SRN_CONFIG_DEFAULT_REACTOR_REAP_BATCH 64U
 
/**
 * Largest string the runtime accepts, in bytes.
 */
#define SRN_CONFIG_DEFAULT_STRING_MAX_LEN ((size_t)1U << 20U)
 
/**
 * Longest namespace name the runtime accepts, in bytes.
 */
#define SRN_CONFIG_DEFAULT_NS_NAME_MAX_LEN 4096U
 
/**
 * Deepest value nesting the recursive value protocols accept.
 */
#define SRN_CONFIG_DEFAULT_MAX_VALUE_DEPTH 512U
 
// -----------------------------------------------------------------------------
// Memory-manager knobs
// -----------------------------------------------------------------------------
typedef struct srn_mm_config_t {
  /// Magnitude of one block the arena hands out from. The block size is
  /// `1 << block_size_magnitude` bytes, a power of two by construction, so
  /// it is a whole number of pages on every platform whose page size it
  /// covers. Read at MM init.
  size_t block_size_magnitude;
} srn_mm_config_t;
 
// -----------------------------------------------------------------------------
// Fiber and scheduler knobs
// -----------------------------------------------------------------------------
typedef struct srn_fiber_config_t {
  /// Size of every fiber stack, in bytes. A per-fiber size of 0 falls back to
  /// this.
  size_t stack_size;
 
  /// Pages in the guard band below every fiber stack. Applies to every stack
  /// the run allocates. Must be at least one page. Read at stack allocation.
  size_t guard_pages;
 
  /// Worker count used when a run does not specify one. Zero delegates to
  /// the CPU count at run time.
  size_t workers;
 
  /// Hard ceiling a requested worker count is clamped to.
  size_t max_workers;
} srn_fiber_config_t;
 
// -----------------------------------------------------------------------------
// Reactor knobs
// -----------------------------------------------------------------------------
typedef enum srn_reactor_backend_e {
  SRN_REACTOR_EPOLL,
  SRN_REACTOR_IO_URING,
  SRN_REACTOR_KQUEUE,
  SRN_REACTOR_IOCP,
} srn_reactor_backend_e;
 
typedef struct srn_reactor_config_t {
  /// Magnitude of each channel's SQ/CQ rings, capacity is `1 << magnitude`.
  /// This also bounds the operations a channel can have in flight, so the
  /// armed-operation table is sized from it rather than grown.
  size_t ring_magnitude;
 
  /// Most completions a worker drains from its channel in a single pass.
  size_t reap_batch;
  /// What IO backend to use
  srn_reactor_backend_e backend;
} srn_reactor_config_t;
 
/**
 * Size and length limits the runtime enforces.
 */
typedef struct srn_limits_config_t {
  /// Largest string accepted, in bytes.
  size_t string_max_len;
 
  /// Longest namespace name accepted, in bytes.
  size_t ns_name_max_len;
 
  // TODO: Enforce this limit. Print, eq, and hash recurse one C stack frame
  // per nesting level, so a deep value overflows a fixed size fiber stack.
  // Thread a countdown through the three walks, print elides deeper
  // structure, eq and hash report a resource error. An iterative rewrite
  // with heap worklists removes the limit entirely and is the long term
  // shape.
  /// Deepest value nesting print, eq, and hash accept.
  size_t max_value_depth;
} srn_limits_config_t;
 
// -----------------------------------------------------------------------------
// The configuration
// -----------------------------------------------------------------------------
 
/**
 * Every runtime knob, in one place. Constructed before the memory manager and
 * read-only thereafter.
 */
typedef struct srn_configuration_t {
  srn_mm_config_t mm;
  srn_fiber_config_t fiber;
  srn_reactor_config_t reactor;
  srn_limits_config_t limits;
} srn_configuration_t;
 
#ifdef __linux__
#  define SRN_CHOOSE_BACKEND SRN_REACTOR_EPOLL
#endif
 
#ifdef __APPLE__
#  define SRN_CHOOSE_BACKEND SRN_REACTOR_KQUEUE
#endif
 
#ifdef _WIN32
#  define SRN_CHOOSE_BACKEND SRN_REACTOR_IOCP
#endif
 
#ifndef SRN_CHOOSE_BACKEND
#  error "no reactor backend for this target (need epoll/kqueue/IOCP/...)"
#endif
 
/**
 * A configuration with every field set to its default. Use as an initializer:
 * `srn_configuration_t cfg = SRN_CONFIG_DEFAULTS;`.
 */
 
/**
 * Panic unless every knob in `config` is usable. Called by `srn_mm_init` and
 * `srn_engine_make` on the configuration they are given, so a bad value
 * fails loudly at startup, naming the knob, instead of corrupting whatever
 * is sized or bounded by it later.
 */
[[gnu::nonnull(1)]]
void srn_config_validate(const srn_configuration_t *config);
 
#define SRN_CONFIG_DEFAULTS                                                  \
  ((srn_configuration_t){                                                    \
    .mm = {.block_size_magnitude = SRN_CONFIG_DEFAULT_BLOCK_SIZE_MAGNITUDE}, \
    .fiber =                                                                 \
      {.stack_size  = SRN_CONFIG_DEFAULT_FIBER_STACK_SIZE,                   \
       .guard_pages = SRN_CONFIG_DEFAULT_FIBER_GUARD_PAGES,                  \
       .workers     = SRN_CONFIG_DEFAULT_WORKERS,                            \
       .max_workers = SRN_CONFIG_DEFAULT_MAX_WORKERS},                       \
    .reactor =                                                               \
      {                                                                      \
        .ring_magnitude = SRN_CONFIG_DEFAULT_REACTOR_RING_MAGNITUDE,         \
        .reap_batch     = SRN_CONFIG_DEFAULT_REACTOR_REAP_BATCH,             \
        .backend        = SRN_CHOOSE_BACKEND,                                \
      },                                                                     \
    .limits = {                                                              \
      .string_max_len  = SRN_CONFIG_DEFAULT_STRING_MAX_LEN,                  \
      .ns_name_max_len = SRN_CONFIG_DEFAULT_NS_NAME_MAX_LEN,                 \
      .max_value_depth = SRN_CONFIG_DEFAULT_MAX_VALUE_DEPTH                  \
    }                                                                        \
  })