stats.c File Reference

Go to the source code of this file.

Data Structures
struct	stats_duration_cell_t
struct	stats_duration_shard_t
	For stats duration cell, this is the live record that ties sequence, observations, total_ns, min_ns together. The owning code creates it, updates it while work is active, and releases its handles and pointed-to storage before freeing the record. More...
struct	stats_scope
	stats duration shard keeps the values that move through the subsystem: owner. Some members are pointers into caller- or subsystem-owned memory, so lifetime follows the API that populated them rather than the struct copy itself. More...
struct	stats_sampler
	This is the handoff point for stats scope. Callers fill observer, observer_context, id, started_ns before passing it on; consumers read the values during the operation and return ownership only where the member contract explicitly says they do. More...

Macros
#define	STATS_DURATION_SHARDS   16

Functions
asciichat_error_t	stats_scope_create (const stats_capabilities_t *capabilities, stats_scope_t **out_scope)
void	stats_scope_destroy (stats_scope_t *scope)
void	stats_scope_set_observer (stats_scope_t *scope, stats_observer_fn observer, void *context)
void	stats_counter_add (stats_scope_t *scope, stats_counter_id_t id, uint64_t amount)
void	stats_gauge_set (stats_scope_t *scope, stats_gauge_id_t id, uint64_t value)
void	stats_duration_record (stats_scope_t *scope, stats_duration_id_t id, uint64_t elapsed_ns)
asciichat_error_t	stats_scope_snapshot (const stats_scope_t *scope, stats_snapshot_t *out)
	stats sampler config keeps the values that move through the subsystem: window_ns, resolution_ns. Some members are pointers into caller- or subsystem-owned memory, so lifetime follows the API that populated them rather than the struct copy itself.
asciichat_error_t	stats_sampler_create (const stats_sampler_config_t *config, stats_sampler_t **out_sampler)
asciichat_error_t	stats_sampler_update (stats_sampler_t *sampler, const stats_snapshot_t *snapshot, stats_rates_t *out_rates)
void	stats_sampler_destroy (stats_sampler_t *sampler)

Macro Definition Documentation

STATS_DURATION_SHARDS

#define STATS_DURATION_SHARDS   16

Definition at line 12 of file lib/stats/stats.c.

Referenced by stats_scope_snapshot().

Function Documentation

stats_counter_add()

void stats_counter_add	(	stats_scope_t *	scope,
		stats_counter_id_t	id,
		uint64_t	amount )

Thread-safe recording with no module allocations. Platform mutex diagnostics may initialize per-thread storage on first use in debug builds. NULL, invalid IDs, and unsupported metrics are ignored. Counters and duration totals wrap at UINT64_MAX; samplers rebaseline on observed decreases. Durations measure attempts (including failures); successful operations are counted separately. A gauge's producer owns its current value.

Definition at line 112 of file lib/stats/stats.c.

                                                                                     {
  if (scope && (unsigned)id < STATS_COUNTER_COUNT && scope->capabilities.counters[id]) {
    atomic_fetch_add_u64_impl(&scope->counters[id], amount);
    if (scope->observer)
      scope->observer(STATS_RECORD_COUNTER, id, amount, scope->observer_context);
  }
}

References stats_scope::counters, stats_scope::observer, stats_scope::observer_context, and STATS_RECORD_COUNTER.

Referenced by acip_handle_acds_packet(), acip_send_session_joined(), client_video_render_thread(), database_session_cleanup_expired(), database_session_update_host(), h265_decode(), h265_encode(), h265_encoder_flush(), http_request_cancel(), http_response_finish(), http_server_authorize(), http_server_dispatch_http3(), mcp_dispatch(), mcp_error(), packet_decode_frame_data_malloc(), packet_decode_frame_data_workspace(), rate_limiter_check(), session_display_encode_frame(), stats_runtime_packet(), and video_frame_commit().

stats_duration_record()

void stats_duration_record	(	stats_scope_t *	scope,
		stats_duration_id_t	id,
		uint64_t	elapsed_ns )

Definition at line 151 of file lib/stats/stats.c.

                                                                                              {
  if (!scope || (unsigned)id >= STATS_DURATION_COUNT || !scope->capabilities.durations[id])
    return;
  stats_duration_shard_t *shard = duration_shard(scope);
  if (shard) {
    stats_duration_cell_t *cell = &shard->durations[id];
    uint64_t sequence = atomic_load(&cell->sequence);
    atomic_store(&cell->sequence, duration_add(sequence, 1));
    uint64_t observations = atomic_load(&cell->observations);
    if (!observations || elapsed_ns < atomic_load(&cell->min_ns))
      atomic_store(&cell->min_ns, elapsed_ns);
    if (elapsed_ns > atomic_load(&cell->max_ns))
      atomic_store(&cell->max_ns, elapsed_ns);
    atomic_store(&cell->last_ns, elapsed_ns);
    atomic_store(&cell->recorded_ns, time_get_ns());
    atomic_store(&cell->observations, duration_add(observations, 1));
    atomic_store(&cell->total_ns, duration_add(atomic_load(&cell->total_ns), elapsed_ns));
    atomic_store(&cell->sequence, duration_add(sequence, 2));
    if (scope->observer)
      scope->observer(STATS_RECORD_DURATION, id, elapsed_ns, scope->observer_context);
    return;
  }
  // Unusually many lifetime producers retain the bounded, coherent fallback.
  if (mutex_lock(&scope->duration_mutex) != 0)
    return;
  stats_duration_snapshot_t *duration = &scope->durations[id];
  duration->last_ns = elapsed_ns;
  scope->duration_recorded_ns[id] = time_get_ns();
  if (!duration->observations || elapsed_ns < duration->min_ns)
    duration->min_ns = elapsed_ns;
  if (elapsed_ns > duration->max_ns)
    duration->max_ns = elapsed_ns;
  duration->observations = duration->observations == UINT64_MAX ? 0 : duration->observations + 1;
  // Unsigned wrap is intentional; an observed decrease causes samplers to rebaseline.
  duration->total_ns = duration->total_ns > UINT64_MAX - elapsed_ns ? elapsed_ns - (UINT64_MAX - duration->total_ns) - 1
                                                                    : duration->total_ns + elapsed_ns;
  mutex_unlock(&scope->duration_mutex);
  if (scope->observer)
    scope->observer(STATS_RECORD_DURATION, id, elapsed_ns, scope->observer_context);
}

References stats_scope::capabilities, stats_scope::duration_mutex, stats_scope::duration_recorded_ns, stats_capabilities_t::durations, stats_duration_shard_t::durations, stats_scope::durations, stats_duration_cell_t::last_ns, stats_duration_snapshot_t::last_ns, stats_duration_cell_t::max_ns, stats_duration_snapshot_t::max_ns, stats_duration_cell_t::min_ns, stats_duration_snapshot_t::min_ns, stats_duration_cell_t::observations, stats_duration_snapshot_t::observations, stats_scope::observer, stats_scope::observer_context, stats_duration_cell_t::recorded_ns, stats_duration_cell_t::sequence, STATS_DURATION_COUNT, STATS_RECORD_DURATION, stats_duration_cell_t::total_ns, and stats_duration_snapshot_t::total_ns.

Referenced by acip_handle_acds_packet(), client_audio_render_thread(), client_video_render_thread(), h265_decode(), h265_encode(), h265_encoder_flush(), http_server_dispatch_http3(), packet_decode_frame_data_malloc(), packet_decode_frame_data_workspace(), server_connection_pong_received(), session_display_encode_frame(), and session_host_render_audio().

stats_gauge_set()

void stats_gauge_set	(	stats_scope_t *	scope,
		stats_gauge_id_t	id,
		uint64_t	value )

Definition at line 120 of file lib/stats/stats.c.

                                                                                {
  if (scope && (unsigned)id < STATS_GAUGE_COUNT && scope->capabilities.gauges[id]) {
    atomic_store_u64_impl(&scope->gauges[id], value);
    if (scope->observer)
      scope->observer(STATS_RECORD_GAUGE, id, value, scope->observer_context);
  }
}

References stats_scope::gauges, stats_scope::observer, stats_scope::observer_context, and STATS_RECORD_GAUGE.

Referenced by database_stats_snapshot(), http_server_dispatch_http3(), stats_runtime_peer_close(), and stats_runtime_peer_open().

stats_sampler_create()

asciichat_error_t stats_sampler_create	(	const stats_sampler_config_t *	config,
		stats_sampler_t **	out_sampler )

Bounded history: ceil(window/resolution) must be in [1, 4096]. Both durations must be nonzero and resolution <= window. Each consumer owns its own sampler; sampler operations are not thread-safe. All allocation happens at creation.

Definition at line 255 of file lib/stats/stats.c.

                                                                                                            {
  if (!out_sampler)
    return SET_ERRNO(ERROR_INVALID_PARAM, "Missing stats sampler output");
  *out_sampler = NULL;
  if (!config || !config->resolution_ns || config->window_ns < config->resolution_ns)
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid stats sampling interval");
  uint64_t slots = config->window_ns / config->resolution_ns + (config->window_ns % config->resolution_ns != 0);
  if (slots > 4096)
    return SET_ERRNO(ERROR_INVALID_PARAM, "Stats sampler exceeds 4096 history intervals");
  stats_sampler_t *sampler = SAFE_CALLOC(1, sizeof(*sampler), stats_sampler_t *);
  if (!sampler)
    return SET_ERRNO(ERROR_MEMORY, "Cannot allocate stats sampler");
  sampler->capacity = (size_t)slots + 2;
  sampler->history = SAFE_CALLOC(sampler->capacity, sizeof(*sampler->history), stats_snapshot_t *);
  if (!sampler->history) {
    SAFE_FREE(sampler);
    return SET_ERRNO(ERROR_MEMORY, "Cannot allocate stats history");
  }
  sampler->config = *config;
  *out_sampler = sampler;
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, stats_sampler::capacity, stats_sampler::config, ERROR_INVALID_PARAM, ERROR_MEMORY, stats_sampler::history, stats_sampler_config_t::resolution_ns, SAFE_CALLOC, SAFE_FREE, SET_ERRNO, and stats_sampler_config_t::window_ns.

Referenced by stats_runtime_peer_open(), and stats_runtime_start().

stats_sampler_destroy()

void stats_sampler_destroy

(

stats_sampler_t *

sampler

)

Definition at line 344 of file lib/stats/stats.c.

                                                     {
  if (!sampler)
    return;
  SAFE_FREE(sampler->history);
  SAFE_FREE(sampler);
}

References stats_sampler::history, and SAFE_FREE.

Referenced by stats_runtime_peer_close(), stats_runtime_start(), and stats_runtime_stop().

stats_sampler_update()

asciichat_error_t stats_sampler_update	(	stats_sampler_t *	sampler,
		const stats_snapshot_t *	snapshot,
		stats_rates_t *	out_rates )

Samples must be supplied regularly, even while idle. Rates use actual elapsed time from the latest retained sample at/before the window boundary (or the oldest available sample during warmup). Resolution controls history retention, not calls. ready becomes true with a positive interval; elapsed_ns exposes window warmup. Scope/capability changes, nonincreasing timestamps, or decreasing totals reset the baseline and return ready=false. Unsupported values are zero/invalid; consult the snapshot capabilities to distinguish unsupported counters from measured zero.

Definition at line 295 of file lib/stats/stats.c.

                                                                 {
  if (!sampler || !snapshot || !out_rates)
    return SET_ERRNO(ERROR_INVALID_PARAM, "Missing stats sampler, snapshot, or rates output");
  memset(out_rates, 0, sizeof(*out_rates));
  if (!sampler->count || stats_baseline_changed(&sampler->latest, snapshot)) {
    sampler->head = 0;
    sampler->count = 1;
    sampler->history[0] = *snapshot;
    sampler->latest = *snapshot;
    return ASCIICHAT_OK;
  }
  uint64_t cutoff =
      snapshot->sampled_ns > sampler->config.window_ns ? snapshot->sampled_ns - sampler->config.window_ns : 0;
  while (sampler->count > 1) {
    size_t next = (sampler->head + 1) % sampler->capacity;
    if (sampler->history[next].sampled_ns > cutoff)
      break;
    sampler->head = next;
    sampler->count--;
  }
  const stats_snapshot_t *baseline = &sampler->history[sampler->head];
  out_rates->elapsed_ns = snapshot->sampled_ns - baseline->sampled_ns;
  out_rates->ready = true;
  for (size_t i = 0; i < STATS_COUNTER_COUNT; ++i)
    if (snapshot->capabilities.counters[i])
      out_rates->counters_per_second[i] =
          (double)(snapshot->counters[i] - baseline->counters[i]) * 1e9 / (double)out_rates->elapsed_ns;
  for (size_t i = 0; i < STATS_DURATION_COUNT; ++i) {
    uint64_t observations = snapshot->durations[i].observations - baseline->durations[i].observations;
    if (snapshot->capabilities.durations[i] && observations) {
      out_rates->duration_valid[i] = true;
      out_rates->duration_mean_ns[i] =
          (double)(snapshot->durations[i].total_ns - baseline->durations[i].total_ns) / (double)observations;
    }
  }
  size_t tail = (sampler->head + sampler->count - 1) % sampler->capacity;
  if (snapshot->sampled_ns - sampler->history[tail].sampled_ns >= sampler->config.resolution_ns) {
    size_t next = (tail + 1) % sampler->capacity;
    sampler->history[next] = *snapshot;
    if (sampler->count == sampler->capacity)
      sampler->head = (sampler->head + 1) % sampler->capacity;
    else
      sampler->count++;
  }
  sampler->latest = *snapshot;
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, stats_snapshot_t::capabilities, stats_sampler::capacity, stats_sampler::config, stats_sampler::count, stats_capabilities_t::counters, stats_snapshot_t::counters, stats_rates_t::counters_per_second, stats_rates_t::duration_mean_ns, stats_rates_t::duration_valid, stats_capabilities_t::durations, stats_snapshot_t::durations, stats_rates_t::elapsed_ns, ERROR_INVALID_PARAM, stats_sampler::head, stats_sampler::history, stats_sampler::latest, stats_duration_snapshot_t::observations, stats_rates_t::ready, stats_sampler_config_t::resolution_ns, stats_snapshot_t::sampled_ns, SET_ERRNO, STATS_COUNTER_COUNT, STATS_DURATION_COUNT, stats_duration_snapshot_t::total_ns, and stats_sampler_config_t::window_ns.

stats_scope_create()

asciichat_error_t stats_scope_create	(	const stats_capabilities_t *	capabilities,
		stats_scope_t **	out_scope )

Copies capabilities. Create before workers start; destroy after all users join. No reset or automatic parent aggregation. New sessions should get new scopes.

Definition at line 71 of file lib/stats/stats.c.

                                                                                                          {
  if (!out_scope)
    return SET_ERRNO(ERROR_INVALID_PARAM, "Missing stats scope output");
  *out_scope = NULL;
  if (!capabilities)
    return SET_ERRNO(ERROR_INVALID_PARAM, "Missing stats capabilities");
  stats_scope_t *scope = SAFE_CALLOC(1, sizeof(*scope), stats_scope_t *);
  if (!scope)
    return SET_ERRNO(ERROR_MEMORY, "Cannot allocate stats scope");
  if (mutex_init(&scope->snapshot_mutex, "stats_snapshot") != 0) {
    SAFE_FREE(scope);
    return SET_ERRNO(ERROR_THREAD, "Cannot initialize stats snapshot mutex");
  }
  if (mutex_init(&scope->duration_mutex, "stats_duration") != 0) {
    mutex_destroy(&scope->snapshot_mutex);
    SAFE_FREE(scope);
    return SET_ERRNO(ERROR_THREAD, "Cannot initialize stats duration mutex");
  }
  scope->capabilities = *capabilities;
  // Bypass debug atomic instrumentation so recording never recursively collects or allocates.
  scope->id = atomic_fetch_add_u64_impl(&next_scope_id, 1) + 1;
  scope->started_ns = time_get_ns();
  *out_scope = scope;
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, stats_scope::capabilities, stats_scope::duration_mutex, ERROR_INVALID_PARAM, ERROR_MEMORY, ERROR_THREAD, stats_scope::id, SAFE_CALLOC, SAFE_FREE, SET_ERRNO, stats_scope::snapshot_mutex, and stats_scope::started_ns.

Referenced by stats_runtime_peer_open(), and stats_runtime_start().

stats_scope_destroy()

void stats_scope_destroy

(

stats_scope_t *

scope

)

Definition at line 97 of file lib/stats/stats.c.

                                               {
  if (!scope)
    return;
  mutex_destroy(&scope->duration_mutex);
  mutex_destroy(&scope->snapshot_mutex);
  SAFE_FREE(scope);
}

References stats_scope::duration_mutex, SAFE_FREE, and stats_scope::snapshot_mutex.

Referenced by stats_runtime_peer_close(), stats_runtime_peer_open(), stats_runtime_start(), and stats_runtime_stop().

stats_scope_set_observer()

void stats_scope_set_observer	(	stats_scope_t *	scope,
		stats_observer_fn	observer,
		void *	context )

Definition at line 105 of file lib/stats/stats.c.

                                                                                               {
  if (scope) {
    scope->observer = observer;
    scope->observer_context = context;
  }
}

References stats_scope::observer, and stats_scope::observer_context.

Referenced by ascii_otel_stats_attach().

stats_scope_snapshot()

asciichat_error_t stats_scope_snapshot	(	const stats_scope_t *	scope,
		stats_snapshot_t *	out )

stats sampler config keeps the values that move through the subsystem: window_ns, resolution_ns. Some members are pointers into caller- or subsystem-owned memory, so lifetime follows the API that populated them rather than the struct copy itself.

Owned value copy. Concurrent snapshots are serialized. Each duration tuple is

stats rates is intentionally a small, concrete record. Fields such as ready, elapsed_ns give callers the identity and current value they need. It is normally borrowed from, or owned by, the surrounding subsystem—not independently managed. coherent, but independent metrics need not describe one atomic application event. Empty durations have observations/min/max/last/total equal to zero.

Definition at line 192 of file lib/stats/stats.c.

                                                                                          {
  if (!scope || !out)
    return SET_ERRNO(ERROR_INVALID_PARAM, "Missing stats scope or snapshot output");
  // Logical constness: collection is unchanged; only snapshot synchronization is mutable.
  stats_scope_t *mutable_scope = (stats_scope_t *)scope;
  if (mutex_lock(&mutable_scope->snapshot_mutex) != 0)
    return SET_ERRNO(ERROR_THREAD, "Cannot lock stats snapshot");
  memset(out, 0, sizeof(*out));
  out->scope_id = scope->id;
  out->started_ns = scope->started_ns;
  out->capabilities = scope->capabilities;
  for (size_t i = 0; i < STATS_COUNTER_COUNT; ++i)
    out->counters[i] = atomic_load_u64_impl(&scope->counters[i]);
  for (size_t i = 0; i < STATS_GAUGE_COUNT; ++i)
    out->gauges[i] = atomic_load_u64_impl(&scope->gauges[i]);
  if (mutex_lock(&mutable_scope->duration_mutex) != 0) {
    mutex_unlock(&mutable_scope->snapshot_mutex);
    return SET_ERRNO(ERROR_THREAD, "Cannot lock stats durations");
  }
  memcpy(out->durations, scope->durations, sizeof(out->durations));
  uint64_t recorded_ns[STATS_DURATION_COUNT];
  memcpy(recorded_ns, scope->duration_recorded_ns, sizeof(recorded_ns));
  mutex_unlock(&mutable_scope->duration_mutex);
  for (size_t i = 0; i < STATS_DURATION_SHARDS; ++i) {
    if (!atomic_load(&scope->shards[i].owner))
      continue;
    for (size_t id = 0; id < STATS_DURATION_COUNT; ++id) {
      const stats_duration_cell_t *cell = &scope->shards[i].durations[id];
      stats_duration_snapshot_t sample;
      uint64_t stamp, before;
      for (;;) {
        before = atomic_load(&cell->sequence);
        if (before & 1)
          continue;
        sample.observations = atomic_load(&cell->observations);
        sample.total_ns = atomic_load(&cell->total_ns);
        sample.min_ns = atomic_load(&cell->min_ns);
        sample.max_ns = atomic_load(&cell->max_ns);
        sample.last_ns = atomic_load(&cell->last_ns);
        stamp = atomic_load(&cell->recorded_ns);
        if (before == atomic_load(&cell->sequence))
          break;
      }
      if (!sample.observations)
        continue;
      stats_duration_snapshot_t *total = &out->durations[id];
      if (!total->observations || sample.min_ns < total->min_ns)
        total->min_ns = sample.min_ns;
      if (sample.max_ns > total->max_ns)
        total->max_ns = sample.max_ns;
      if (stamp >= recorded_ns[id]) {
        recorded_ns[id] = stamp;
        total->last_ns = sample.last_ns;
      }
      total->observations = duration_add(total->observations, sample.observations);
      total->total_ns = duration_add(total->total_ns, sample.total_ns);
    }
  }
  out->sampled_ns = time_get_ns();
  mutex_unlock(&mutable_scope->snapshot_mutex);
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, stats_scope::capabilities, stats_scope::counters, stats_scope::duration_mutex, stats_scope::duration_recorded_ns, stats_duration_shard_t::durations, stats_scope::durations, ERROR_INVALID_PARAM, ERROR_THREAD, stats_scope::gauges, stats_scope::id, stats_duration_cell_t::last_ns, stats_duration_snapshot_t::last_ns, stats_duration_cell_t::max_ns, stats_duration_snapshot_t::max_ns, stats_duration_cell_t::min_ns, stats_duration_snapshot_t::min_ns, stats_duration_cell_t::observations, stats_duration_snapshot_t::observations, out, stats_duration_shard_t::owner, stats_duration_cell_t::recorded_ns, stats_duration_cell_t::sequence, SET_ERRNO, stats_scope::shards, stats_scope::snapshot_mutex, stats_scope::started_ns, STATS_COUNTER_COUNT, STATS_DURATION_COUNT, STATS_DURATION_SHARDS, STATS_GAUGE_COUNT, stats_duration_cell_t::total_ns, and stats_duration_snapshot_t::total_ns.

Referenced by update_server_stats().