time.h

Go to the documentation of this file.

#pragma once
#include <ascii-chat/asciichat_errno.h>
 
#include <ascii-chat/asciichat_errno.h>

 
/* Storage capacities in elements; text buffers include the terminating NUL. */
#define TIME_DURATION_BUFFER_SIZE 32
 
/* Storage capacities in elements; text buffers include the terminating NUL. */
#define UTIL_TIME_TIMER_NAME_BUFFER_SIZE 256
#define UTIL_TIME_TIMER_NAME_WITH_TID_BUFFER_SIZE 280
 
#include <stdint.h>
#include <stdbool.h>
#include <time.h>
#include <libplatform/time.h>
// C11 stdatomic.h conflicts with MSVC's C++ <atomic> header on Windows.
// Include the appropriate header based on the compilation mode.
#if defined(__cplusplus) && defined(_WIN32)
#include <atomic>
using std::atomic_compare_exchange_weak_explicit;
using std::atomic_load_explicit;
using std::memory_order_relaxed;
// C11 _Atomic(T) syntax doesn't work in C++ - use std::atomic<T> instead
#define TIME_ATOMIC_UINT64 std::atomic<uint64_t>
#define TIME_ATOMIC_UINT64_INIT(val) {val}
#else
#include <libplatform/atomic.h>
// Use atomic_t for rate-limiting counters
#define TIME_ATOMIC_UINT64 atomic_t
#define TIME_ATOMIC_UINT64_INIT(val) {0}
#endif
 
// ============================================================================
// sokol_time.h Integration
// ============================================================================
 
// Include sokol_time.h declarations (WITHOUT implementation)
// SOKOL_TIME_IMPL is defined only in time.c to avoid duplicate symbols
#include <ascii-chat-deps/sokol/sokol_time.h>
 
// Include platform thread for thread ID in timer names
#include <libplatform/thread.h>
 
// Include uthash wrapper for UBSan-safe hash functions
// Headers can include this even before common.h is fully processed
#include <ascii-chat/uthash.h>
 
// ============================================================================
// Core Monotonic Timing API (Nanosecond Precision)
// ============================================================================



void time_sleep_ns(uint64_t ns);

uint64_t time_elapsed_ns(uint64_t start_ns, uint64_t end_ns);
 
// ============================================================================
// Time Unit Constants (moved before inline functions that use them)
// ============================================================================
 
// Floating-point versions (for time formatting and conversions)
#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) // Account for leap years
 
// Integer versions (for comparing uint64_t nanosecond values)
#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)
 
// Microsecond versions (for API compatibility)
#define US_PER_MS_INT 1000ULL
#define US_PER_SEC_INT 1000000ULL
 
// Millisecond versions (for API compatibility)
#define MS_PER_SEC_INT 1000ULL
 
// Standard time unit conversions (seconds-based)
#define SEC_PER_MIN 60ULL
#define SEC_PER_HOUR (SEC_PER_MIN * SEC_PER_MIN)
#define SEC_PER_DAY (24ULL * SEC_PER_HOUR)
 
// Minute/hour/day to nanoseconds conversions
#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)
 
// ============================================================================
// Inline Time Conversion Helpers
// ============================================================================

static inline uint64_t time_ns_to_us(uint64_t ns) {
  return ns / NS_PER_US_INT;
}

static inline uint64_t time_ns_to_ms(uint64_t ns) {
  return ns / NS_PER_MS_INT;
}

static inline double time_ns_to_s(uint64_t ns) {
  return (double)ns / 1e9;
}

static inline uint64_t time_us_to_ns(uint64_t us) {
  return us * NS_PER_US_INT;
}

static inline uint64_t time_ms_to_ns(uint64_t ms) {
  return ms * NS_PER_MS_INT;
}

static inline uint64_t time_s_to_ns(double s) {
  return (uint64_t)(s * 1e9);
}
 
// ============================================================================
// Timer Record Structure
// ============================================================================

typedef struct timer_record {
  char *name;           
  uint64_t start_ticks; 
  UT_hash_handle hh;    
} timer_record_t;
 
// ============================================================================
// Timer System API
// ============================================================================

bool timer_system_init(void);

void timer_system_destroy(void);

bool timer_start(const char *name);

double timer_stop(const char *name);

bool timer_is_initialized(void);
 
// ============================================================================
// Convenience Macros
// ============================================================================

#define START_TIMER(name_fmt, ...)                                                                                     \
  do {                                                                                                                 \
    if (timer_is_initialized()) {                                                                                      \
      char _timer_name_buf[UTIL_TIME_TIMER_NAME_BUFFER_SIZE];                                                          \
      char _timer_name_with_tid[UTIL_TIME_TIMER_NAME_WITH_TID_BUFFER_SIZE];                                            \
      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)thread_current_id());                                                               \
      (void)timer_start(_timer_name_with_tid);                                                                         \
    }                                                                                                                  \
  } while (0)

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

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

#define STOP_TIMER(name_fmt, ...)                                                                                      \
  ({                                                                                                                   \
    double _elapsed = -1.0;                                                                                            \
    if (timer_is_initialized()) {                                                                                      \
      char _timer_name_buf[UTIL_TIME_TIMER_NAME_BUFFER_SIZE];                                                          \
      char _timer_name_with_tid[UTIL_TIME_TIMER_NAME_WITH_TID_BUFFER_SIZE];                                            \
      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)thread_current_id());                                                               \
      _elapsed = timer_stop(_timer_name_with_tid);                                                                     \
    }                                                                                                                  \
    _elapsed;                                                                                                          \
  })
 
// ============================================================================
// Time Formatting API
// ============================================================================

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

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

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

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

int time_human_readable_now(char *buffer, size_t buffer_size);

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

#define STOP_TIMER_AND_LOG(log_level, threshold_ns, timer_name, msg_fmt, ...)                                          \
  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[TIME_DURATION_BUFFER_SIZE];                                                                   \
      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)

#define STOP_TIMER_AND_LOG_EVERY(log_level, interval_ns, threshold_ns, timer_name, msg_fmt, ...)                       \
  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[TIME_DURATION_BUFFER_SIZE];                                                               \
          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)
 
// ============================================================================
// Adaptive Sleep System
// ============================================================================

typedef struct {
  uint64_t baseline_sleep_ns;  
  double min_speed_multiplier; 
  double max_speed_multiplier; 
  double speedup_rate;         
  double slowdown_rate;        
} adaptive_sleep_config_t;

typedef struct {
  adaptive_sleep_config_t config;  
  double current_speed_multiplier; 
  uint64_t last_sleep_ns;          
} adaptive_sleep_state_t;

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

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

void adaptive_sleep_do(adaptive_sleep_state_t *state, size_t queue_depth, size_t target_depth);
 
/* ============================================================================
 * Time Format Validation and Formatting
 * ============================================================================ */

bool time_format_is_valid_strftime(const char *format_str);

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

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

 
/* ============================================================================
 * Conversion Functions
 * ============================================================================ */

uint64_t time_timespec_to_ns(const struct timespec *ts);