Utilities

🛠️ Core utility functions for string manipulation, paths, IP parsing, and formatting More...

Files
file	time.c
	⏱️ High-precision timing utilities implementation
file	time.h
	⏱️ High-precision timing utilities using sokol_time.h and uthash

Data Structures
struct	timer_record
	Individual timer record for a named timing operation. More...
struct	adaptive_sleep_config_t
	Configuration for adaptive sleep behavior. More...
struct	adaptive_sleep_state_t
	Runtime state for adaptive sleep. More...

Macros
#define	START_TIMER(name_fmt, ...)
	Start a timer with formatted name.
#define	STOP_TIMER(name_fmt, ...)
	Stop a timer with formatted name and return elapsed time.
#define	NS_PER_US   1000.0
#define	NS_PER_MS   1000000.0
#define	NS_PER_SEC   1000000000.0
#define	NS_PER_MIN   (NS_PER_SEC * 60.0)
#define	NS_PER_HOUR   (NS_PER_MIN * 60.0)
#define	NS_PER_DAY   (NS_PER_HOUR * 24.0)
#define	NS_PER_YEAR   (NS_PER_DAY * 365.25)
#define	STOP_TIMER_AND_LOG(timer_name, log_func, msg_fmt, ...)
	Stop a timer and log the result with a custom message.

Typedefs
typedef struct timer_record	timer_record_t
	Individual timer record for a named timing operation.

Functions
bool	timer_system_init (void)
	Initialize the timing system.
void	timer_system_cleanup (void)
	Cleanup the timing system.
bool	timer_start (const char *name)
	Start a named timer.
double	timer_stop (const char *name)
	Stop a named timer and return elapsed time.
bool	timer_is_initialized (void)
	Check if timing system is initialized.
int	format_duration_ms (double milliseconds, char *buffer, size_t buffer_size)
	Format milliseconds as human-readable duration string.
int	format_duration_ns (double nanoseconds, char *buffer, size_t buffer_size)
	Format nanoseconds as human-readable duration string.
int	format_duration_s (double seconds, char *buffer, size_t buffer_size)
	Format seconds as human-readable duration string.
void	adaptive_sleep_init (adaptive_sleep_state_t *state, const adaptive_sleep_config_t *config)
	Initialize adaptive sleep state with configuration.
uint64_t	adaptive_sleep_calculate (adaptive_sleep_state_t *state, size_t queue_depth, size_t target_depth)
	Calculate adaptive sleep time based on queue depth.
void	adaptive_sleep_do (adaptive_sleep_state_t *state, size_t queue_depth, size_t target_depth)
	Calculate sleep time and immediately sleep for that duration.

Detailed Description

🛠️ Core utility functions for string manipulation, paths, IP parsing, and formatting

String utilities, path handling, IP address parsing, UTF-8 support, CRC32, and formatting.

This module provides a simple timing API for performance measurement:

• START_TIMER("name", ...) - Begin timing with formatted message
• STOP_TIMER("name") - End timing, log result, return elapsed time

Features:

• Cross-platform high-resolution timing (sokol_time.h)
• Automatic hashtable management for named timers
• Thread-safe operation with mutex protection
• Formatted timer names with printf-style arguments
• Zero overhead when timing is disabled

Example usage:

START_TIMER("process_frame_%d", frame_num);
// ... do work ...
double elapsed_ns = STOP_TIMER("process_frame_%d", frame_num);
// Use format_duration_ns() for human-readable output
char duration_str[32];
format_duration_ns(elapsed_ns, duration_str, sizeof(duration_str));
log_info("Frame took %s", duration_str);

Author

Zachary Fogg me@zf.nosp@m.o.gg

Date

September 2025

Macro Definition Documentation

NS_PER_DAY

#define NS_PER_DAY   (NS_PER_HOUR * 24.0)

#include <time.h>

Definition at line 185 of file time.h.

NS_PER_HOUR

#define NS_PER_HOUR   (NS_PER_MIN * 60.0)

#include <time.h>

Definition at line 184 of file time.h.

NS_PER_MIN

#define NS_PER_MIN   (NS_PER_SEC * 60.0)

#include <time.h>

Definition at line 183 of file time.h.

NS_PER_MS

#define NS_PER_MS   1000000.0

#include <time.h>

Definition at line 181 of file time.h.

NS_PER_SEC

#define NS_PER_SEC   1000000000.0

#include <time.h>

Definition at line 182 of file time.h.

NS_PER_US

#define NS_PER_US   1000.0

#include <time.h>

Definition at line 180 of file time.h.

NS_PER_YEAR

#define NS_PER_YEAR   (NS_PER_DAY * 365.25)

#include <time.h>

Definition at line 186 of file time.h.

START_TIMER

#define START_TIMER	(		name_fmt,
			...
	)

#include <time.h>

Value:

  do {                                                                                                                 \
    if (timer_is_initialized()) {                                                                                      \
      char _timer_name_buf[256];                                                                                       \
      snprintf(_timer_name_buf, sizeof(_timer_name_buf), name_fmt, ##__VA_ARGS__);                                     \
      (void)timer_start(_timer_name_buf);                                                                              \
    }                                                                                                                  \
  } while (0)

Start a timer with formatted name.

The timer name is created by formatting the name_fmt string with the provided arguments. This complete formatted string becomes the unique key in the hashtable.

IMPORTANT: Timer names must be unique. If a timer with the same formatted name already exists, timer_start() will return false and log an error.

Usage: START_TIMER("lock_%p", lock_ptr); // Unique per lock address START_TIMER("process_frame_%d", frame_id); // Unique per frame START_TIMER("client_%u_decode", client_id); // Unique per client

Parameters

name_fmt	Printf-style format string for timer name
...	Format arguments to create unique key

Definition at line 141 of file time.h.

     {                                                                                                                 \
    if (timer_is_initialized()) {                                                                                      \
      char _timer_name_buf[256];                                                                                       \
      snprintf(_timer_name_buf, sizeof(_timer_name_buf), name_fmt, ##__VA_ARGS__);                                     \
      (void)timer_start(_timer_name_buf);                                                                              \
    }                                                                                                                  \
  } while (0)

STOP_TIMER

#define STOP_TIMER	(		name_fmt,
			...
	)

#include <time.h>

Value:

  ({                                                                                                                   \
    double _elapsed = -1.0;                                                                                            \
    if (timer_is_initialized()) {                                                                                      \
      char _timer_name_buf[256];                                                                                       \
      snprintf(_timer_name_buf, sizeof(_timer_name_buf), name_fmt, ##__VA_ARGS__);                                     \
      _elapsed = timer_stop(_timer_name_buf);                                                                          \
    }                                                                                                                  \
    _elapsed;                                                                                                          \
  })

Stop a timer with formatted name and return elapsed time.

The timer name must match exactly (including all format arguments) with the name used in START_TIMER(). The formatted string is used as the hashtable key lookup.

Usage: double ns = STOP_TIMER("lock_%p", lock_ptr); double ns = STOP_TIMER("process_frame_%d", frame_id);

Parameters

name_fmt	Printf-style format string for timer name (must match START_TIMER)
...	Format arguments (must match START_TIMER to create same key)

Returns

Elapsed time in nanoseconds, or -1.0 if timer not found

Definition at line 165 of file time.h.

   {                                                                                                                   \
    double _elapsed = -1.0;                                                                                            \
    if (timer_is_initialized()) {                                                                                      \
      char _timer_name_buf[256];                                                                                       \
      snprintf(_timer_name_buf, sizeof(_timer_name_buf), name_fmt, ##__VA_ARGS__);                                     \
      _elapsed = timer_stop(_timer_name_buf);                                                                          \
    }                                                                                                                  \
    _elapsed;                                                                                                          \
  })

STOP_TIMER_AND_LOG

#define STOP_TIMER_AND_LOG	(		timer_name,
			log_func,
			msg_fmt,
			...
	)

#include <time.h>

Value:

  do {                                                                                                                 \
    double _elapsed_ns = STOP_TIMER(timer_name, ##__VA_ARGS__);                                                        \
    if (_elapsed_ns >= 0.0) {                                                                                          \
      char _duration_str[32];                                                                                          \
      format_duration_ns(_elapsed_ns, _duration_str, sizeof(_duration_str));                                           \
      log_func(msg_fmt " in %s", ##__VA_ARGS__, _duration_str);                                                        \
    }                                                                                                                  \
  } while (0)

Stop a timer and log the result with a custom message.

Combines STOP_TIMER() with logging. The timer is stopped, elapsed time is retrieved, and a log message is generated with the elapsed time appended in human-readable format.

Usage: STOP_TIMER_AND_LOG("client_handshake", log_info, "Crypto handshake completed successfully"); STOP_TIMER_AND_LOG("process_frame_%d", log_debug, "Frame %d processed", frame_id, frame_id);

The macro will append " in X.XXms" (or appropriate unit) to your message automatically.

Parameters

timer_name	Timer name (must match START_TIMER call)
log_func	Logging function to use (log_info, log_debug, etc.)
msg_fmt	Printf-style format string for the message
...	Format arguments for both timer name and message

Definition at line 271 of file time.h.

     {                                                                                                                 \
    double _elapsed_ns = STOP_TIMER(timer_name, ##__VA_ARGS__);                                                        \
    if (_elapsed_ns >= 0.0) {                                                                                          \
      char _duration_str[32];                                                                                          \
      format_duration_ns(_elapsed_ns, _duration_str, sizeof(_duration_str));                                           \
      log_func(msg_fmt " in %s", ##__VA_ARGS__, _duration_str);                                                        \
    }                                                                                                                  \
  } while (0)

Typedef Documentation

timer_record_t

typedef struct timer_record timer_record_t

#include <time.h>

Individual timer record for a named timing operation.

Function Documentation

adaptive_sleep_calculate()

uint64_t adaptive_sleep_calculate	(	adaptive_sleep_state_t *	state,
		size_t	queue_depth,
		size_t	target_depth
	)

#include <time.h>

Calculate adaptive sleep time based on queue depth.

Evaluates current queue depth against target and adjusts the speed multiplier:

• If queue_depth > target_depth: speed up (reduce sleep, drain queue faster)
• If queue_depth < target_depth: slow down (increase sleep back to baseline)
• Speed multiplier changes gradually based on speedup_rate/slowdown_rate

The actual sleep time is calculated as: baseline_sleep_ns / current_speed_multiplier

Example usage:

adaptive_sleep_state_t sleep_state;
adaptive_sleep_config_t config = {
  .baseline_sleep_ns = 16666667,  // ~60 FPS (16.67ms)
  .min_speed_multiplier = 1.0,    // Never slower than baseline
  .max_speed_multiplier = 4.0,    // Can process up to 4x faster (240 FPS)
  .speedup_rate = 0.1,            // Ramp up 10% per frame
  .slowdown_rate = 0.05           // Ramp down 5% per frame
};
adaptive_sleep_init(&sleep_state, &config);
 
while (running) {
  // Process one frame/packet/unit of work
  process_data();
 
  // Sleep adaptively based on queue depth
  size_t queue_depth = get_queue_size();
  uint64_t sleep_ns = adaptive_sleep_calculate(&sleep_state, queue_depth, 10);
  platform_sleep_usec(sleep_ns / 1000);
}

Parameters

state	Pointer to adaptive sleep state (will be updated)
queue_depth	Current number of items in queue/buffer
target_depth	Desired queue depth (0 = empty queue target)

Returns

Sleep time in nanoseconds

Definition at line 300 of file time.c.

                                                                                                          {
  if (!state) {
    return 0;
  }
 
  const adaptive_sleep_config_t *cfg = &state->config;
 
  // Determine if we need to speed up or slow down
  double desired_multiplier;
 
  if (queue_depth > target_depth) {
    // Queue is building up - speed up processing
    // The more items in queue, the faster we should process
    size_t backlog = queue_depth - target_depth;
 
    // Calculate desired speed based on backlog
    // Each item above target increases speed proportionally
    // This ensures we drain the queue faster the more backed up we are
    double backlog_factor = 1.0 + ((double)backlog / (double)(target_depth + 1));
    desired_multiplier = cfg->min_speed_multiplier * backlog_factor;
 
    // Clamp to max speed
    if (desired_multiplier > cfg->max_speed_multiplier) {
      desired_multiplier = cfg->max_speed_multiplier;
    }
 
    // Ramp up gradually based on speedup_rate
    double delta = desired_multiplier - state->current_speed_multiplier;
    state->current_speed_multiplier += delta * cfg->speedup_rate;
 
  } else {
    // Queue is at or below target - slow down to baseline
    desired_multiplier = cfg->min_speed_multiplier;
 
    // Ramp down gradually based on slowdown_rate
    double delta = desired_multiplier - state->current_speed_multiplier;
    state->current_speed_multiplier += delta * cfg->slowdown_rate;
  }
 
  // Ensure we stay within configured bounds
  if (state->current_speed_multiplier < cfg->min_speed_multiplier) {
    state->current_speed_multiplier = cfg->min_speed_multiplier;
  }
  if (state->current_speed_multiplier > cfg->max_speed_multiplier) {
    state->current_speed_multiplier = cfg->max_speed_multiplier;
  }
 
  // Calculate actual sleep time: baseline / speed_multiplier
  // Higher multiplier = shorter sleep = faster processing
  uint64_t sleep_ns = (uint64_t)(cfg->baseline_sleep_ns / state->current_speed_multiplier);
 
  // Store for debugging
  state->last_sleep_ns = sleep_ns;
 
  return sleep_ns;
}

References adaptive_sleep_config_t::baseline_sleep_ns, adaptive_sleep_state_t::config, adaptive_sleep_state_t::current_speed_multiplier, adaptive_sleep_state_t::last_sleep_ns, adaptive_sleep_config_t::max_speed_multiplier, adaptive_sleep_config_t::min_speed_multiplier, adaptive_sleep_config_t::slowdown_rate, and adaptive_sleep_config_t::speedup_rate.

Referenced by adaptive_sleep_do().

adaptive_sleep_do()

void adaptive_sleep_do	(	adaptive_sleep_state_t *	state,
		size_t	queue_depth,
		size_t	target_depth
	)

#include <time.h>

Calculate sleep time and immediately sleep for that duration.

Convenience wrapper that combines adaptive_sleep_calculate() with platform_sleep_usec(). Useful for simple loops that don't need to inspect the calculated sleep time.

Parameters

state	Pointer to adaptive sleep state (will be updated)
queue_depth	Current number of items in queue/buffer
target_depth	Desired queue depth (0 = empty queue target)

Definition at line 357 of file time.c.

                                                                                               {
  uint64_t sleep_ns = adaptive_sleep_calculate(state, queue_depth, target_depth);
 
  if (sleep_ns > 0) {
    // Convert nanoseconds to microseconds for platform_sleep_usec
    uint64_t sleep_us = sleep_ns / 1000;
    if (sleep_us > 0) {
      platform_sleep_usec(sleep_us);
    }
  }
}

References adaptive_sleep_calculate(), and platform_sleep_usec().

adaptive_sleep_init()

void adaptive_sleep_init	(	adaptive_sleep_state_t *	state,
		const adaptive_sleep_config_t *	config
	)

#include <time.h>

Initialize adaptive sleep state with configuration.

Sets up an adaptive sleep state structure with the provided configuration. The configuration is copied internally, so the caller doesn't need to keep the config structure alive.

Parameters

state	Pointer to adaptive sleep state to initialize
config	Pointer to configuration (will be copied)

Definition at line 285 of file time.c.

                                                                                               {
  if (!state || !config) {
    return;
  }
 
  // Copy configuration
  state->config = *config;
 
  // Start at baseline speed (no speedup initially)
  state->current_speed_multiplier = config->min_speed_multiplier;
 
  // Initial sleep is the baseline
  state->last_sleep_ns = config->baseline_sleep_ns;
}

References adaptive_sleep_config_t::baseline_sleep_ns, adaptive_sleep_state_t::config, adaptive_sleep_state_t::current_speed_multiplier, adaptive_sleep_state_t::last_sleep_ns, and adaptive_sleep_config_t::min_speed_multiplier.

format_duration_ms()

int format_duration_ms	(	double	milliseconds,
		char *	buffer,
		size_t	buffer_size
	)

#include <time.h>

Format milliseconds as human-readable duration string.

Parameters

milliseconds	Duration in milliseconds
buffer	Output buffer for formatted string
buffer_size	Size of output buffer

Returns

Number of characters written (excluding null terminator), or -1 on error

Formats a duration in milliseconds into a human-readable string. The function automatically selects the most appropriate units and precision based on the duration magnitude.

Format rules:

• For sub-millisecond durations: shows ns or µs
• For sub-second durations: shows ms
• For sub-minute durations: shows seconds with decimal
• For sub-hour durations: shows minutes and seconds (e.g., "1m30s")
• For sub-day durations: shows hours, minutes, and seconds (e.g., "5h30m0s")
• For sub-year durations: shows days, hours, minutes, and seconds (e.g., "1d4h48m0s")
• For year+ durations: shows years with decimal

Note

Buffer should be at least 32 bytes for all possible outputs

Thread-safe (no global state)

Definition at line 269 of file time.c.

                                                                              {
  // Convert milliseconds to nanoseconds and use the nanosecond formatter
  double nanoseconds = milliseconds * NS_PER_MS;
  return format_duration_ns(nanoseconds, buffer, buffer_size);
}

References format_duration_ns(), and NS_PER_MS.

Referenced by broadcast_server_state_to_all_clients().

format_duration_ns()

int format_duration_ns	(	double	nanoseconds,
		char *	buffer,
		size_t	buffer_size
	)

#include <time.h>

Format nanoseconds as human-readable duration string.

Parameters

nanoseconds	Duration in nanoseconds
buffer	Output buffer for formatted string
buffer_size	Size of output buffer

Returns

Number of characters written (excluding null terminator), or -1 on error

Similar to format_duration_ms() but accepts nanosecond precision input. Useful for high-precision timing measurements.

Note

Buffer should be at least 32 bytes for all possible outputs

Thread-safe (no global state)

Definition at line 187 of file time.c.

                                                                             {
  if (!buffer || buffer_size == 0) {
    return -1;
  }
 
  // Handle negative durations
  if (nanoseconds < 0) {
    nanoseconds = -nanoseconds;
  }
 
  int written = 0;
 
  // Nanoseconds (< 1µs)
  if (nanoseconds < NS_PER_US) {
    written = snprintf(buffer, buffer_size, "%.0fns", nanoseconds);
  }
  // Microseconds (< 1ms)
  else if (nanoseconds < NS_PER_MS) {
    double us = nanoseconds / NS_PER_US;
    if (us < 10.0) {
      written = snprintf(buffer, buffer_size, "%.1fµs", us);
    } else {
      written = snprintf(buffer, buffer_size, "%.0fµs", us);
    }
  }
  // Milliseconds (< 1s)
  else if (nanoseconds < NS_PER_SEC) {
    double ms = nanoseconds / NS_PER_MS;
    if (ms < 10.0) {
      written = snprintf(buffer, buffer_size, "%.1fms", ms);
    } else {
      written = snprintf(buffer, buffer_size, "%.0fms", ms);
    }
  }
  // Seconds (< 1m)
  else if (nanoseconds < NS_PER_MIN) {
    double s = nanoseconds / NS_PER_SEC;
    if (s < 10.0) {
      written = snprintf(buffer, buffer_size, "%.2fs", s);
    } else {
      written = snprintf(buffer, buffer_size, "%.1fs", s);
    }
  }
  // Minutes (< 1h) - show minutes and seconds
  else if (nanoseconds < NS_PER_HOUR) {
    int minutes = (int)(nanoseconds / NS_PER_MIN);
    int seconds = (int)((nanoseconds - (minutes * NS_PER_MIN)) / NS_PER_SEC);
    written = snprintf(buffer, buffer_size, "%dm%ds", minutes, seconds);
  }
  // Hours (< 1d) - show hours, minutes, and seconds
  else if (nanoseconds < NS_PER_DAY) {
    int hours = (int)(nanoseconds / NS_PER_HOUR);
    double remaining_ns = nanoseconds - ((double)hours * NS_PER_HOUR);
    int minutes = (int)(remaining_ns / NS_PER_MIN);
    double remaining_after_min = remaining_ns - ((double)minutes * NS_PER_MIN);
    int seconds = (int)(remaining_after_min / NS_PER_SEC);
    written = snprintf(buffer, buffer_size, "%dh%dm%ds", hours, minutes, seconds);
  }
  // Days (< 1y) - show days, hours, minutes, and seconds
  else if (nanoseconds < NS_PER_YEAR) {
    int days = (int)(nanoseconds / NS_PER_DAY);
    double remaining_ns = nanoseconds - ((double)days * NS_PER_DAY);
    int hours = (int)(remaining_ns / NS_PER_HOUR);
    remaining_ns = remaining_ns - ((double)hours * NS_PER_HOUR);
    int minutes = (int)(remaining_ns / NS_PER_MIN);
    double remaining_after_min = remaining_ns - ((double)minutes * NS_PER_MIN);
    int seconds = (int)(remaining_after_min / NS_PER_SEC);
    written = snprintf(buffer, buffer_size, "%dd%dh%dm%ds", days, hours, minutes, seconds);
  }
  // Years - show years with one decimal
  else {
    double years = nanoseconds / NS_PER_YEAR;
    written = snprintf(buffer, buffer_size, "%.1fy", years);
  }
 
  if (written < 0 || (size_t)written >= buffer_size) {
    return -1;
  }
 
  return written;
}

References NS_PER_DAY, NS_PER_HOUR, NS_PER_MIN, NS_PER_MS, NS_PER_SEC, NS_PER_US, and NS_PER_YEAR.

Referenced by asciichat_instr_log_line(), format_duration_ms(), format_duration_s(), mixer_process_excluding_source(), and timer_stop().

format_duration_s()

int format_duration_s	(	double	seconds,
		char *	buffer,
		size_t	buffer_size
	)

#include <time.h>

Format seconds as human-readable duration string.

Parameters

seconds	Duration in seconds
buffer	Output buffer for formatted string
buffer_size	Size of output buffer

Returns

Number of characters written (excluding null terminator), or -1 on error

Similar to format_duration_ms() but accepts seconds as input. Useful for timing measurements already in seconds.

Note

Buffer should be at least 32 bytes for all possible outputs

Thread-safe (no global state)

Definition at line 275 of file time.c.

                                                                        {
  // Convert seconds to nanoseconds and use the nanosecond formatter
  double nanoseconds = seconds * NS_PER_SEC;
  return format_duration_ns(nanoseconds, buffer, buffer_size);
}

References format_duration_ns(), and NS_PER_SEC.

Referenced by crypto_init(), and crypto_rekey_init().

timer_is_initialized()

bool timer_is_initialized

(

void

)

#include <time.h>

Check if timing system is initialized.

Returns

true if initialized, false otherwise

Definition at line 179 of file time.c.

                                {
  return g_timer_manager.initialized;
}

timer_start()

bool timer_start

(

const char *

name

)

#include <time.h>

Start a named timer.

Creates a new timer record and stores the start time. If a timer with the same name exists, it will be overwritten.

Parameters

name	Timer name (must be unique, will be copied)

Returns

true on success, false on failure

Definition at line 84 of file time.c.

                                   {
  if (!g_timer_manager.initialized) {
    SET_ERRNO(ERROR_INVALID_STATE, "Timer system not initialized");
    return false;
  }
 
  if (!name) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Timer name is NULL");
    return false;
  }
 
  rwlock_wrlock(&g_timer_manager.rwlock);
 
  // Check if timer already exists - this is an error, timers must be unique
  timer_record_t *existing = NULL;
  HASH_FIND_STR(g_timer_manager.timers, name, existing);
 
  if (existing) {
    rwlock_wrunlock(&g_timer_manager.rwlock);
    SET_ERRNO(ERROR_INVALID_STATE, "Timer '%s' already exists - timers must have unique names", name);
    return false;
  }
 
  // Create new timer record
  timer_record_t *timer = SAFE_MALLOC(sizeof(timer_record_t), timer_record_t *);
  if (!timer) {
    rwlock_wrunlock(&g_timer_manager.rwlock);
    SET_ERRNO(ERROR_MEMORY, "Failed to allocate timer record");
    return false;
  }
 
  // Use platform-safe string duplication
  size_t name_len = strlen(name) + 1;
  timer->name = SAFE_MALLOC(name_len, char *);
  if (!timer->name) {
    SAFE_FREE(timer);
    rwlock_wrunlock(&g_timer_manager.rwlock);
    SET_ERRNO(ERROR_MEMORY, "Failed to allocate timer name");
    return false;
  }
  SAFE_STRNCPY(timer->name, name, name_len);
 
  timer->start_ticks = stm_now();
 
  // Add to hashtable
  HASH_ADD_KEYPTR(hh, g_timer_manager.timers, timer->name, strlen(timer->name), timer);
 
  rwlock_wrunlock(&g_timer_manager.rwlock);
  return true;
}

References ERROR_INVALID_PARAM, ERROR_INVALID_STATE, ERROR_MEMORY, timer_record::name, rwlock_wrlock, rwlock_wrunlock, SAFE_FREE, SAFE_MALLOC, SAFE_STRNCPY, SET_ERRNO, and timer_record::start_ticks.

timer_stop()

double timer_stop

(

const char *

name

)

#include <time.h>

Stop a named timer and return elapsed time.

Looks up the timer by name, calculates elapsed time, logs it, and removes the timer from the hashtable.

Parameters

name	Timer name to stop

Returns

Elapsed time in nanoseconds, or -1.0 if timer not found

Definition at line 135 of file time.c.

                                    {
  if (!g_timer_manager.initialized) {
    SET_ERRNO(ERROR_INVALID_STATE, "Timer system not initialized");
    return -1.0;
  }
 
  if (!name) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Timer name is NULL");
    return -1.0;
  }
 
  rwlock_wrlock(&g_timer_manager.rwlock);
 
  // Find timer
  timer_record_t *timer = NULL;
  HASH_FIND_STR(g_timer_manager.timers, name, timer);
 
  if (!timer) {
    rwlock_wrunlock(&g_timer_manager.rwlock);
    log_warn("Timer '%s' not found", name);
    return -1.0;
  }
 
  // Calculate elapsed time in nanoseconds for maximum precision
  uint64_t end_ticks = stm_now();
  uint64_t elapsed_ticks = stm_diff(end_ticks, timer->start_ticks);
  double elapsed_ns = stm_ns(elapsed_ticks);
 
  // Format duration for human-readable logging
  char duration_str[32];
  format_duration_ns(elapsed_ns, duration_str, sizeof(duration_str));
 
  // Log the result (debug level - caller can use return value for production logging)
  log_debug("Timer '%s': %s", name, duration_str);
 
  // Remove from hashtable
  HASH_DEL(g_timer_manager.timers, timer);
  SAFE_FREE(timer->name);
  SAFE_FREE(timer);
 
  rwlock_wrunlock(&g_timer_manager.rwlock);
  return elapsed_ns; // Return nanoseconds
}

References ERROR_INVALID_PARAM, ERROR_INVALID_STATE, format_duration_ns(), log_debug, log_warn, timer_record::name, rwlock_wrlock, rwlock_wrunlock, SAFE_FREE, SET_ERRNO, and timer_record::start_ticks.

timer_system_cleanup()

void timer_system_cleanup

(

void

)

#include <time.h>

Cleanup the timing system.

Frees all timer records and destroys mutex. Should be called at program exit.

Definition at line 60 of file time.c.

                                {
  if (!g_timer_manager.initialized) {
    return;
  }
 
  rwlock_wrlock(&g_timer_manager.rwlock);
 
  // Free all timer records
  timer_record_t *current, *tmp;
  HASH_ITER(hh, g_timer_manager.timers, current, tmp) {
    HASH_DEL(g_timer_manager.timers, current);
    SAFE_FREE(current->name);
    SAFE_FREE(current);
  }
 
  g_timer_manager.timers = NULL;
  g_timer_manager.initialized = false;
 
  rwlock_wrunlock(&g_timer_manager.rwlock);
  rwlock_destroy(&g_timer_manager.rwlock);
 
  log_debug("Timer system cleaned up");
}

References log_debug, timer_record::name, rwlock_destroy(), rwlock_wrlock, rwlock_wrunlock, and SAFE_FREE.

timer_system_init()

bool timer_system_init

(

void

)

#include <time.h>

Initialize the timing system.

Must be called before using any timer functions. Automatically calls stm_setup() for sokol_time initialization.

Returns

true on success, false on failure

Definition at line 39 of file time.c.

                             {
  if (g_timer_manager.initialized) {
    return true;
  }
 
  // Initialize sokol_time
  stm_setup();
 
  // Initialize rwlock (uthash requires external locking for writes, rwlock allows concurrent reads)
  if (rwlock_init(&g_timer_manager.rwlock) != 0) {
    SET_ERRNO(ERROR_PLATFORM_INIT, "Failed to initialize timer rwlock");
    return false;
  }
 
  g_timer_manager.timers = NULL;
  g_timer_manager.initialized = true;
 
  log_debug("Timer system initialized");
  return true;
}

References ERROR_PLATFORM_INIT, log_debug, rwlock_init(), and SET_ERRNO.