configuration.h File Reference

The single place that holds every runtime knob. More...

#include <stddef.h>

Include dependency graph for configuration.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	srn_mm_config_t
struct	srn_fiber_config_t
struct	srn_reactor_config_t
struct	srn_limits_config_t
	Size and length limits the runtime enforces. More...
struct	srn_configuration_t
	Every runtime knob, in one place. More...

Macros
#define	SRN_CONFIG_DEFAULT_BLOCK_SIZE_MAGNITUDE   17U
	Magnitude of one memory-manager block.
#define	SRN_CONFIG_DEFAULT_BLOCK_SIZE   ((size_t)1 << SRN_CONFIG_DEFAULT_BLOCK_SIZE_MAGNITUDE)
	The default block size in bytes, derived from the magnitude.
#define	SRN_CONFIG_DEFAULT_FIBER_STACK_SIZE   ((size_t)128 * 1024)
	Size of every fiber stack, in bytes.
#define	SRN_CONFIG_DEFAULT_WORKERS   1U
	Worker count a run uses when the caller does not specify one.
#define	SRN_CONFIG_DEFAULT_MAX_WORKERS   256U
	Upper bound a requested worker count is clamped to.
#define	SRN_MAX_WORKERS   256U
	The absolute worker ceiling.
#define	SRN_CONFIG_DEFAULT_REACTOR_RING_MAGNITUDE   8U
	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_REAP_BATCH   64U
	Most completions a worker drains from a channel in one pass.
#define	SRN_CONFIG_DEFAULT_STRING_MAX_LEN   ((size_t)1U << 20U)
	Largest string the runtime accepts, in bytes.
#define	SRN_CONFIG_DEFAULT_NS_NAME_MAX_LEN   4096U
	Longest namespace name the runtime accepts, in bytes.
#define	SRN_CONFIG_DEFAULT_MAX_VALUE_DEPTH   512U
	Deepest value nesting the recursive value protocols accept.
#define	SRN_CONFIG_DEFAULTS

Typedefs
typedef struct srn_mm_config_t	srn_mm_config_t
typedef struct srn_fiber_config_t	srn_fiber_config_t
typedef enum srn_reactor_backend_e	srn_reactor_backend_e
typedef struct srn_reactor_config_t	srn_reactor_config_t
typedef struct srn_limits_config_t	srn_limits_config_t
	Size and length limits the runtime enforces.
typedef struct srn_configuration_t	srn_configuration_t
	Every runtime knob, in one place.

Enumerations
enum	srn_reactor_backend_e { SRN_REACTOR_EPOLL , SRN_REACTOR_IO_URING , SRN_REACTOR_KQUEUE , SRN_REACTOR_IOCP }

Functions
void	srn_config_validate (const srn_configuration_t *config)
	A configuration with every field set to its default.

Detailed Description

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.

Definition in file configuration.h.

Macro Definition Documentation

SRN_CONFIG_DEFAULT_BLOCK_SIZE

#define SRN_CONFIG_DEFAULT_BLOCK_SIZE   ((size_t)1 << SRN_CONFIG_DEFAULT_BLOCK_SIZE_MAGNITUDE)

The default block size in bytes, derived from the magnitude.

Definition at line 59 of file configuration.h.

SRN_CONFIG_DEFAULT_BLOCK_SIZE_MAGNITUDE

#define SRN_CONFIG_DEFAULT_BLOCK_SIZE_MAGNITUDE   17U

Magnitude of one memory-manager block.

The block size is 1 << block_size_magnitude bytes, so 17 is 128 KiB.

Definition at line 54 of file configuration.h.

SRN_CONFIG_DEFAULT_FIBER_STACK_SIZE

#define SRN_CONFIG_DEFAULT_FIBER_STACK_SIZE   ((size_t)128 * 1024)

Size of every fiber stack, in bytes.

All fiber stacks share one size.

Definition at line 64 of file configuration.h.

SRN_CONFIG_DEFAULT_MAX_VALUE_DEPTH

#define SRN_CONFIG_DEFAULT_MAX_VALUE_DEPTH   512U

Deepest value nesting the recursive value protocols accept.

Definition at line 106 of file configuration.h.

SRN_CONFIG_DEFAULT_MAX_WORKERS

#define SRN_CONFIG_DEFAULT_MAX_WORKERS   256U

Upper bound a requested worker count is clamped to.

Definition at line 74 of file configuration.h.

SRN_CONFIG_DEFAULT_NS_NAME_MAX_LEN

#define SRN_CONFIG_DEFAULT_NS_NAME_MAX_LEN   4096U

Longest namespace name the runtime accepts, in bytes.

Definition at line 101 of file configuration.h.

SRN_CONFIG_DEFAULT_REACTOR_REAP_BATCH

#define SRN_CONFIG_DEFAULT_REACTOR_REAP_BATCH   64U

Most completions a worker drains from a channel in one pass.

Definition at line 91 of file configuration.h.

SRN_CONFIG_DEFAULT_REACTOR_RING_MAGNITUDE

#define SRN_CONFIG_DEFAULT_REACTOR_RING_MAGNITUDE   8U

Magnitude of each reactor channel's SQ/CQ rings, capacity is 1 << magnitude slots, which also bounds a channel's in-flight operations.

Definition at line 86 of file configuration.h.

SRN_CONFIG_DEFAULT_STRING_MAX_LEN

#define SRN_CONFIG_DEFAULT_STRING_MAX_LEN   ((size_t)1U << 20U)

Largest string the runtime accepts, in bytes.

Definition at line 96 of file configuration.h.

SRN_CONFIG_DEFAULT_WORKERS

#define SRN_CONFIG_DEFAULT_WORKERS   1U

Worker count a run uses when the caller does not specify one.

Definition at line 69 of file configuration.h.

SRN_CONFIG_DEFAULTS

#define SRN_CONFIG_DEFAULTS

Value:

((srn_configuration_t){                                                    \
  .mm = {.block_size_magnitude = SRN_CONFIG_DEFAULT_BLOCK_SIZE_MAGNITUDE}, \
  .fiber =                                                                 \
    {.stack_size  = SRN_CONFIG_DEFAULT_FIBER_STACK_SIZE,                   \
     .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                  \
  }                                                                        \
})

Definition at line 221 of file configuration.h.

#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,                   \
       .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                  \
    }                                                                        \
  })

SRN_MAX_WORKERS

#define SRN_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.

Definition at line 80 of file configuration.h.

Typedef Documentation

srn_configuration_t

typedef struct srn_configuration_t srn_configuration_t

Every runtime knob, in one place.

Constructed before the memory manager and read-only thereafter.

srn_fiber_config_t

typedef struct srn_fiber_config_t srn_fiber_config_t

srn_limits_config_t

typedef struct srn_limits_config_t srn_limits_config_t

Size and length limits the runtime enforces.

srn_mm_config_t

typedef struct srn_mm_config_t srn_mm_config_t

srn_reactor_backend_e

typedef enum srn_reactor_backend_e srn_reactor_backend_e

srn_reactor_config_t

typedef struct srn_reactor_config_t srn_reactor_config_t

Enumeration Type Documentation

srn_reactor_backend_e

enum srn_reactor_backend_e

Enumerator
SRN_REACTOR_EPOLL
SRN_REACTOR_IO_URING
SRN_REACTOR_KQUEUE
SRN_REACTOR_IOCP

Definition at line 137 of file configuration.h.

                                   {
  SRN_REACTOR_EPOLL,
  SRN_REACTOR_IO_URING,
  SRN_REACTOR_KQUEUE,
  SRN_REACTOR_IOCP,
} srn_reactor_backend_e;

Function Documentation

srn_config_validate()

void srn_config_validate

(

const srn_configuration_t *

config

)

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.

Definition at line 26 of file configuration.c.

                                                            {
  PANIC_IF_NULL(config);
 
  // Pages are powers of two on every platform in practice, which makes a
  // covering power of two a whole number of pages. The modulo still checks
  // it, in case a platform reports an unusual page size. The upper bound
  // keeps the shift defined and the block size sane.
  PANIC_IF(
    config->mm.block_size_magnitude > 30 ||
      ((size_t)1 << config->mm.block_size_magnitude) < srn_mm_get_os_page_size() ||
      ((size_t)1 << config->mm.block_size_magnitude) % srn_mm_get_os_page_size() != 0,
    "config: mm.block_size_magnitude must yield a whole number of OS pages, within 30"
  );
  PANIC_IF(
    config->fiber.stack_size < FALLBACK_PAGE_SIZE || config->fiber.stack_size > SIZE_MAX / 2,
    "config: fiber.stack_size must be within one page..SIZE_MAX/2"
  );
 
  PANIC_IF(config->fiber.workers < 1, "config: fiber.workers must be at least 1");
  PANIC_IF(
    config->fiber.max_workers < config->fiber.workers ||
      config->fiber.max_workers > SRN_MAX_WORKERS,
    "config: fiber.max_workers must be within fiber.workers..SRN_MAX_WORKERS"
  );
 
  // The ring magnitude bounds every ring, the admission cap, and the backend
  // op pool; the reap batch is a stack buffer size on the workers.
  PANIC_IF(
    config->reactor.ring_magnitude < 1 || config->reactor.ring_magnitude > 16,
    "config: reactor.ring_magnitude must be within 1..16"
  );
  PANIC_IF(
    config->reactor.reap_batch < 1 ||
      config->reactor.reap_batch > ((size_t)1 << config->reactor.ring_magnitude),
    "config: reactor.reap_batch must be within 1..ring capacity"
  );
 
  // A zero limit rejects everything, including the runtime's own interned
  // names, which is never what a configuration means.
  PANIC_IF(config->limits.string_max_len < 1, "config: limits.string_max_len must be at least 1");
  PANIC_IF(config->limits.ns_name_max_len < 1, "config: limits.ns_name_max_len must be at least 1");
}

Here is the call graph for this function:

Here is the caller graph for this function: