runtime.h File Reference

Go to the source code of this file.

Data Structures
struct	options_edit_t
struct	options_patch_t
struct	options_patch_result_t
struct	options_snapshot_t

Macros
#define	OPTIONS_REVISION_ANY   UINT64_MAX
#define	OPTIONS_PATCH_MAX_EDITS   32

Enumerations
enum	options_value_type_t { OPTIONS_VALUE_INT , OPTIONS_VALUE_BOOL , OPTIONS_VALUE_DOUBLE , OPTIONS_VALUE_STRING }
enum	options_operation_t { OPTIONS_ASSIGN , OPTIONS_TOGGLE , OPTIONS_ADD , OPTIONS_CYCLE }
enum	options_origin_t { OPTIONS_ORIGIN_LOCAL , OPTIONS_ORIGIN_REMOTE , OPTIONS_ORIGIN_CONFIG }

Functions
asciichat_error_t	options_apply_patch (const options_patch_t *patch, options_patch_result_t *result)
asciichat_error_t	options_prepare_patch (const options_t *current, const options_patch_t *patch, options_t *candidate, bool remote_only)
asciichat_error_t	options_read_snapshot (options_snapshot_t *snapshot)
uint64_t	options_revision (void)
asciichat_error_t	options_toggle (const char *name)
asciichat_error_t	options_adjust (const char *name, double amount)
asciichat_error_t	options_cycle (const char *name, int count)
bool	options_remote_render_field (const char *name)
asciichat_error_t	options_prepare_json (const options_t *current, const char *json, size_t length, options_t *candidate, bool remote_only)
asciichat_error_t	options_apply_json (const char *json, size_t length, uint64_t expected_revision, options_origin_t origin, options_patch_result_t *result)
char *	options_values_json (const options_t *values, bool remote_only)

Macro Definition Documentation

OPTIONS_PATCH_MAX_EDITS

#define OPTIONS_PATCH_MAX_EDITS   32

Definition at line 24 of file options/runtime.h.

Referenced by options_apply_json(), options_apply_patch(), options_prepare_json(), and options_prepare_patch().

OPTIONS_REVISION_ANY

#define OPTIONS_REVISION_ANY   UINT64_MAX

Definition at line 23 of file options/runtime.h.

Referenced by options_apply_patch(), options_prepare_json(), and patch_options().

Enumeration Type Documentation

options_operation_t

enum options_operation_t

Enumerator
OPTIONS_ASSIGN
OPTIONS_TOGGLE
OPTIONS_ADD
OPTIONS_CYCLE

Definition at line 8 of file options/runtime.h.

{ OPTIONS_ASSIGN, OPTIONS_TOGGLE, OPTIONS_ADD, OPTIONS_CYCLE } options_operation_t;

options_origin_t

enum options_origin_t

Enumerator
OPTIONS_ORIGIN_LOCAL
OPTIONS_ORIGIN_REMOTE
OPTIONS_ORIGIN_CONFIG

Definition at line 9 of file options/runtime.h.

{ OPTIONS_ORIGIN_LOCAL, OPTIONS_ORIGIN_REMOTE, OPTIONS_ORIGIN_CONFIG } options_origin_t;

options_value_type_t

enum options_value_type_t

Runtime edits are applied to the latest snapshot under the writer mutex.

Enumerator
OPTIONS_VALUE_INT
OPTIONS_VALUE_BOOL
OPTIONS_VALUE_DOUBLE
OPTIONS_VALUE_STRING

Definition at line 7 of file options/runtime.h.

{ OPTIONS_VALUE_INT, OPTIONS_VALUE_BOOL, OPTIONS_VALUE_DOUBLE, OPTIONS_VALUE_STRING } options_value_type_t;

Function Documentation

options_adjust()

asciichat_error_t options_adjust	(	const char *	name,
		double	amount )

Definition at line 914 of file rcu.c.

                                                                  {
  return apply_one(
      (options_edit_t){.name = name, .type = OPTIONS_VALUE_DOUBLE, .operation = OPTIONS_ADD, .value.number = amount});
}

References OPTIONS_ADD, and OPTIONS_VALUE_DOUBLE.

Referenced by ui_session_key().

options_apply_json()

asciichat_error_t options_apply_json	(	const char *	json,
		size_t	length,
		uint64_t	expected_revision,
		options_origin_t	origin,
		options_patch_result_t *	result )

Definition at line 1000 of file rcu.c.

                                                                                              {
  yyjson_doc *doc = NULL;
  options_edit_t edits[OPTIONS_PATCH_MAX_EDITS];
  size_t count = 0;
  asciichat_error_t error = parse_json_edits(json, length, &doc, edits, &count);
  options_patch_t patch = {.edits = edits, .count = count, .expected_revision = expected_revision, .origin = origin};
  if (error == ASCIICHAT_OK)
    error = options_apply_patch(&patch, result);
  yyjson_doc_free(doc);
  return error;
}

References ASCIICHAT_OK, options_apply_patch(), and OPTIONS_PATCH_MAX_EDITS.

Referenced by patch_options().

options_apply_patch()

asciichat_error_t options_apply_patch	(	const options_patch_t *	patch,
		options_patch_result_t *	result )

No observer callbacks or network I/O run under the writer mutex. A rejected patch publishes nothing.

Definition at line 837 of file rcu.c.

                                                                                                    {
  if (!patch || !patch->edits || !patch->count || patch->count > OPTIONS_PATCH_MAX_EDITS)
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid options patch");
  if (!lifecycle_is_initialized(&g_options_lifecycle))
    return SET_ERRNO(ERROR_INVALID_STATE, "Options are not initialized");
  mutex_lock(&g_options_write_mutex);
  if (result)
    *result = (options_patch_result_t){.revision = g_revision};
  if (patch->expected_revision != OPTIONS_REVISION_ANY && patch->expected_revision != g_revision) {
    mutex_unlock(&g_options_write_mutex);
    return SET_ERRNO(ERROR_INVALID_STATE, "Options changed; refresh and retry");
  }
  options_t *current = atomic_ptr_load(&g_options);
  options_t *candidate = SAFE_MALLOC(sizeof(*candidate), options_t *);
  asciichat_error_t error = options_prepare_patch(current, patch, candidate, false);
  if (error == ASCIICHAT_OK && memcmp(current, candidate, sizeof(*current))) {
    atomic_ptr_store(&g_options, candidate);
    deferred_free_add(current);
    ++g_revision;
    g_origin = patch->origin;
    if (result)
      *result = (options_patch_result_t){.revision = g_revision, .changed = true};
  } else
    SAFE_FREE(candidate);
  mutex_unlock(&g_options_write_mutex);
  return error;
}

References ASCIICHAT_OK, options_patch_t::count, options_patch_t::edits, ERROR_INVALID_PARAM, ERROR_INVALID_STATE, options_patch_t::expected_revision, OPTIONS_PATCH_MAX_EDITS, options_prepare_patch(), OPTIONS_REVISION_ANY, options_patch_t::origin, SAFE_FREE, SAFE_MALLOC, and SET_ERRNO.

Referenced by options_apply_json().

options_cycle()

asciichat_error_t options_cycle	(	const char *	name,
		int	count )

Definition at line 918 of file rcu.c.

                                                             {
  return apply_one(
      (options_edit_t){.name = name, .type = OPTIONS_VALUE_INT, .operation = OPTIONS_CYCLE, .value.integer = count});
}

References OPTIONS_CYCLE, and OPTIONS_VALUE_INT.

Referenced by ui_session_key().

options_prepare_json()

asciichat_error_t options_prepare_json	(	const options_t *	current,
		const char *	json,
		size_t	length,
		options_t *	candidate,
		bool	remote_only )

Definition at line 987 of file rcu.c.

                                                         {
  yyjson_doc *doc = NULL;
  options_edit_t edits[OPTIONS_PATCH_MAX_EDITS];
  size_t count = 0;
  asciichat_error_t error = parse_json_edits(json, length, &doc, edits, &count);
  options_patch_t patch = {.edits = edits, .count = count, .expected_revision = OPTIONS_REVISION_ANY};
  if (error == ASCIICHAT_OK)
    error = options_prepare_patch(current, &patch, candidate, remote_only);
  yyjson_doc_free(doc);
  return error;
}

References ASCIICHAT_OK, OPTIONS_PATCH_MAX_EDITS, options_prepare_patch(), and OPTIONS_REVISION_ANY.

Referenced by acip_settings_request(), client_settings_receive(), session_participant_receive_settings(), and session_protocol_dispatch().

options_prepare_patch()

asciichat_error_t options_prepare_patch	(	const options_t *	current,
		const options_patch_t *	patch,
		options_t *	candidate,
		bool	remote_only )

Prepare caller-owned state. The owner serializes access; remote edits use an allowlist.

Definition at line 799 of file rcu.c.

                                                          {
  if (!current || !candidate || current == candidate || !patch || !patch->edits || !patch->count ||
      patch->count > OPTIONS_PATCH_MAX_EDITS)
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid options patch");
  *candidate = *current;
  for (size_t i = 0; i < patch->count; ++i) {
    if (remote_only &&
        (!options_remote_render_field(patch->edits[i].name) || patch->edits[i].operation != OPTIONS_ASSIGN))
      return SET_ERRNO(ERROR_INVALID_PARAM, "Option is not a remote render preference");
    asciichat_error_t error = edit_candidate(candidate, &patch->edits[i]);
    if (error != ASCIICHAT_OK)
      return error;
  }
  bool animation_changed = false;
  bool stabilize_changed = false;
  for (size_t i = 0; i < patch->count; ++i) {
    const char *name = patch->edits[i].name;
    animation_changed |= !strcmp(name, "matrix_rain") || !strcmp(name, "waveform") || !strcmp(name, "fft");
    stabilize_changed |= !strcmp(name, "stabilize");
  }
  if (stabilize_changed)
    candidate->stabilize_explicit = true;
  else if (animation_changed && !candidate->stabilize_explicit)
    candidate->stabilize = !(candidate->waveform || candidate->fft);
  for (size_t i = 0; i < patch->count; ++i) {
    asciichat_error_t error = validate_field(find_field(patch->edits[i].name), candidate);
    if (error != ASCIICHAT_OK)
      return error;
  }
  asciichat_error_t palette_error = validate_glyph_palette(candidate);
  if (palette_error != ASCIICHAT_OK)
    return palette_error;
  candidate->flip_x_explicit |= current->flip_x_explicit;
  options_resolve_flip_x(candidate);
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, options_patch_t::count, options_patch_t::edits, ERROR_INVALID_PARAM, options_state::fft, options_state::flip_x_explicit, options_edit_t::name, options_edit_t::operation, OPTIONS_ASSIGN, OPTIONS_PATCH_MAX_EDITS, options_remote_render_field(), options_resolve_flip_x(), SET_ERRNO, options_state::stabilize, options_state::stabilize_explicit, validate_glyph_palette(), and options_state::waveform.

Referenced by options_apply_patch(), and options_prepare_json().

options_read_snapshot()

asciichat_error_t options_read_snapshot

(

options_snapshot_t *

snapshot

)

Capture values and revision together. Callers own the copied snapshot.

Definition at line 865 of file rcu.c.

                                                                      {
  if (!snapshot || !lifecycle_is_initialized(&g_options_lifecycle))
    return SET_ERRNO(ERROR_INVALID_STATE, "Options are not initialized");
  mutex_lock(&g_options_write_mutex);
  snapshot->values = *(options_t *)atomic_ptr_load(&g_options);
  snapshot->revision = g_revision;
  snapshot->origin = g_origin;
  mutex_unlock(&g_options_write_mutex);
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_INVALID_STATE, options_snapshot_t::origin, options_snapshot_t::revision, SET_ERRNO, and options_snapshot_t::values.

Referenced by client_protocol_start(), initial_options(), session_protocol_update_settings(), and session_settings_from_options().

options_remote_render_field()

bool options_remote_render_field

(

const char *

name

)

Only explicitly exposed fields may enter a remote rendering patch.

Definition at line 671 of file rcu.c.

                                                   {
  const runtime_field_t *field = find_field(name);
  if (!field)
    return false;
  const char *allowed[] = {
      "width",          "height",           "fps",      "color_mode", "color_filter", "render_mode", "palette_type",
      "palette_custom", "palette_explicit", "renderer", "stabilize",  "matrix_rain"};
  for (size_t i = 0; i < sizeof(allowed) / sizeof(*allowed); ++i)
    if (!strcmp(field->name, allowed[i]))
      return true;
  return false;
}

References runtime_field_t::name.

Referenced by options_prepare_patch(), and options_values_json().

options_revision()

uint64_t options_revision

(

void

)

Observers coalesce changes by reading a new snapshot when this revision changes.

Definition at line 876 of file rcu.c.

                                {
  if (!lifecycle_is_initialized(&g_options_lifecycle))
    return 0;
  mutex_lock(&g_options_write_mutex);
  uint64_t revision = g_revision;
  mutex_unlock(&g_options_write_mutex);
  return revision;
}

Referenced by EMSCRIPTEN_BINDINGS(), and session_protocol_update_settings().

options_toggle()

asciichat_error_t options_toggle

(

const char *

name

)

Definition at line 911 of file rcu.c.

                                                   {
  return apply_one((options_edit_t){.name = name, .type = OPTIONS_VALUE_BOOL, .operation = OPTIONS_TOGGLE});
}

References OPTIONS_TOGGLE, and OPTIONS_VALUE_BOOL.

Referenced by ui_session_key().

options_values_json()

char * options_values_json	(	const options_t *	values,
		bool	remote_only )

Caller releases JSON with SAFE_FREE. Only public runtime fields are serialized.

Definition at line 1013 of file rcu.c.

                                                                     {
  yyjson_mut_doc *doc = yyjson_mut_doc_new(&runtime_json_allocator);
  if (!doc)
    return NULL;
  yyjson_mut_val *root = yyjson_mut_obj(doc);
  yyjson_mut_doc_set_root(doc, root);
  for (size_t i = 0; i < sizeof(runtime_fields) / sizeof(*runtime_fields); ++i) {
    const runtime_field_t *field = &runtime_fields[i];
    bool exposed = options_remote_render_field(field->name);
    if (!remote_only &&
        (!strcmp(field->name, "flip_x") || !strcmp(field->name, "flip_x_explicit") ||
         !strcmp(field->name, "media_input") || !strcmp(field->name, "flip_y") || !strcmp(field->name, "waveform") ||
         !strcmp(field->name, "fft") || !strcmp(field->name, "fps_counter") || !strcmp(field->name, "audio_source") ||
         !strcmp(field->name, "speakers_volume") || !strcmp(field->name, "microphone_sensitivity") ||
         !strcmp(field->name, "audio_enabled")))
      exposed = true;
    if (!exposed)
      continue;
    const char *ptr = (const char *)values + field->offset;
    switch (field->type) {
    case OPTIONS_VALUE_INT:
      yyjson_mut_obj_add_int(doc, root, field->name, *(const int *)ptr);
      break;
    case OPTIONS_VALUE_BOOL:
      yyjson_mut_obj_add_bool(doc, root, field->name, *(const bool *)ptr);
      break;
    case OPTIONS_VALUE_DOUBLE:
      yyjson_mut_obj_add_real(doc, root, field->name,
                              field->size == sizeof(float) ? *(const float *)ptr : *(const double *)ptr);
      break;
    case OPTIONS_VALUE_STRING:
      yyjson_mut_obj_add_str(doc, root, field->name, ptr);
      break;
    }
  }
  char *json = yyjson_mut_write_opts(doc, 0, &runtime_json_allocator, NULL, NULL);
  yyjson_mut_doc_free(doc);
  return json;
}

References runtime_field_t::name, runtime_field_t::offset, options_remote_render_field(), OPTIONS_VALUE_BOOL, OPTIONS_VALUE_DOUBLE, OPTIONS_VALUE_INT, OPTIONS_VALUE_STRING, runtime_field_t::size, and runtime_field_t::type.

Referenced by acip_settings_request(), acip_settings_send(), and client_settings_values().