Utilities

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

Modules
	Utility Functions
	🛠️ String, path, IP, UTF-8, CRC32, and formatting utilities

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	TIME_ATOMIC_UINT64   atomic_t
#define	TIME_ATOMIC_UINT64_INIT(val)   {0}
#define	NS_PER_US   1000.0
#define	NS_PER_MS   (1000.0 * NS_PER_US)
#define	NS_PER_SEC   (1000.0 * NS_PER_MS)
#define	NS_PER_MIN   (60.0 * NS_PER_SEC)
#define	NS_PER_HOUR   (60.0 * NS_PER_MIN)
#define	NS_PER_DAY   (24.0 * NS_PER_HOUR)
#define	NS_PER_YEAR   (365.25 * NS_PER_DAY)
#define	NS_PER_US_INT   1000ULL
#define	NS_PER_MS_INT   (1000ULL * NS_PER_US_INT)
#define	NS_PER_SEC_INT   (1000ULL * NS_PER_MS_INT)
#define	US_PER_MS_INT   1000ULL
#define	US_PER_SEC_INT   1000000ULL
#define	MS_PER_SEC_INT   1000ULL
#define	SEC_PER_MIN   60ULL
#define	SEC_PER_HOUR   (SEC_PER_MIN * SEC_PER_MIN)
#define	SEC_PER_DAY   (24ULL * SEC_PER_HOUR)
#define	NS_PER_MIN_INT   (SEC_PER_MIN * NS_PER_SEC_INT)
#define	NS_PER_HOUR_INT   (SEC_PER_HOUR * NS_PER_SEC_INT)
#define	NS_PER_DAY_INT   (SEC_PER_DAY * NS_PER_SEC_INT)
#define	START_TIMER(name_fmt, ...)
	Start a timer with formatted name.
#define	START_TIMER_GLOBAL(name_fmt, ...)
	Start a timer without thread ID (for cross-thread timers)
#define	STOP_TIMER_GLOBAL(name_fmt, ...)
	Stop a cross-thread timer and return elapsed time.
#define	STOP_TIMER(name_fmt, ...)
	Stop a timer with formatted name and return elapsed time.
#define	STOP_TIMER_AND_LOG(log_level, threshold_ns, timer_name, msg_fmt, ...)
	Stop a timer and log the result with a custom message.
#define	STOP_TIMER_AND_LOG_EVERY(log_level, interval_ns, threshold_ns, timer_name, msg_fmt, ...)
	Stop a timer and log the result with rate limiting.

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

Functions
uint64_t	time_get_ns (void)
	Get current monotonic time in nanoseconds.
uint64_t	time_get_realtime_ns (void)
	Get current wall-clock (real) time in nanoseconds.
void	time_sleep_ns (uint64_t ns)
	Sleep for specified nanoseconds.
uint64_t	time_elapsed_ns (uint64_t start_ns, uint64_t end_ns)
	Calculate elapsed time with wraparound safety.
bool	timer_system_init (void)
	Initialize the timing system.
void	timer_system_destroy (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	time_pretty (uint64_t nanoseconds, int decimals, char *buffer, size_t buffer_size)
	Format nanoseconds as pretty duration with spaces and configurable precision.
int	time_pretty_now (int decimals, char *buffer, size_t buffer_size)
	Format current monotonic time as pretty duration.
int	time_human_readable (int64_t nanoseconds, char *buffer, size_t buffer_size)
	Format nanoseconds as human-readable relative duration (moment.js style)
int	time_human_readable_unsigned (uint64_t nanoseconds, char *buffer, size_t buffer_size)
	Format elapsed time as human-readable relative duration (unsigned version)
int	time_human_readable_now (char *buffer, size_t buffer_size)
	Format current monotonic time as human-readable relative duration.
int	format_uptime_hms (int hours, int minutes, int seconds, char *buffer, size_t buffer_size)
	Format uptime as HH:MM:SS 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.
bool	time_format_is_valid_strftime (const char *format_str)
	Validate strftime format string against known safe specifiers.
int	time_format_now (const char *format_str, char *buf, size_t buf_size)
	Format current time using strftime format string.
asciichat_error_t	time_format_safe (const char *format_str, char *buf, size_t buf_size)
	Safe wrapper for time formatting with validation and error codes.
uint64_t	time_timespec_to_ns (const struct timespec *ts)
	Convert struct timespec to nanoseconds.
void	time_ns_to_timespec (uint64_t ns, struct timespec *ts)
	Convert nanoseconds to struct timespec.

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 time_pretty() for human-readable formatted output
char duration_str[32];
time_pretty((uint64_t)elapsed_ns, -1, 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

MS_PER_SEC_INT

#define MS_PER_SEC_INT   1000ULL

#include <time.h>

Definition at line 164 of file time.h.

NS_PER_DAY

#define NS_PER_DAY   (24.0 * NS_PER_HOUR)

#include <time.h>

Definition at line 151 of file time.h.

NS_PER_DAY_INT

#define NS_PER_DAY_INT   (SEC_PER_DAY * NS_PER_SEC_INT)

#include <time.h>

Definition at line 174 of file time.h.

NS_PER_HOUR

#define NS_PER_HOUR   (60.0 * NS_PER_MIN)

#include <time.h>

Definition at line 150 of file time.h.

NS_PER_HOUR_INT

#define NS_PER_HOUR_INT   (SEC_PER_HOUR * NS_PER_SEC_INT)

#include <time.h>

Definition at line 173 of file time.h.

NS_PER_MIN

#define NS_PER_MIN   (60.0 * NS_PER_SEC)

#include <time.h>

Definition at line 149 of file time.h.

NS_PER_MIN_INT

#define NS_PER_MIN_INT   (SEC_PER_MIN * NS_PER_SEC_INT)

#include <time.h>

Definition at line 172 of file time.h.

NS_PER_MS

#define NS_PER_MS   (1000.0 * NS_PER_US)

#include <time.h>

Definition at line 147 of file time.h.

NS_PER_MS_INT

#define NS_PER_MS_INT   (1000ULL * NS_PER_US_INT)

#include <time.h>

Definition at line 156 of file time.h.

NS_PER_SEC

#define NS_PER_SEC   (1000.0 * NS_PER_MS)

#include <time.h>

Definition at line 148 of file time.h.

NS_PER_SEC_INT

#define NS_PER_SEC_INT   (1000ULL * NS_PER_MS_INT)

#include <time.h>

Definition at line 157 of file time.h.

NS_PER_US

#define NS_PER_US   1000.0

#include <time.h>

Definition at line 146 of file time.h.

NS_PER_US_INT

#define NS_PER_US_INT   1000ULL

#include <time.h>

Definition at line 155 of file time.h.

NS_PER_YEAR

#define NS_PER_YEAR   (365.25 * NS_PER_DAY)

#include <time.h>

Definition at line 152 of file time.h.

SEC_PER_DAY

#define SEC_PER_DAY   (24ULL * SEC_PER_HOUR)

#include <time.h>

Definition at line 169 of file time.h.

SEC_PER_HOUR

#define SEC_PER_HOUR   (SEC_PER_MIN * SEC_PER_MIN)

#include <time.h>

Definition at line 168 of file time.h.

SEC_PER_MIN

#define SEC_PER_MIN   60ULL

#include <time.h>

Definition at line 167 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];                                                                                       \
      char _timer_name_with_tid[280];                                                                                  \
      snprintf(_timer_name_buf, sizeof(_timer_name_buf), name_fmt, ##__VA_ARGS__);                                     \
      snprintf(_timer_name_with_tid, sizeof(_timer_name_with_tid), "%s_tid%llu", _timer_name_buf,                      \
               (unsigned long long)asciichat_thread_current_id());                                                     \
      (void)timer_start(_timer_name_with_tid);                                                                         \
    }                                                                                                                  \
  } 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 333 of file time.h.

     {                                                                                                                 \
    if (timer_is_initialized()) {                                                                                      \
      char _timer_name_buf[256];                                                                                       \
      char _timer_name_with_tid[280];                                                                                  \
      snprintf(_timer_name_buf, sizeof(_timer_name_buf), name_fmt, ##__VA_ARGS__);                                     \
      snprintf(_timer_name_with_tid, sizeof(_timer_name_with_tid), "%s_tid%llu", _timer_name_buf,                      \
               (unsigned long long)asciichat_thread_current_id());                                                     \
      (void)timer_start(_timer_name_with_tid);                                                                         \
    }                                                                                                                  \
  } while (0)

START_TIMER_GLOBAL

#define START_TIMER_GLOBAL	(		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 without thread ID (for cross-thread timers)

Use this variant when a timer may be stopped on a different thread than it was started. The timer name will NOT include thread ID, so it must be globally unique through other means (e.g., including a unique identifier in the format string).

Parameters

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

Definition at line 357 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];                                                                                       \
      char _timer_name_with_tid[280];                                                                                  \
      snprintf(_timer_name_buf, sizeof(_timer_name_buf), name_fmt, ##__VA_ARGS__);                                     \
      snprintf(_timer_name_with_tid, sizeof(_timer_name_with_tid), "%s_tid%llu", _timer_name_buf,                      \
               (unsigned long long)asciichat_thread_current_id());                                                     \
      _elapsed = timer_stop(_timer_name_with_tid);                                                                     \
    }                                                                                                                  \
    _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 403 of file time.h.

   {                                                                                                                   \
    double _elapsed = -1.0;                                                                                            \
    if (timer_is_initialized()) {                                                                                      \
      char _timer_name_buf[256];                                                                                       \
      char _timer_name_with_tid[280];                                                                                  \
      snprintf(_timer_name_buf, sizeof(_timer_name_buf), name_fmt, ##__VA_ARGS__);                                     \
      snprintf(_timer_name_with_tid, sizeof(_timer_name_with_tid), "%s_tid%llu", _timer_name_buf,                      \
               (unsigned long long)asciichat_thread_current_id());                                                     \
      _elapsed = timer_stop(_timer_name_with_tid);                                                                     \
    }                                                                                                                  \
    _elapsed;                                                                                                          \
  })

STOP_TIMER_AND_LOG

#define STOP_TIMER_AND_LOG	(		log_level,
			threshold_ns,
			timer_name,
			msg_fmt,
			...
	)

#include <time.h>

Value:

  do {                                                                                                                 \
    double _elapsed_ns = STOP_TIMER(timer_name, ##__VA_ARGS__);                                                        \
    if (_elapsed_ns >= 0.0 && (threshold_ns == 0 || _elapsed_ns >= (double)(threshold_ns))) {                          \
      char _duration_str[32];                                                                                          \
      time_pretty((uint64_t)_elapsed_ns, -1, _duration_str, sizeof(_duration_str));                                    \
      log_##log_level(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. Optionally filters based on a minimum elapsed time threshold.

Usage: STOP_TIMER_AND_LOG(info, 0, "client_handshake", "Crypto handshake completed successfully"); STOP_TIMER_AND_LOG(debug, 5000000, "process_frame_%d", "Frame %d processed", frame_id, frame_id); STOP_TIMER_AND_LOG(dev, NS_PER_MS_INT, "render", "Rendering complete");

The macro will append " in X.XXms" (or appropriate unit) to your message automatically. Supported log levels: dev, debug, info, warn, error, fatal

Parameters

log_level	Log level name (dev, debug, info, warn, error, fatal - without log_ prefix)
threshold_ns	Minimum elapsed time in nanoseconds to trigger log (0 = always log)
timer_name	Timer name (must match START_TIMER call)
msg_fmt	Printf-style format string for the message
...	Format arguments for both timer name and message

Definition at line 612 of file time.h.

     {                                                                                                                 \
    double _elapsed_ns = STOP_TIMER(timer_name, ##__VA_ARGS__);                                                        \
    if (_elapsed_ns >= 0.0 && (threshold_ns == 0 || _elapsed_ns >= (double)(threshold_ns))) {                          \
      char _duration_str[32];                                                                                          \
      time_pretty((uint64_t)_elapsed_ns, -1, _duration_str, sizeof(_duration_str));                                    \
      log_##log_level(msg_fmt " in %s", ##__VA_ARGS__, _duration_str);                                                 \
    }                                                                                                                  \
  } while (0)

STOP_TIMER_AND_LOG_EVERY

#define STOP_TIMER_AND_LOG_EVERY	(		log_level,
			interval_ns,
			threshold_ns,
			timer_name,
			msg_fmt,
			...
	)

#include <time.h>

Value:

  do {                                                                                                                 \
    double _elapsed_ns = STOP_TIMER(timer_name, ##__VA_ARGS__);                                                        \
    if (_elapsed_ns >= 0.0 && (threshold_ns == 0 || _elapsed_ns >= (double)(threshold_ns))) {                          \
      static atomic_t _log_every_last_time = {0};                                                                      \
      uint64_t _log_every_now = time_get_ns();                                                                         \
      uint64_t _log_every_last = atomic_load_u64(&_log_every_last_time);                                               \
      if (_log_every_now - _log_every_last >= (uint64_t)(interval_ns)) {                                               \
        if (atomic_cas_u64(&_log_every_last_time, &_log_every_last, _log_every_now)) {                                 \
          char _duration_str[32];                                                                                      \
          time_pretty((uint64_t)_elapsed_ns, -1, _duration_str, sizeof(_duration_str));                                \
          log_##log_level(msg_fmt " in %s", ##__VA_ARGS__, _duration_str);                                             \
        }                                                                                                              \
      }                                                                                                                \
    }                                                                                                                  \
  } while (0)

Stop a timer and log the result with rate limiting.

Combines STOP_TIMER() with rate-limited logging. The timer is stopped, elapsed time is retrieved, and a log message is generated only if:

1. The elapsed time exceeds the threshold (if non-zero), AND
2. The specified time interval has passed since the last logged occurrence

This prevents log spam from frequent operations while also filtering out fast operations.

Usage: STOP_TIMER_AND_LOG_EVERY(dev, 1000000000, 0, "opus_encode", "Opus encode completed"); STOP_TIMER_AND_LOG_EVERY(info, 5000000000, NS_PER_MS_INT, "process_frame_%d", "Frame %d processed", frame_id);

The macro will append " in X.XXms" (or appropriate unit) to your message automatically. Supported log levels: dev, debug, info, warn, error, fatal

Parameters

log_level	Log level name (dev, debug, info, warn, error, fatal - without log_ prefix)
interval_ns	Time interval in nanoseconds between log emissions (rate limiting)
threshold_ns	Minimum elapsed time in nanoseconds to trigger log (0 = no threshold)
timer_name	Timer name (must match START_TIMER call)
msg_fmt	Printf-style format string for the message
...	Format arguments for both timer name and message

Definition at line 647 of file time.h.

     {                                                                                                                 \
    double _elapsed_ns = STOP_TIMER(timer_name, ##__VA_ARGS__);                                                        \
    if (_elapsed_ns >= 0.0 && (threshold_ns == 0 || _elapsed_ns >= (double)(threshold_ns))) {                          \
      static atomic_t _log_every_last_time = {0};                                                                      \
      uint64_t _log_every_now = time_get_ns();                                                                         \
      uint64_t _log_every_last = atomic_load_u64(&_log_every_last_time);                                               \
      if (_log_every_now - _log_every_last >= (uint64_t)(interval_ns)) {                                               \
        if (atomic_cas_u64(&_log_every_last_time, &_log_every_last, _log_every_now)) {                                 \
          char _duration_str[32];                                                                                      \
          time_pretty((uint64_t)_elapsed_ns, -1, _duration_str, sizeof(_duration_str));                                \
          log_##log_level(msg_fmt " in %s", ##__VA_ARGS__, _duration_str);                                             \
        }                                                                                                              \
      }                                                                                                                \
    }                                                                                                                  \
  } while (0)

STOP_TIMER_GLOBAL

#define STOP_TIMER_GLOBAL	(		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 cross-thread timer and return elapsed time.

Use this variant when stopping a timer started with START_TIMER_GLOBAL. The timer name must match exactly (without thread ID appended).

Parameters

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

Returns

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

Definition at line 377 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;                                                                                                          \
  })

TIME_ATOMIC_UINT64

#define TIME_ATOMIC_UINT64   atomic_t

#include <time.h>

Definition at line 52 of file time.h.

TIME_ATOMIC_UINT64_INIT

#define TIME_ATOMIC_UINT64_INIT

(

val

)

{0}

#include <time.h>

Definition at line 53 of file time.h.

US_PER_MS_INT

#define US_PER_MS_INT   1000ULL

#include <time.h>

Definition at line 160 of file time.h.

US_PER_SEC_INT

#define US_PER_SEC_INT   1000000ULL

#include <time.h>

Definition at line 161 of file time.h.

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_us(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 630 of file util/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 = 1.0;
    if (desired_multiplier < cfg->min_speed_multiplier) {
      desired_multiplier = cfg->min_speed_multiplier;
    }
    if (desired_multiplier > cfg->max_speed_multiplier) {
      desired_multiplier = cfg->max_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_us(). 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 693 of file util/time.c.

                                                                                               {
  uint64_t sleep_ns = adaptive_sleep_calculate(state, queue_depth, target_depth);
 
  if (sleep_ns > 0) {
    platform_sleep_ns(sleep_ns);
  }
}

References adaptive_sleep_calculate(), and platform_sleep_ns().

Referenced by session_capture_sleep_for_fps().

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 609 of file util/time.c.

                                                                                               {
  if (!state || !config) {
    return;
  }
 
  // Copy configuration
  state->config = *config;
 
  // A multiplier of 1.0 preserves the configured interval. Clamp it for
  // configurations whose allowed range does not include the baseline.
  state->current_speed_multiplier = 1.0;
  if (state->current_speed_multiplier < config->min_speed_multiplier) {
    state->current_speed_multiplier = config->min_speed_multiplier;
  }
  if (state->current_speed_multiplier > config->max_speed_multiplier) {
    state->current_speed_multiplier = config->max_speed_multiplier;
  }
 
  state->last_sleep_ns = (uint64_t)(config->baseline_sleep_ns / state->current_speed_multiplier);
}

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, and adaptive_sleep_config_t::min_speed_multiplier.

Referenced by session_capture_create(), and session_network_capture_create().

format_uptime_hms()

int format_uptime_hms	(	int	hours,
		int	minutes,
		int	seconds,
		char *	buffer,
		size_t	buffer_size
	)

#include <time.h>

Format uptime as HH:MM:SS string.

Parameters

hours	Hours component (0-999)
minutes	Minutes component (0-59)
seconds	Seconds component (0-59)
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 an uptime duration as a fixed "HH:MM:SS" string with zero-padding. Useful for status displays where consistent formatting is preferred over adaptive human-readable formats.

Examples:

• format_uptime_hms(0, 0, 5, buf, size) -> "00:00:05"
• format_uptime_hms(1, 30, 45, buf, size) -> "01:30:45"
• format_uptime_hms(123, 45, 6, buf, size) -> "123:45:06"

Note

Buffer should be at least 12 bytes (HH:MM:SS + null terminator)

Thread-safe (no global state)

Hours component can exceed 99 (e.g., "123:45:06" for 123 hours)

Definition at line 354 of file util/time.c.

                                                                                             {
  if (!buffer || buffer_size == 0) {
    return -1;
  }
 
  // Validate components
  if (hours < 0 || minutes < 0 || minutes >= 60 || seconds < 0 || seconds >= 60) {
    return -1;
  }
 
  // Format as HH:MM:SS with zero-padding
  int written = safe_snprintf(buffer, buffer_size, "%02d:%02d:%02d", hours, minutes, seconds);
 
  if (written < 0 || (size_t)written >= buffer_size) {
    return -1;
  }
 
  return written;
}

References buffer_size, and safe_snprintf().

time_elapsed_ns()

uint64_t time_elapsed_ns	(	uint64_t	start_ns,
		uint64_t	end_ns
	)

#include <time.h>

Calculate elapsed time with wraparound safety.

Computes the difference between two time values, handling potential wraparound of uint64_t (which won't happen in practice - uint64_t wraps after ~584 years at nanosecond resolution, but this is defensive).

Parameters

start_ns	Start time in nanoseconds
end_ns	End time in nanoseconds

Returns

Elapsed time in nanoseconds (end - start)

Usage:

uint64_t start = time_get_ns();
// ... do work ...
uint64_t elapsed = time_elapsed_ns(start, time_get_ns());

Definition at line 150 of file util/time.c.

                                                             {
  // Handle wraparound (defensive - uint64_t won't wrap in practice at nanosecond resolution)
  // but this is safe and handles any theoretical edge cases
  if (end_ns >= start_ns) {
    return end_ns - start_ns;
  }
  // Wraparound case (extremely unlikely)
  return (UINT64_MAX - start_ns) + end_ns + 1;
}

Referenced by ascii_convert_with_capabilities(), asciichat_instr_log_line(), audio_analysis_print_report(), broadcast_server_state_to_all_clients(), client_send_thread_func(), fps_frame_ns(), media_source_read_video(), media_source_seek(), mixer_process_excluding_source(), session_capture_get_current_fps(), session_capture_read_frame(), and session_client_like_run().

time_format_is_valid_strftime()

bool time_format_is_valid_strftime

(

const char *

format_str

)

#include <time.h>

Validate strftime format string against known safe specifiers.

Parameters

format_str

Format string to validate (e.g., "%H:%M:%S")

Returns

true if valid, false if contains invalid specifiers or syntax

Validates format string by checking each % specifier against a whitelist of known safe POSIX strftime specifiers. Returns false if:

• Contains unterminated % sequences
• Contains invalid/unsupported specifiers
• Contains malformed width/precision
• Contains unsupported locale-dependent specifiers

Supported specifiers:

• Date: Y (4-digit year), m (month), d (day), j (day of year)
• Date (ISO): F (full date), G (ISO year), g (ISO year short), V (ISO week)
• Time: H (24-hour), M (minute), S (second), I (12-hour), p (AM/PM)
• Time (combined): T (full time HH:MM:SS), s (seconds since epoch)
• Locale: a (abbrev weekday), A (full weekday), b (abbrev month), B (full month)
• Locale: c (locale date/time), x (locale date), X (locale time)
• Timezone: z (offset), Z (name)
• Weekday: w (0-6), u (1-7)

Definition at line 711 of file util/time.c.

                                                           {
  if (!format_str) {
    return false;
  }
 
  for (const char *p = format_str; *p; p++) {
    if (*p == '%') {
      p++;
      if (!*p) {
        /* Unterminated % at end of string */
        log_error("Invalid time format: unterminated %% at end");
        return false;
      }
 
      if (*p == '%') {
        /* Escaped %% - this is valid, just skip it */
        continue;
      }
 
      /* Optional: flag characters (-, 0, +, space) */
      if (*p == '-' || *p == '0' || *p == '+' || *p == ' ') {
        p++;
        if (!*p) {
          log_error("Invalid time format: flag character without specifier");
          return false;
        }
      }
 
      /* Optional: width specifier (digits or *) */
      if (*p == '*' || isdigit((unsigned char)*p)) {
        while (*p && (isdigit((unsigned char)*p) || *p == '*')) {
          p++;
        }
        if (!*p) {
          log_error("Invalid time format: width specifier without specifier character");
          return false;
        }
      }
 
      /* Optional: precision specifier (.digits or .*) */
      if (*p == '.') {
        p++;
        if (!*p) {
          log_error("Invalid time format: precision specifier incomplete");
          return false;
        }
        while (*p && (isdigit((unsigned char)*p) || *p == '*')) {
          p++;
        }
        if (!*p) {
          log_error("Invalid time format: precision specifier without specifier character");
          return false;
        }
      }
 
      /* Optional: modifier characters (E for %Ex, O for %Ox) */
      if (*p == 'E' || *p == 'O') {
        p++;
        if (!*p) {
          log_error("Invalid time format: modifier character without specifier");
          return false;
        }
      }
 
      /* Validate that the final character is a supported specifier */
      if (!strchr(SUPPORTED_SPECIFIERS, *p)) {
        log_error("Invalid time format: unsupported specifier %%%c (at position %ld)", *p, (p - format_str));
        return false;
      }
    }
  }
 
  return true;
}

References log_error.

Referenced by time_format_safe().

time_format_now()

int time_format_now	(	const char *	format_str,
		char *	buf,
		size_t	buf_size
	)

#include <time.h>

Format current time using strftime format string.

Parameters

format_str	strftime format string (should be validated with time_format_is_valid_strftime)
buf	Output buffer
buf_size	Output buffer size

Returns

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

Formats current wall-clock time (CLOCK_REALTIME) using the provided strftime format. Handles nanosecond precision separately: if format contains S and buffer has room, appends ".NNNNNN" for microseconds (rounded from nanoseconds).

Example outputs:

• Format "%H:%M:%S" → "14:30:45.123456"
• Format "%Y-%m-%d" → "2026-02-16"
• Format "%F %T" → "2026-02-16 14:30:45.123456"

Notes:

• Buffer size should be at least 64 bytes
• Automatic microsecond appending occurs only when S is in format
• Output is locale-aware (UTF-8 safe from strftime)
• Returns 0 on error (strftime failure or buffer overflow)

Definition at line 786 of file util/time.c.

                                                                        {
  if (!format_str || !buf || buf_size < 2) {
    SET_ERRNO(ERROR_INVALID_PARAM, "time_format_now: invalid arguments - format_str=%p, buf=%p, buf_size=%zu",
              format_str, buf, buf_size);
    return 0;
  }
 
  /* Get current wall-clock time in nanoseconds */
  uint64_t ts_ns = time_get_realtime_ns();
 
  /* Extract seconds and nanoseconds */
  time_t seconds = (time_t)(ts_ns / NS_PER_SEC_INT);
 
  /* Convert seconds to struct tm */
  struct tm tm_info;
  platform_localtime(&seconds, &tm_info);
 
  /* Format using strftime */
  size_t len = strftime(buf, buf_size, format_str, &tm_info);
 
  /* Check for strftime errors or buffer overflow */
  if (len == 0) {
    /* strftime returned 0 - either error or exact buffer fill */
    log_debug("strftime returned 0 for format: %s", format_str);
    return 0;
  }
 
  if (len >= buf_size - 1) {
    /* Buffer would overflow - strftime filled entire buffer or hit exact size */
    log_error("time_format_now: buffer too small (need %zu, have %zu)", len + 1, buf_size);
    return 0;
  }
 
  return (int)len;
}

References ERROR_INVALID_PARAM, log_debug, log_error, NS_PER_SEC_INT, platform_localtime(), SET_ERRNO, and time_get_realtime_ns().

Referenced by log_template_apply(), and time_format_safe().

time_format_safe()

asciichat_error_t time_format_safe	(	const char *	format_str,
		char *	buf,
		size_t	buf_size
	)

#include <time.h>

Safe wrapper for time formatting with validation and error codes.

Parameters

format_str	Format string to use
buf	Output buffer
buf_size	Output buffer size

Returns

ASCIICHAT_OK on success, error code on failure (includes error context)

Validates format string first, then formats time. Returns detailed error if:

• format_str is NULL
• buf is NULL
• buf_size < 64 (minimum safe size)
• format_str contains invalid specifiers
• strftime fails

All errors include context message via SET_ERRNO for debugging.

Example:

char timebuf[64];
asciichat_error_t err = time_format_safe("%H:%M:%S", timebuf, sizeof(timebuf));
if (err != ASCIICHAT_OK) {
    log_error("Failed to format time");
    return err;
}
log_info("Current time: %s", timebuf);

Definition at line 822 of file util/time.c.

                                                                                       {
  /* Check NULL pointers */
  if (!format_str) {
    return SET_ERRNO(ERROR_INVALID_STATE, "time_format_safe: format_str is NULL");
  }
 
  if (!buf) {
    return SET_ERRNO(ERROR_INVALID_STATE, "time_format_safe: buf is NULL");
  }
 
  /* Check minimum buffer size */
  if (buf_size < 64) {
    return SET_ERRNO(ERROR_INVALID_STATE, "time_format_safe: buffer too small (minimum 64 bytes, got %zu)", buf_size);
  }
 
  /* Validate format string */
  if (!time_format_is_valid_strftime(format_str)) {
    return SET_ERRNO(ERROR_INVALID_STATE, "time_format_safe: invalid time format: %s", format_str);
  }
 
  /* Format the time */
  int result = time_format_now(format_str, buf, buf_size);
  if (result <= 0) {
    return SET_ERRNO(ERROR_INVALID_STATE, "time_format_safe: strftime formatting failed");
  }
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_INVALID_STATE, SET_ERRNO, time_format_is_valid_strftime(), and time_format_now().

time_get_ns()

uint64_t time_get_ns

(

void

)

#include <time.h>

Get current monotonic time in nanoseconds.

Returns high-precision monotonic time that never goes backwards. Suitable for measuring elapsed time, FPS tracking, and performance metrics.

Returns

Current time in nanoseconds (monotonic, never decreases)

Usage:

uint64_t start = time_get_ns();
// ... do work ...
uint64_t elapsed_ns = time_elapsed_ns(start, time_get_ns());

Definition at line 108 of file util/time.c.

                           {
  // sokol_time provides monotonic clock that never goes backwards
  // stm_ns() converts ticks to nanoseconds
  // Ensure sokol_time is initialized before use (defensive programming)
  if (!g_sokol_time_initialized) {
    stm_setup();
    g_sokol_time_initialized = true;
  }
  return (uint64_t)stm_ns(stm_now());
}

Referenced by acds_client_handler(), acip_server_receive_and_dispatch(), ascii_convert_with_capabilities(), asciichat_instr_log_line(), atomic_on_cas(), atomic_on_fetch(), atomic_on_load(), atomic_on_store(), atomic_ptr_on_cas(), atomic_ptr_on_exchange(), atomic_ptr_on_load(), atomic_ptr_on_store(), audio_analysis_init(), audio_analysis_print_report(), audio_analysis_track_received_packet(), audio_analysis_track_sent_packet(), audio_write_samples(), broadcast_server_state_to_all_clients(), buffer_pool_free(), buffer_pool_shrink(), client_audio_render_thread(), client_dispatch_thread(), client_send_thread_func(), client_video_render_thread(), cond_format_state(), cond_on_broadcast(), cond_on_signal(), cond_on_wait(), consensus_coordinator_create(), consensus_coordinator_on_collection_start(), consensus_coordinator_process(), consensus_coordinator_time_until_next_round(), create_mixed_ascii_frame_for_client(), debug_atomic_format_timing(), debug_atomic_ptr_format_timing(), discovery_mdns_query(), discovery_session_process(), fps_counter_tick(), get_utf8_palette_cache(), media_source_read_video(), media_source_seek(), mixer_process_excluding_source(), mutex_format_state(), mutex_on_lock(), mutex_on_trylock(), mutex_on_unlock(), mutex_stack_mark_locked(), mutex_stack_push_pending(), nat_measure_bandwidth(), rwlock_format_state(), rwlock_on_rdlock(), rwlock_on_unlock(), rwlock_on_wrlock(), session_capture_create(), session_capture_get_current_fps(), session_capture_read_frame(), session_client_like_run(), session_display_convert_to_ascii(), session_display_create(), session_display_render_frame(), session_display_write_ascii(), session_network_capture_create(), session_pipeline_run_main(), session_render_loop(), simple_frame_swap_update(), splash_intro_done(), splash_intro_start(), time_human_readable_now(), time_pretty_now(), and websocket_server_run().

time_get_realtime_ns()

uint64_t time_get_realtime_ns

(

void

)

#include <time.h>

Get current wall-clock (real) time in nanoseconds.

Returns high-precision wall-clock time that can jump forwards or backwards when system time is adjusted. Use this for timestamps, database records, and user-facing time displays.

Returns

Current wall-clock time in nanoseconds (CLOCK_REALTIME)

Note: This time can jump backward if system clock is adjusted. For measuring elapsed time, use time_get_ns() instead.

Definition at line 119 of file util/time.c.

                                    {
#ifdef _WIN32
  // Windows: Use GetSystemTimePreciseAsFileTime (Win8+) for high-precision wall clock
  // FILETIME is 100-nanosecond intervals since January 1, 1601
  FILETIME ft;
  GetSystemTimePreciseAsFileTime(&ft);
  // Convert FILETIME to nanoseconds
  uint64_t filetime = ((uint64_t)ft.dwHighDateTime << 32) | ft.dwLowDateTime;
  // Convert 100-nanosecond intervals to nanoseconds
  return filetime * 100;
#else
  // Get wall-clock (real-time) timestamp
  struct timespec ts;
  if (clock_gettime(CLOCK_REALTIME, &ts) != 0) {
    // Fallback on error (unlikely)
    return 0;
  }
  return time_timespec_to_ns(&ts);
#endif
}

References time_timespec_to_ns().

Referenced by acds_validate_timestamp(), asciichat_error_stats_record(), asciichat_instr_log_line(), asciichat_set_errno(), connection_attempt_tcp(), connection_attempt_websocket(), connection_check_timeout(), connection_context_init(), consensus_metrics_measure(), consensus_state_compute_election(), database_session_is_migration_ready(), database_session_start_migration(), get_current_time_formatted(), handle_image_frame_h265_packet(), log_json_async_safe(), log_msg(), log_plain_msg(), log_terminal_msg(), and time_format_now().

time_human_readable()

int time_human_readable	(	int64_t	nanoseconds,
		char *	buffer,
		size_t	buffer_size
	)

#include <time.h>

Format nanoseconds as human-readable relative duration (moment.js style)

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

Formats a duration using moment.js-compatible thresholds to produce natural language relative time strings like "a few seconds ago", "3 minutes ago", "2 hours ago", etc.

Threshold table (moment.js compatible):

• < 45 s → "a few seconds ago"
• < 90 s → "a minute ago"
• < 45 min → "%d minutes ago"
• < 90 min → "an hour ago"
• < 22 h → "%d hours ago"
• < 36 h → "a day ago"
• < 25 d → "%d days ago"
• < 45 d → "a month ago"
• < 11 months → "%d months ago"
• < 18 months → "a year ago"
• ≥ 18 months → "%d years ago"

Note

Buffer should be at least 32 bytes for all possible outputs

Thread-safe (no global state)

Format elapsed time as human-readable relative duration with past/future support

Parameters

nanoseconds	Signed elapsed nanoseconds (negative for future times)
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 as a human-readable string with moment.js-compatible thresholds. Supports both past times ("3 hours ago") and future times ("in 5 minutes").

Examples:

• Positive: 3600000000000 ns → "an hour ago"
• Negative: -300000000000 ns → "in 5 minutes"

Note

Use positive values for elapsed time (past), negative for countdown (future)

Buffer should be at least 32 bytes for all possible outputs

Thread-safe (no global state)

Definition at line 572 of file util/time.c.

                                                                               {
  if (!buffer || buffer_size == 0) {
    return -1;
  }
 
  // Determine direction (past vs future)
  bool is_future = nanoseconds < 0;
  uint64_t abs_ns = is_future ? (uint64_t)(-nanoseconds) : (uint64_t)nanoseconds;
 
  // Convert nanoseconds to seconds for threshold checking
  double total_seconds = (double)abs_ns / NS_PER_SEC;
  int minutes = (int)(total_seconds / 60);
  int hours = minutes / 60;
  int days = hours / 24;
  int months = days / 30; // Approximate
  int years = months / 12;
 
  const char *suffix = is_future ? "from now" : "ago";
  int written =
      format_human_readable_time_ago(total_seconds, minutes, hours, days, months, years, suffix, buffer, buffer_size);
 
  if (written < 0 || (size_t)written >= buffer_size) {
    return -1;
  }
 
  return written;
}

References buffer_size, and NS_PER_SEC.

Referenced by time_human_readable_now().

time_human_readable_now()

int time_human_readable_now	(	char *	buffer,
		size_t	buffer_size
	)

#include <time.h>

Format current monotonic time as human-readable relative duration.

Parameters

buffer	Output buffer for formatted string
buffer_size	Size of output buffer

Returns

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

Convenience wrapper that calls time_get_ns() and delegates to time_human_readable(). Useful for measuring time since program start in a single call.

Note

Buffer should be at least 32 bytes for all possible outputs

Thread-safe (no global state)

Definition at line 600 of file util/time.c.

                                                              {
  int64_t ns = (int64_t)time_get_ns();
  return time_human_readable(ns, buffer, buffer_size);
}

References buffer_size, time_get_ns(), and time_human_readable().

time_human_readable_unsigned()

int time_human_readable_unsigned	(	uint64_t	nanoseconds,
		char *	buffer,
		size_t	buffer_size
	)

#include <time.h>

Format elapsed time as human-readable relative duration (unsigned version)

Parameters

nanoseconds	Unsigned elapsed nanoseconds (always past times)
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 unsigned nanosecond durations as human-readable past-time strings. Uses moment.js-compatible thresholds. All values are interpreted as elapsed time and formatted with "ago" suffix.

Examples:

• 3600000000000 ns → "an hour ago"
• 300000000000 ns → "5 minutes ago"

Note

Use this for values from time_get_ns() or other unsigned sources

Buffer should be at least 32 bytes for all possible outputs

Thread-safe (no global state)

Definition at line 549 of file util/time.c.

                                                                                         {
  if (!buffer || buffer_size == 0) {
    return -1;
  }
 
  // Convert nanoseconds to seconds for threshold checking
  double total_seconds = (double)nanoseconds / NS_PER_SEC;
  int minutes = (int)(total_seconds / 60);
  int hours = minutes / 60;
  int days = hours / 24;
  int months = days / 30; // Approximate
  int years = months / 12;
 
  int written =
      format_human_readable_time_ago(total_seconds, minutes, hours, days, months, years, "ago", buffer, buffer_size);
 
  if (written < 0 || (size_t)written >= buffer_size) {
    return -1;
  }
 
  return written;
}

References buffer_size, and NS_PER_SEC.

time_ns_to_timespec()

void time_ns_to_timespec	(	uint64_t	ns,
		struct timespec *	ts
	)

#include <time.h>

Convert nanoseconds to struct timespec.

Parameters

ns	Time in nanoseconds
ts	Pointer to timespec structure (output)

Useful for nanosleep() or other system calls that require struct timespec.

Definition at line 178 of file util/time.c.

                                                           {
  if (!ts) {
    SET_ERRNO(ERROR_INVALID_PARAM, "null ts");
    return;
  }
  ts->tv_sec = (time_t)(ns / NS_PER_SEC_INT);
  ts->tv_nsec = (long)(ns % NS_PER_SEC_INT);
}

References ERROR_INVALID_PARAM, NS_PER_SEC_INT, and SET_ERRNO.

time_pretty()

int time_pretty	(	uint64_t	nanoseconds,
		int	decimals,
		char *	buffer,
		size_t	buffer_size
	)

#include <time.h>

Format nanoseconds as pretty duration with spaces and configurable precision.

Parameters

nanoseconds	Duration in nanoseconds
decimals	Number of decimal places (0-9), or -1 for sensible defaults per range
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 with space-separated number and unit, with configurable precision. Automatically strips trailing zeros and decimal points.

Examples (with decimals=-1):

• 500 ns → "500 ns"
• 3500 ns → "3.5 µs"
• 1253000 ns → "1.253 ms"
• 2500000000 ns → "2.5 s"
• 83456000000000 ns → "1:23.456" (minutes range, MM:SS.fraction)
• 7530000000000 ns → "2:05:30" (hours range, H:MM:SS)

Unit selection logic:

• [0, 1k) ns → "NNN ns"
• [1k, 1M) ns → "N.N µs" (up to 3 decimals)
• [1M, 1G) ns → "N.NNN ms" (up to 3 decimals)
• [1G, 60G) ns → "N.NN s" (up to 2 decimals)
• [60G, 3.6T) ns → "M:SS.fraction" (colon notation, up to 3 decimals)
• [3.6T+) ns → "H:MM:SS" (colon notation)

Note

Buffer should be at least 32 bytes for all possible outputs

Thread-safe (no global state)

decimals=-1 uses appropriate defaults (3 for ns/µs/ms/colon, 2 for s)

decimals=0 produces no decimal point

Definition at line 424 of file util/time.c.

                                                                                      {
  if (!buffer || buffer_size == 0) {
    return -1;
  }
 
  // Handle zero
  if (nanoseconds == 0) {
    int written = safe_snprintf(buffer, buffer_size, "0 ns");
    return (written < 0 || (size_t)written >= buffer_size) ? -1 : written;
  }
 
  // Determine decimals for this range if not explicitly set
  int actual_decimals = decimals;
  if (decimals == -1) {
    if (nanoseconds < NS_PER_MIN_INT) {
      actual_decimals = (nanoseconds < NS_PER_SEC_INT) ? 3 : 2; // ns/µs/ms or seconds
    } else {
      actual_decimals = 3; // colon notation
    }
  }
 
  // Clamp decimals to valid range
  if (actual_decimals < 0)
    actual_decimals = 0;
  if (actual_decimals > 9)
    actual_decimals = 9;
 
  int written = 0;
 
  // Nanoseconds (< 1µs)
  if (nanoseconds < NS_PER_US_INT) {
    written = safe_snprintf(buffer, buffer_size, "%llu ns", (unsigned long long)nanoseconds);
  }
  // Microseconds (< 1ms)
  else if (nanoseconds < NS_PER_MS_INT) {
    double us = (double)nanoseconds / NS_PER_US;
    char temp_buf[64];
    // Use a direct snprintf with large enough buffer first
    snprintf(temp_buf, sizeof(temp_buf), "%.*f µs", actual_decimals, us);
    strip_trailing_zeros(temp_buf);
    written = (int)strlen(temp_buf);
    if (written > 0 && written < (int)buffer_size) {
      SAFE_STRNCPY(buffer, temp_buf, buffer_size);
    } else {
      written = -1;
    }
  }
  // Milliseconds (< 1s)
  else if (nanoseconds < NS_PER_SEC_INT) {
    double ms = (double)nanoseconds / NS_PER_MS;
    char temp_buf[64];
    snprintf(temp_buf, sizeof(temp_buf), "%.*f ms", actual_decimals, ms);
    strip_trailing_zeros(temp_buf);
    written = (int)strlen(temp_buf);
    if (written > 0 && written < (int)buffer_size) {
      SAFE_STRNCPY(buffer, temp_buf, buffer_size);
    } else {
      written = -1;
    }
  }
  // Seconds (< 1 minute)
  else if (nanoseconds < NS_PER_MIN_INT) {
    double s = (double)nanoseconds / NS_PER_SEC;
    char temp_buf[64];
    snprintf(temp_buf, sizeof(temp_buf), "%.*f s", actual_decimals, s);
    strip_trailing_zeros(temp_buf);
    written = (int)strlen(temp_buf);
    if (written > 0 && written < (int)buffer_size) {
      SAFE_STRNCPY(buffer, temp_buf, buffer_size);
    } else {
      written = -1;
    }
  }
  // Minutes (< 1 hour) - use colon notation: M:SS.frac
  else if (nanoseconds < NS_PER_HOUR_INT) {
    uint64_t total_seconds = nanoseconds / NS_PER_SEC_INT;
    uint64_t minutes = total_seconds / 60;
    uint64_t seconds = total_seconds % 60;
    uint64_t remainder_ns = nanoseconds % NS_PER_SEC_INT;
    double fraction = (double)remainder_ns / NS_PER_SEC;
 
    char temp_buf[64];
    if (actual_decimals == 0) {
      snprintf(temp_buf, sizeof(temp_buf), "%llu:%02llu", (unsigned long long)minutes, (unsigned long long)seconds);
    } else {
      snprintf(temp_buf, sizeof(temp_buf), "%llu:%02llu.%.*f", (unsigned long long)minutes, (unsigned long long)seconds,
               actual_decimals, fraction);
      strip_trailing_zeros(temp_buf);
    }
 
    written = (int)strlen(temp_buf);
    if (written > 0 && written < (int)buffer_size) {
      SAFE_STRNCPY(buffer, temp_buf, buffer_size);
    } else {
      written = -1;
    }
  }
  // Hours+ - use colon notation: H:MM:SS or HH:MM:SS
  else {
    uint64_t total_seconds = nanoseconds / NS_PER_SEC_INT;
    uint64_t hours = total_seconds / 3600;
    uint64_t remaining = total_seconds % 3600;
    uint64_t minutes = remaining / 60;
    uint64_t seconds = remaining % 60;
 
    written = safe_snprintf(buffer, buffer_size, "%llu:%02llu:%02llu", (unsigned long long)hours,
                            (unsigned long long)minutes, (unsigned long long)seconds);
  }
 
  if (written < 0 || (size_t)written >= buffer_size) {
    return -1;
  }
 
  return written;
}

References buffer_size, NS_PER_HOUR_INT, NS_PER_MIN_INT, NS_PER_MS, NS_PER_MS_INT, NS_PER_SEC, NS_PER_SEC_INT, NS_PER_US, NS_PER_US_INT, safe_snprintf(), and SAFE_STRNCPY.

Referenced by acip_server_receive_and_dispatch(), ascii_convert_with_capabilities(), asciichat_instr_log_line(), broadcast_server_state_to_all_clients(), client_send_thread_func(), client_video_render_thread(), cond_format_state(), connection_check_timeout(), create_mixed_ascii_frame_for_client(), crypto_init(), crypto_rekey_init(), debug_atomic_format_timing(), debug_atomic_ptr_format_timing(), media_source_seek(), mixer_process_excluding_source(), mutex_format_state(), rwlock_format_state(), session_display_convert_to_ascii(), session_display_write_ascii(), session_render_loop(), time_pretty_now(), and timer_stop().

time_pretty_now()

int time_pretty_now	(	int	decimals,
		char *	buffer,
		size_t	buffer_size
	)

#include <time.h>

Format current monotonic time as pretty duration.

Parameters

decimals	Number of decimal places (0-9), or -1 for sensible defaults per range
buffer	Output buffer for formatted string
buffer_size	Size of output buffer

Returns

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

Convenience wrapper that calls time_get_ns() and delegates to time_pretty(). Useful for measuring elapsed time since program start in a single call.

Note

Buffer should be at least 32 bytes for all possible outputs

Thread-safe (no global state)

Definition at line 540 of file util/time.c.

                                                                    {
  uint64_t ns = time_get_ns();
  return time_pretty(ns, decimals, buffer, buffer_size);
}

References buffer_size, time_get_ns(), and time_pretty().

time_sleep_ns()

void time_sleep_ns

(

uint64_t

ns

)

#include <time.h>

Sleep for specified nanoseconds.

Sleeps the current thread for at least the specified number of nanoseconds. On some systems, actual sleep time may be slightly longer due to scheduler granularity.

Parameters

ns	Number of nanoseconds to sleep

Definition at line 140 of file util/time.c.

                                {
  // Use platform abstraction for cross-platform sleep
  // Convert nanoseconds to microseconds (1 us = 1000 ns)
  unsigned int usec = (unsigned int)(ns / 1000);
  if (usec == 0 && ns > 0) {
    usec = 1; // Minimum 1 microsecond
  }
  platform_sleep_us(usec);
}

References platform_sleep_us().

time_timespec_to_ns()

uint64_t time_timespec_to_ns

(

const struct timespec *

ts

)

#include <time.h>

Convert struct timespec to nanoseconds.

Parameters

ts	Pointer to timespec structure

Returns

Time in nanoseconds

Useful for converting CLOCK_MONOTONIC or CLOCK_REALTIME readings to nanoseconds.

Definition at line 164 of file util/time.c.

                                                        {
  if (!ts) {
    SET_ERRNO(ERROR_INVALID_PARAM, "null ts");
    return 0;
  }
  // Use __uint128_t to prevent overflow during multiplication of large time values
  __uint128_t result = (__uint128_t)ts->tv_sec * NS_PER_SEC_INT;
  if (result > UINT64_MAX) {
    SET_ERRNO(ERROR_INVALID_PARAM, "time_timespec_to_ns: timespec value would overflow");
    return UINT64_MAX;
  }
  return (uint64_t)result + (uint64_t)ts->tv_nsec;
}

References ERROR_INVALID_PARAM, NS_PER_SEC_INT, and SET_ERRNO.

Referenced by time_get_realtime_ns().

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 346 of file util/time.c.

                                {
  return lifecycle_is_initialized(&g_timer_manager.lifecycle);
}

References lifecycle_is_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 240 of file util/time.c.

                                   {
  if (!lifecycle_is_initialized(&g_timer_manager.lifecycle)) {
    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, lifecycle_is_initialized(), 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 291 of file util/time.c.

                                    {
  if (!lifecycle_is_initialized(&g_timer_manager.lifecycle)) {
    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_dev("Timer '%s' not found (may have already been stopped)", 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];
  time_pretty((uint64_t)elapsed_ns, -1, duration_str, sizeof(duration_str));
 
  // Log the result (dev level - only shown with --verbose)
  log_dev("Timer '%s': %s", name, duration_str);
 
  // Save pointers to free BEFORE removing from hashtable
  char *timer_name = timer->name;
 
  // Remove from hashtable (HASH_DEL only removes from hash, doesn't free memory)
  HASH_DEL(g_timer_manager.timers, timer);
 
  // Free timer->name first (this was allocated separately)
  SAFE_FREE(timer_name);
 
  // Nullify the timer->name field so debug_free doesn't try to access it
  // when freeing the timer structure itself
  timer->name = NULL;
 
  // Free the timer record itself
  SAFE_FREE(timer);
 
  rwlock_wrunlock(&g_timer_manager.rwlock);
  return elapsed_ns; // Return nanoseconds
}

References ERROR_INVALID_PARAM, ERROR_INVALID_STATE, lifecycle_is_initialized(), log_dev, timer_record::name, rwlock_wrlock, rwlock_wrunlock, SAFE_FREE, SET_ERRNO, timer_record::start_ticks, and time_pretty().

timer_system_destroy()

void timer_system_destroy

(

void

)

#include <time.h>

Cleanup the timing system.

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

Definition at line 213 of file util/time.c.

                                {
  if (!lifecycle_is_initialized(&g_timer_manager.lifecycle)) {
    return;
  }
 
  rwlock_wrlock(&g_timer_manager.rwlock);
 
  // Free all timer records
  int timer_count = 0;
  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);
    timer_count++;
  }
 
  g_timer_manager.timers = NULL;
 
  rwlock_wrunlock(&g_timer_manager.rwlock);
 
  /* Shutdown lifecycle and destroy rwlock together */
  lifecycle_shutdown(&g_timer_manager.lifecycle);
 
  log_debug("Timer system cleaned up (freed %d timers)", timer_count);
}

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

Referenced by asciichat_shared_destroy().

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 191 of file util/time.c.

                             {
  if (lifecycle_is_initialized(&g_timer_manager.lifecycle)) {
    return true;
  }
 
  // Initialize sokol_time
  stm_setup();
 
  // Initialize rwlock and lifecycle together
  g_timer_manager.lifecycle.sync_type = LIFECYCLE_SYNC_RWLOCK;
  g_timer_manager.lifecycle.sync.rwlock = &g_timer_manager.rwlock;
  if (!lifecycle_init(&g_timer_manager.lifecycle, "timer_manager")) {
    SET_ERRNO(ERROR_PLATFORM_INIT, "Failed to initialize timer system (already initialized by another thread)");
    return true; // Another thread already initialized it
  }
 
  g_timer_manager.timers = NULL;
 
  log_dev("Timer system initialized");
  return true;
}

References ERROR_PLATFORM_INIT, lifecycle_init(), lifecycle_is_initialized(), LIFECYCLE_SYNC_RWLOCK, log_dev, and SET_ERRNO.

Referenced by asciichat_shared_init().