rcu.h File Reference

Go to the source code of this file.

Functions
asciichat_error_t	options_state_init (void)
	Initialize RCU options system.
asciichat_error_t	options_state_set (const options_t *opts)
	Set options from a parsed options struct.
void	options_state_destroy (void)
	Shutdown RCU options system.
const options_t *	options_get (void)
	Get current options (lock-free read).
size_t	options_retired_snapshot_count (void)
void	options_cleanup_schema (void)
	Clean up schema resources.

Function Documentation

options_cleanup_schema()

void options_cleanup_schema

(

void

)

Clean up schema resources.

Frees the dynamically allocated options schema array and all associated strings. Should be called at program shutdown after options_state_destroy(). Safe to call multiple times or if schema was never built.

Definition at line 507 of file rcu.c.

                                  {
  config_schema_destroy();
}

References config_schema_destroy().

Referenced by main().

options_retired_snapshot_count()

size_t options_retired_snapshot_count

(

void

)

Number of retired borrowed snapshots retained until shutdown.

Definition at line 322 of file rcu.c.

                                            {
  if (!lifecycle_is_initialized(&g_options_lifecycle))
    return 0;
  mutex_lock(&g_deferred_free_mutex);
  size_t count = g_retired_count;
  mutex_unlock(&g_deferred_free_mutex);
  return count;
}

options_state_destroy()

void options_state_destroy

(

void

)

Shutdown RCU options system.

Frees the current options struct and cleans up resources. Should be called at program shutdown after all threads have exited.

Definition at line 476 of file rcu.c.

                                 {
  // Check if initialized using lifecycle
  if (!lifecycle_is_initialized(&g_options_lifecycle)) {
    return;
  }
 
  /* Shutdown lifecycle to mark as no longer initialized */
  lifecycle_shutdown(&g_options_lifecycle);
 
  // Get current options pointer
  options_t *current = atomic_ptr_load(&g_options);
 
  // Clear the atomic pointer (prevent further reads)
  atomic_ptr_store(&g_options, NULL);
 
  // Free current struct
  SAFE_FREE(current);
 
  // Free all deferred structs
  deferred_free_all();
 
  // Cleanup schema (frees all dynamically allocated config strings)
  config_schema_destroy();
 
  // Destroy dynamically created mutexes
  mutex_destroy(&g_options_write_mutex);
  mutex_destroy(&g_deferred_free_mutex);
 
  log_debug("Options state shutdown complete");
}

References config_schema_destroy(), log_debug, and SAFE_FREE.

Referenced by asciichat_shared_destroy(), main(), and mirror_cleanup().

options_state_init()

asciichat_error_t options_state_init

(

void

)

Initialize RCU options system.

Must be called once at program startup before any threads access options. Allocates initial options struct and sets up atomic pointer.

Returns

ASCIICHAT_OK on success, error code on failure

Definition at line 380 of file rcu.c.

                                           {
  // RCU setters validate against the option registry, including when callers
  // use the state API directly in tests or embedded integrations. Initialize
  // the registry here so those callers observe the same metadata as the CLI.
  registry_init_size();
 
  // Detect fork: after fork(), child process must reinitialize
  pid_t current_pid = platform_get_pid();
  if ((lifecycle_is_initialized(&g_options_lifecycle) || g_init_pid != -1) && g_init_pid != current_pid) {
    log_debug("Detected fork (parent PID %d, child PID %d) - resetting lifecycle", g_init_pid, current_pid);
    /* Reset lifecycle to allow reinitialization after fork */
    lifecycle_shutdown(&g_options_lifecycle);
    g_init_pid = current_pid;
  }
 
  // Check if already initialized in this process using lifecycle
  if (lifecycle_is_initialized(&g_options_lifecycle) && g_init_pid == current_pid &&
      atomic_ptr_load(&g_options) != NULL) {
    log_warn("Options state already initialized");
    return ASCIICHAT_OK;
  }
  if (lifecycle_is_initialized(&g_options_lifecycle) && atomic_ptr_load(&g_options) == NULL) {
    lifecycle_shutdown(&g_options_lifecycle);
  }
 
  /* Use lifecycle to serialize initialization */
  if (!lifecycle_init(&g_options_lifecycle, "options")) {
    /* Another thread is initializing or already initialized */
    if (lifecycle_is_initialized(&g_options_lifecycle)) {
      return ASCIICHAT_OK;
    }
    return SET_ERRNO(ERROR_INVALID_STATE, "Failed to acquire options initialization lock");
  }
 
  // Initialize write mutex
  if (mutex_init(&g_options_write_mutex, "options_write") != 0) {
    lifecycle_shutdown(&g_options_lifecycle);
    return SET_ERRNO(ERROR_THREAD, "Failed to initialize options write mutex");
  }
 
  // Initialize deferred free mutex
  if (mutex_init(&g_deferred_free_mutex, "deferred_free") != 0) {
    mutex_destroy(&g_options_write_mutex);
    lifecycle_shutdown(&g_options_lifecycle);
    return SET_ERRNO(ERROR_THREAD, "Failed to initialize deferred free mutex");
  }
 
  // Allocate initial options struct (will be populated later by options_state_populate_from_globals)
  options_t *initial_opts = SAFE_MALLOC(sizeof(options_t), options_t *);
  if (!initial_opts) {
    mutex_destroy(&g_options_write_mutex);
    mutex_destroy(&g_deferred_free_mutex);
    lifecycle_shutdown(&g_options_lifecycle);
    return SET_ERRNO(ERROR_MEMORY, "Failed to allocate initial options struct");
  }
 
  // Initialize all defaults using options_t_new()
  *initial_opts = options_t_new();
 
  // Publish initial struct (release semantics - make all fields visible to readers)
  atomic_ptr_store(&g_options, initial_opts);
 
  ++g_revision;
  g_origin = OPTIONS_ORIGIN_CONFIG;
  g_init_pid = current_pid; // Record PID to detect fork later
  log_dev("Options state initialized with RCU pattern (PID %d)", current_pid);
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_INVALID_STATE, ERROR_MEMORY, ERROR_THREAD, log_debug, log_dev, log_warn, OPTIONS_ORIGIN_CONFIG, options_t_new(), platform_get_pid(), registry_init_size(), SAFE_MALLOC, and SET_ERRNO.

Referenced by __attribute__(), and options_init().

options_state_set()

asciichat_error_t options_state_set

(

const options_t *

opts

)

Set options from a parsed options struct.

Called by options_init() after parsing to publish the options struct to RCU. This atomically replaces the current options with the provided struct.

Parameters

opts	Pointer to options struct to publish (will be copied)

Returns

ASCIICHAT_OK on success, error code on failure

Definition at line 450 of file rcu.c.

                                                           {
  if (!opts) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "opts is NULL");
  }
 
  // Check initialization state using lifecycle
  if (!lifecycle_is_initialized(&g_options_lifecycle)) {
    return SET_ERRNO(ERROR_INVALID_STATE, "Options state not initialized (call options_state_init first)");
  }
 
  mutex_lock(&g_options_write_mutex);
  options_t *next = SAFE_MALLOC(sizeof(*next), options_t *);
  *next = *opts;
  options_t *previous = atomic_ptr_load(&g_options);
  if (previous->flip_x_explicit && !next->flip_x_explicit)
    next->flip_x = previous->flip_x;
  next->flip_x_explicit |= previous->flip_x_explicit;
  options_resolve_flip_x(next);
  atomic_ptr_store(&g_options, next);
  ++g_revision;
  g_origin = OPTIONS_ORIGIN_CONFIG;
  deferred_free_add(previous);
  mutex_unlock(&g_options_write_mutex);
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_INVALID_PARAM, ERROR_INVALID_STATE, retired_options::next, OPTIONS_ORIGIN_CONFIG, options_resolve_flip_x(), SAFE_MALLOC, and SET_ERRNO.

Referenced by config_load_and_apply().