⚙️ Code shared throughout the library More...

Files
file	common.c
	🔧 Core utilities: memory management, safe macros, and cross-platform helpers

file	common.h
	⚙️ Common definitions, error codes, macros, and types shared throughout the application

file	fps.c
	⏱️ FPS tracking utility implementation

file	fps.h
	⏱️ FPS tracking utility for monitoring frame throughput across all threads

Data Structures
struct	fps_t
	FPS tracking state. More...

Macros
#define	ASCII_CHAT_APP_NAME "ascii-chat"
	Application name for key comments ("ascii-chat")

#define	PLATFORM_MAX_PATH_LENGTH 4096

#define	FATAL(code, ...) asciichat_fatal_with_context(code, __FILE__, __LINE__, __func__, ##__VA_ARGS__)
	Exit with error code and custom message, with stack trace in debug builds.

#define	ALLOC_MALLOC(size) malloc(size)
	Return the minimum of two values.

#define	ALLOC_CALLOC(count, size) calloc((count), (size))

#define	ALLOC_REALLOC(ptr, size) realloc((ptr), (size))

#define	ALLOC_FREE(ptr) free(ptr)

#define	ASCIICHAT_CHECK_AND_LOG(expr, ok_value, msg, ...)
	Check result and log error if operation failed.

Typedefs
typedef unsigned char	uint8_t

typedef unsigned short	uint16_t

typedef unsigned int	uint32_t

typedef unsigned long long	uint64_t

Functions
void	asciichat_fatal_with_context (asciichat_error_t code, const char file, int line, const char function, const char *format,...)
	Exit with error code and context (used by FATAL macro)

asciichat_error_t	asciichat_shared_init (const char *default_log_filename, bool is_client)
	Initialize common subsystems shared by client and server.

void	fps_init (fps_t tracker, int expected_fps, const char name)
	Initialize FPS tracker.

void	fps_init_with_interval (fps_t tracker, int expected_fps, const char name, uint64_t report_interval_us)
	Initialize FPS tracker with custom report interval.

void	fps_frame (fps_t tracker, const struct timespec current_time, const char *context)
	Track a frame and detect lag conditions.

Memory Debugging Macros
#define	SAFE_MALLOC(size, cast)

#define	SAFE_CALLOC(count, size, cast)

#define	SAFE_REALLOC(ptr, size, cast)

#define	TRACK_ALIGNED_ALLOC(ptr, size, file, line) ((void)0)

#define	SAFE_MALLOC_ALIGNED(size, alignment, cast)

#define	SAFE_MALLOC_SIMD(size, cast) SAFE_MALLOC_ALIGNED(size, 16, cast)

#define	SAFE_CALLOC_SIMD(count, size, cast)

#define	SAFE_FREE(ptr)

#define	SAFE_FCLOSE(fp)

#define	UNTRACKED_MALLOC(size, cast)

#define	UNTRACKED_FREE(ptr)

#define	SAFE_STRNCPY(dst, src, size) platform_strlcpy((dst), (src), (size))

#define	SAFE_STRDUP(dst, src)

#define	SAFE_GETENV(name) platform_getenv(name)

#define	SAFE_SSCANF(str, format, ...) sscanf(str, format, __VA_ARGS__)

#define	SAFE_STRERROR(errnum) platform_strerror(errnum)

#define	SAFE_MEMCPY(dest, dest_size, src, count) platform_memcpy((dest), (dest_size), (src), (count))

#define	SAFE_MEMSET(dest, dest_size, ch, count) platform_memset((dest), (dest_size), (ch), (count))

#define	SAFE_MEMMOVE(dest, dest_size, src, count) platform_memmove((dest), (dest_size), (src), (count))

#define	SAFE_STRCPY(dest, dest_size, src) platform_strcpy((dest), (dest_size), (src))

#define	read_u16_unaligned bytes_read_u16_unaligned

#define	read_u32_unaligned bytes_read_u32_unaligned

#define	write_u16_unaligned bytes_write_u16_unaligned

#define	write_u32_unaligned bytes_write_u32_unaligned

#define	safe_size_mul bytes_safe_size_mul

#define	SAFE_SNPRINTF(buffer, buffer_size, ...) (size_t)safe_snprintf((buffer), (buffer_size), __VA_ARGS__)

#define	SAFE_BUFFER_SIZE(buffer_size, offset) ((offset) < 0 \|\| (size_t)(offset) >= (buffer_size) ? 0 : (buffer_size) - (size_t)(offset))
	Safe buffer size calculation for snprintf.

#define	THREAD_CREATE_OR_RETURN(thread, func, arg)
	Create a thread or log error and return.

#define	MUTEX_INIT_OR_RETURN(m)
	Initialize a mutex or log error and return.

Detailed Description

⚙️ Code shared throughout the library

This header provides core functionality used throughout ascii-chat:

Error codes (via common/error_codes.h)
Protocol constants (via common/protocol_constants.h)
Application limits (via common/limits.h)
Buffer sizes (via common/buffer_sizes.h)
Memory allocation macros (with mimalloc support)
Thread and synchronization macros
Utility macros (MIN, MAX, ARRAY_SIZE)
Shutdown detection system
Shared initialization function

Note: This header should be included early in other headers as it provides fundamental types and macros that many other modules depend on.

Provides a reusable FPS tracking mechanism for monitoring real-time frame delivery rates across all client threads (data reception, webcam capture, audio capture, keepalive). Tracks frame intervals, detects lag conditions, and generates periodic FPS reports every 7-15 seconds.

USAGE:

fps_t tracker;
fps_init(&tracker, 60, "WEBCAM");  // 60 FPS expected
 
// In your frame processing loop
struct timespec now;
clock_gettime(CLOCK_MONOTONIC, &now);
fps_frame(&tracker, &now, "frame received");

FEATURES:

Automatic frame counting and interval measurement
Lag detection (when frames arrive late)
Periodic FPS report generation (configurable, default 10 seconds)
Configurable expected FPS and reporting interval
Thread-safe (caller must synchronize if needed)
Integrated across all major threads (data reception, webcam, audio, keepalive)

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

Date: December 2025

Version: 2.0 (Refactored with unified thread tracking)

Common Definitions

Core error handling, memory management, logging, and type definitions shared throughout the ascii-chat application.

Overview

The common module (lib/common.h, lib/common.c) provides fundamental infrastructure:

Comprehensive error handling with context tracking
Memory allocation with leak detection in debug builds
Rate-limited logging for high-frequency code paths
Platform-independent type definitions
Shared constants and macros

All application code should use these common definitions to ensure consistency, proper error handling, and debuggability.

Error Handling System

ascii-chat uses a comprehensive error system (lib/asciichat_errno.h) that provides:

Specific error codes for different failure modes
Contextual error messages with file/line/function information
System error integration (errno on POSIX, GetLastError on Windows)
Thread-local error state (thread-safe)
Stack traces in debug builds

Error Code Enumeration

typedef enum {
    // Standard codes (0-2) - Unix conventions
    ASCIICHAT_OK = 0,                   // Success
    ERROR_GENERAL = 1,                  // Unspecified error
    ERROR_USAGE = 2,                    // Invalid command line arguments
 
    // Initialization failures (3-19)
    ERROR_MEMORY = 3,                   // Memory allocation failed (OOM)
    ERROR_CONFIG = 4,                   // Configuration file or settings error
    ERROR_CRYPTO_INIT = 5,              // Cryptographic initialization failed
    ERROR_LOGGING_INIT = 6,             // Logging system initialization failed
    ERROR_PLATFORM_INIT = 7,            // Platform-specific initialization failed
 
    // Hardware/Device errors (20-39)
    ERROR_WEBCAM = 20,                  // Webcam initialization or capture failed
    ERROR_WEBCAM_IN_USE = 21,           // Webcam is in use by another application
    ERROR_WEBCAM_PERMISSION = 22,       // Webcam permission denied
    ERROR_AUDIO = 23,                   // Audio device initialization or I/O failed
    ERROR_AUDIO_IN_USE = 24,            // Audio device is in use
    ERROR_TERMINAL = 25,                // Terminal initialization failed
 
    // Network errors (40-59)
    ERROR_NETWORK = 40,                 // General network error
    ERROR_NETWORK_BIND = 41,            // Cannot bind to port (server)
    ERROR_NETWORK_CONNECT = 42,         // Cannot connect to server (client)
    ERROR_NETWORK_TIMEOUT = 43,         // Network operation timed out
    ERROR_NETWORK_PROTOCOL = 44,        // Protocol violation or incompatible version
    ERROR_NETWORK_SIZE = 45,            // Network packet size error
 
    // Security/Crypto errors (60-79)
    ERROR_CRYPTO = 60,                  // Cryptographic operation failed
    ERROR_CRYPTO_KEY = 61,              // Key loading, parsing, or generation failed
    ERROR_CRYPTO_AUTH = 62,             // Authentication failed
    ERROR_CRYPTO_HANDSHAKE = 63,        // Cryptographic handshake failed
    ERROR_CRYPTO_VERIFICATION = 64,     // Signature or key verification failed
 
    // Runtime errors (80-99)
    ERROR_THREAD = 80,                  // Thread creation or management failed
    ERROR_BUFFER = 81,                  // Buffer allocation or overflow
    ERROR_BUFFER_FULL = 82,             // Buffer full
    ERROR_BUFFER_OVERFLOW = 83,         // Buffer overflow
    ERROR_DISPLAY = 84,                 // Display rendering or output error
    ERROR_INVALID_STATE = 85,           // Invalid program state
    ERROR_INVALID_PARAM = 86,           // Invalid parameter
    ERROR_INVALID_FRAME = 87,           // Invalid frame data
    ERROR_RESOURCE_EXHAUSTED = 88,      // System resources exhausted
    ERROR_FORMAT = 89,                  // String formatting operation failed
    ERROR_STRING = 90,                  // String manipulation operation failed
 
    // Signal/Crash handlers (100-127)
    ERROR_SIGNAL_INTERRUPT = 100,       // Interrupted by signal (SIGINT, SIGTERM)
    ERROR_SIGNAL_CRASH = 101,           // Fatal signal (SIGSEGV, SIGABRT, etc.)
    ERROR_ASSERTION_FAILED = 102,       // Assertion or invariant violation
 
    // Compression errors (103-104)
    ERROR_COMPRESSION = 103,            // Compression operation failed
    ERROR_DECOMPRESSION = 104,          // Decompression operation failed
} asciichat_error_t;

Error Context

Each error includes rich contextual information:

typedef struct {
    asciichat_error_t code;     // Error code (asciichat_error_t enum value)
    const char *file;           // Source file where error occurred (NULL in release)
    int line;                   // Line number where error occurred (0 in release)
    const char *function;       // Function name where error occurred (NULL in release)
    char *context_message;      // Optional custom message (dynamically allocated)
    uint64_t timestamp;         // Timestamp when error occurred (microseconds)
    int system_errno;           // System errno value (if applicable, 0 otherwise)
    int wsa_error;              // Windows socket error code (if applicable)
    void *backtrace[32];        // Stack trace addresses (debug builds only)
    char **backtrace_symbols;   // Stack trace symbol strings (debug builds only)
    int stack_depth;            // Number of stack frames captured
    bool has_system_error;      // True if system_errno is valid
    bool has_wsa_error;         // True if wsa_error is valid
} asciichat_error_context_t;

Error Handling Macros

SET_ERRNO: Set error with custom message

asciichat_error_t open_file(const char *path) {
    if (!path) {
        return SET_ERRNO(ERROR_INVALID_PARAM, "File path is NULL");
    }
 
    int fd = open(path, O_RDONLY);
    if (fd < 0) {
        return SET_ERRNO_SYS(ERROR_NOT_FOUND, "Failed to open file: %s", path);
    }
 
    return ASCIICHAT_OK;
}

SET_ERRNO_SYS: Set error with system errno

asciichat_error_t create_socket(void) {
    socket_t sockfd = socket(AF_INET6, SOCK_STREAM, 0);
    if (sockfd == INVALID_SOCKET_VALUE) {
        return SET_ERRNO_SYS(ERROR_NETWORK_SOCKET,
                              "socket() failed (errno=%d)", errno);
    }
    return ASCIICHAT_OK;
}

HAS_ERRNO: Check if error occurred

asciichat_error_context_t err_ctx;
asciichat_error_t result = risky_operation();
if (HAS_ERRNO(&err_ctx)) {
    log_error("Operation failed: %s (code=%d, file=%s:%d)",
              err_ctx.context_message, err_ctx.error_code,
              err_ctx.file, err_ctx.line);
    return result;
}

PRINT_ERRNO_CONTEXT: Debug print error details

if (HAS_ERRNO(&err_ctx)) {
    PRINT_ERRNO_CONTEXT(&err_ctx);  // Only in debug builds
    // Output:
    // Error: ERROR_NETWORK_CONNECT (code=13)
    // Message: Failed to connect to server (Connection refused)
    // Location: src/client.c:245 in connect_to_server()
    // System errno: 111 (Connection refused)
    // Timestamp: 1234567890123456 µs
}

CLEAR_ERRNO: Clear error state

CLEAR_ERRNO(); // Resets thread-local error state

CLEAR_ERRNO

#define CLEAR_ERRNO()

Clear the current error state.

Definition asciichat_errno.h:259

GET_ERRNO: Get current error code

asciichat_error_t current_error = GET_ERRNO();
if (current_error != ASCIICHAT_OK) {
    // Handle error
}

Memory Management

Custom memory allocation macros with automatic leak detection in debug builds:

Memory Allocation Macros

SAFE_MALLOC: Allocate memory with leak tracking

// Syntax: SAFE_MALLOC(size, cast_type)
uint8_t *buffer = SAFE_MALLOC(1024, uint8_t*);
if (!buffer) {
    return SET_ERRNO(ERROR_MEMORY, "Failed to allocate 1024 bytes");
}
 
// In debug builds, records:
// - Allocation address
// - Size (1024 bytes)
// - File (src/client.c)
// - Line (123)
// - Thread ID

SAFE_CALLOC: Allocate zeroed memory

// Allocate array of 100 integers, initialized to 0
int *array = SAFE_CALLOC(100, sizeof(int), int*);
if (!array) {
    return ERROR_MEMORY;
}

SAFE_REALLOC: Reallocate memory

// Grow buffer from 1024 to 2048 bytes
uint8_t *new_buffer = SAFE_REALLOC(buffer, 2048, uint8_t*);
if (!new_buffer) {
    // Original buffer still valid
    SAFE_FREE(buffer);
    return ERROR_MEMORY;
}
buffer = new_buffer;

SAFE_FREE: Free memory and set to NULL

SAFE_FREE(buffer); // Frees and sets buffer = NULL

// In debug builds, removes from leak tracker

Debug Memory Tracking

When CMAKE_BUILD_TYPE=Debug and DEBUG_MEMORY is defined:

Leak Detection:

All SAFE_MALLOC/CALLOC/REALLOC calls are recorded
Each allocation stores: address, size, file, line, timestamp
On program exit, reports any allocations not freed
Example output:
Memory leak detected:

Address: 0x7f1234567890

Size: 1024 bytes

Allocated at: src/client.c:123 in process_frame()

Thread: 0x7f123456

Total leaked: 1024 bytes in 1 allocation

Allocation Logging:

#define DEBUG_MEMORY 1
 
// Every allocation is logged:
// [MEMORY] malloc(1024) = 0x7f1234567890 at src/client.c:123
// [MEMORY] free(0x7f1234567890) at src/client.c:456

Double-Free Detection:

Freeing already-freed memory triggers assertion
Prevents use-after-free bugs

Memory Reports:

void asciichat_common_print_memory_stats(void);
// Prints:
// Current allocations: 5 (total 4096 bytes)
// Peak allocations: 10 (total 8192 bytes)
// Total malloc calls: 100
// Total free calls: 95

Logging System

Multi-level logging with rate limiting for high-frequency code:

Log Levels

typedef enum {
    LOG_DEBUG = 0,   // Verbose debug information
    LOG_INFO = 1,    // Informational messages
    LOG_WARN = 2,    // Warnings (non-fatal issues)
    LOG_ERROR = 3,   // Errors (operation failed)
    LOG_FATAL = 4,   // Fatal errors (program will exit)
} log_level_t;

Control via environment:

export LOG_LEVEL=0  # DEBUG (all messages)
export LOG_LEVEL=1  # INFO and above
export LOG_LEVEL=2  # WARN and above
export LOG_LEVEL=3  # ERROR and above
export LOG_LEVEL=4  # FATAL only

Standard Logging Macros

log_debug("Frame captured: %dx%d", width, height);
log_info("Client connected from %s:%d", ip, port);
log_warn("Audio buffer underrun detected");
log_error("Failed to send packet: %s", strerror(errno));
log_fatal("Critical error, terminating");  // Exits program

Output format:

[2025-01-15 14:32:45.123] [DEBUG] Frame captured: 1920x1080
[2025-01-15 14:32:45.456] [INFO] Client connected from 192.168.1.100:12345
[2025-01-15 14:32:45.789] [WARN] Audio buffer underrun detected
[2025-01-15 14:32:46.012] [ERROR] Failed to send packet: Broken pipe
[2025-01-15 14:32:46.345] [FATAL] Critical error, terminating

Rate-Limited Logging

For high-frequency code paths (e.g., video/audio processing at 60+ FPS):

// Log at most once per second (1000000 µs)
log_debug_every(1000000, "Processing frame %d", frame_count);
 
// Log at most once per 5 seconds
log_info_every(5000000, "Client status: %d connected", num_clients);
 
// Log at most once per 10 seconds
log_warn_every(10000000, "High CPU usage: %.1f%%", cpu_usage);

Implementation:

Uses thread-local timestamp tracking
First call always logs
Subsequent calls within interval are suppressed
Different log sites have independent rate limiting

Example (video processing loop at 60 FPS):

while (running) {
    capture_frame();
 
    // Without rate limiting: 60 log messages per second
    // log_debug("Frame captured");
 
    // With rate limiting: 1 log message per second
    log_debug_every(1000000, "Frame captured (count=%d)", frame_count);
 
    frame_count++;
}

Logging Configuration

// Initialize logging system
asciichat_error_t log_init(const char *log_file, log_level_t level);
 
// Change log level at runtime
void log_set_level(log_level_t level);
 
// Enable/disable color output
void log_set_color(bool enable);
 
// Cleanup logging
void log_destroy(void);

Usage:

// Log to file and stderr
log_init("/tmp/ascii-chat.log", LOG_INFO);
 
// Later: increase verbosity
log_set_level(LOG_DEBUG);
 
// Cleanup
log_destroy();

Common Type Definitions

Fixed-width integers (platform-independent):

#include <stdint.h>
int8_t, uint8_t      // 8-bit signed/unsigned
int16_t, uint16_t    // 16-bit signed/unsigned
int32_t, uint32_t    // 32-bit signed/unsigned
int64_t, uint64_t    // 64-bit signed/unsigned
size_t               // Unsigned size type (32 or 64-bit)
ssize_t              // Signed size type

Boolean (C99 style):

#include <stdbool.h>

bool, true, false

stdbool.h

bool

#define bool

Definition stdbool.h:22

NULL pointer:

#define NULL ((void*)0)

Common Constants

// Buffer sizes
#define MAX_PACKET_SIZE 65536         // Maximum network packet payload
#define MAX_PATH_LEN 4096             // Maximum path length
#define MAX_CLIENTS 9                 // Maximum simultaneous clients
 
// Network
#define DEFAULT_PORT 27224            // Default server port
#define PACKET_MAGIC 0xDEADBEEF      // Packet header magic number
 
// Video
#define DEFAULT_WIDTH 80              // Default terminal width
#define DEFAULT_HEIGHT 24             // Default terminal height
#define DEFAULT_FPS 30                // Default framerate
 
// Audio
#define SAMPLE_RATE 48000             // Audio sample rate (Hz)
#define AUDIO_CHANNELS 1              // Mono audio
#define FRAMES_PER_BUFFER 512         // PortAudio buffer size

Usage Examples

Comprehensive Error Handling

asciichat_error_t initialize_system(const char *config_file) {
    asciichat_error_t err;
 
    // Load configuration
    options_t opts;
    err = config_load(&opts, config_file);
    if (err != ASCIICHAT_OK) {
        asciichat_error_context_t ctx;
        if (HAS_ERRNO(&ctx)) {
            log_error("Config load failed: %s", ctx.context_message);
            PRINT_ERRNO_CONTEXT(&ctx);
        }
        return err;
    }
 
    // Initialize crypto
    crypto_context_t crypto_ctx;
    err = crypto_init(&crypto_ctx);
    if (err != ASCIICHAT_OK) {
        options_destroy(&opts);
        return err;
    }
 
    // Initialize audio
    audio_context_t audio_ctx;
    err = audio_init(&audio_ctx);
    if (err != ASCIICHAT_OK) {
        crypto_destroy(&crypto_ctx);
        options_destroy(&opts);
        return err;
    }
 
    return ASCIICHAT_OK;
}

Memory Management with Leak Detection

void process_data(void) {
    // Allocate buffers
    uint8_t *buffer1 = SAFE_MALLOC(1024, uint8_t*);
    uint8_t *buffer2 = SAFE_CALLOC(512, sizeof(uint8_t), uint8_t*);
 
    if (!buffer1 || !buffer2) {
        log_error("Memory allocation failed");
        SAFE_FREE(buffer1);
        SAFE_FREE(buffer2);
        return;
    }
 
    // Process data...
 
    // Grow buffer if needed
    if (need_more_space) {
        uint8_t *new_buffer = SAFE_REALLOC(buffer1, 2048, uint8_t*);
        if (!new_buffer) {
            log_error("Reallocation failed");
            SAFE_FREE(buffer1);
            SAFE_FREE(buffer2);
            return;
        }
        buffer1 = new_buffer;
    }
 
    // Cleanup (SAFE_FREE sets pointers to NULL)
    SAFE_FREE(buffer1);
    SAFE_FREE(buffer2);
}
 
// At program exit (debug builds):
// If any SAFE_MALLOC'd memory wasn't freed, it's reported:
// Memory leak detected:
//   Address: 0x7f1234567890
//   Size: 1024 bytes
//   Allocated at: src/client.c:123

Rate-Limited Logging in Video Loop

void video_processing_loop(void) {
    uint64_t frame_count = 0;
    uint64_t dropped_frames = 0;
 
    while (running) {
        // Capture frame (60 FPS)
        uint8_t *frame_data;
        asciichat_error_t err = webcam_capture_frame(webcam, &frame_data, &frame_len);
 
        if (err != ASCIICHAT_OK) {
            dropped_frames++;
            // Log at most once per second to avoid spam
            log_warn_every(1000000, "Frame capture failed (dropped %lu frames)",
                            dropped_frames);
            continue;
        }
 
        // Process frame...
 
        frame_count++;
 
        // Log progress every 5 seconds
        log_info_every(5000000, "Processed %lu frames (%.1f FPS)",
                        frame_count, calculate_fps());
    }
}

See also: common.h; asciichat_errno.h; logging.h

Macro Definition Documentation

◆ ALLOC_CALLOC

#define ALLOC_CALLOC	(	count,
		size
	)	calloc((count), (size))

#include <common.h>

Definition at line 196 of file common.h.

◆ ALLOC_FREE

#define ALLOC_FREE ( ptr ) free(ptr)

#include <common.h>

Definition at line 198 of file common.h.

◆ ALLOC_MALLOC

#define ALLOC_MALLOC ( size ) malloc(size)

#include <common.h>

Return the minimum of two values.

Return the maximum of two values

Calculate the number of elements in an array

Definition at line 195 of file common.h.

◆ ALLOC_REALLOC

#define ALLOC_REALLOC	(	ptr,
		size
	)	realloc((ptr), (size))

#include <common.h>

Definition at line 197 of file common.h.

◆ ASCII_CHAT_APP_NAME

#define ASCII_CHAT_APP_NAME "ascii-chat"

#include <common.h>

Application name for key comments ("ascii-chat")

Definition at line 43 of file common.h.

◆ ASCIICHAT_CHECK_AND_LOG

#define ASCIICHAT_CHECK_AND_LOG	(	expr,
		ok_value,
		msg,
		...
	)

#include <common.h>

Value:

  do {                                                                                                                 \
    if ((expr) != (ok_value)) {                                                                                        \
      log_error(msg, ##__VA_ARGS__);                                                                                   \
      return (expr);                                                                                                   \
    }                                                                                                                  \
  } while (0)

Check result and log error if operation failed.

Consolidates the pattern:

operation_result_t result = operation();
if (result != OK) {
    log_error("Operation failed: %d", result);
    return result;
}

Usage:

ASCIICHAT_CHECK_AND_LOG(crypto_result = crypto_operation(args),
                        ASCIICHAT_OK, "Crypto operation failed: %d",
                        crypto_result);

Definition at line 529 of file common.h.

     {                                                                                                                 \
    if ((expr) != (ok_value)) {                                                                                        \
      log_error(msg, ##__VA_ARGS__);                                                                                   \
      return (expr);                                                                                                   \
    }                                                                                                                  \
  } while (0)

◆ FATAL

#define FATAL	(	code,
		...
	)	asciichat_fatal_with_context(code, __FILE__, __LINE__, __func__, ##__VA_ARGS__)

#include <common.h>

Exit with error code and custom message, with stack trace in debug builds.

Parameters

code	Error code (asciichat_error_t)
...	Custom message format string and arguments (printf-style)

Note: In debug builds, includes file, line, and function information. In release builds, file/line/function are omitted to reduce binary size.

Warning: This macro terminates the program. Use only for unrecoverable errors.

Example:: FATAL(ERROR_NETWORK_BIND, "Cannot bind to port %d", port_number);

Definition at line 151 of file common.h.

◆ MUTEX_INIT_OR_RETURN

#define MUTEX_INIT_OR_RETURN ( m )

#include <common.h>

Value:

  do {                                                                                                                 \
    if (mutex_init(&(m)) != 0) {                                                                                       \
      log_error("Failed to initialize mutex: %s", #m);                                                                 \
      return -1;                                                                                                       \
    }                                                                                                                  \
  } while (0)

Initialize a mutex or log error and return.

Parameters

m	Pointer to mutex_t variable

Handles common pattern: init mutex, log error if failed, then return -1. Example usage:

MUTEX_INIT_OR_RETURN(mutex); // Mutex initialized successfully, continue

Definition at line 462 of file common.h.

     {                                                                                                                 \
    if (mutex_init(&(m)) != 0) {                                                                                       \
      log_error("Failed to initialize mutex: %s", #m);                                                                 \
      return -1;                                                                                                       \
    }                                                                                                                  \
  } while (0)

◆ PLATFORM_MAX_PATH_LENGTH

#define PLATFORM_MAX_PATH_LENGTH 4096

#include <common.h>

Definition at line 91 of file common.h.

◆ read_u16_unaligned

#define read_u16_unaligned bytes_read_u16_unaligned

#include <common.h>

Definition at line 404 of file common.h.

◆ read_u32_unaligned

#define read_u32_unaligned bytes_read_u32_unaligned

#include <common.h>

Definition at line 405 of file common.h.

◆ SAFE_BUFFER_SIZE

#define SAFE_BUFFER_SIZE	(	buffer_size,
		offset
	)	((offset) < 0 \|\| (size_t)(offset) >= (buffer_size) ? 0 : (buffer_size) - (size_t)(offset))

#include <common.h>

Safe buffer size calculation for snprintf.

Casts offset to size_t to avoid sign conversion warnings when subtracting from buffer_size. Returns 0 if offset is negative or >= buffer_size (prevents underflow).

Definition at line 421 of file common.h.

422 : (buffer_size) - (size_t)(offset))

◆ SAFE_CALLOC

#define SAFE_CALLOC	(	count,
		size,
		cast
	)

#include <common.h>

Value:

  ({                                                                                                                   \
    cast _ptr = (cast)ALLOC_CALLOC((count), (size));                                                                   \
    if (!_ptr) {                                                                                                       \
      FATAL(ERROR_MEMORY, "Memory allocation failed: %zu elements x %zu bytes", (size_t)(count), (size_t)(size));      \
    }                                                                                                                  \
    _ptr;                                                                                                              \
  })

Definition at line 218 of file common.h.

   {                                                                                                                   \
    cast _ptr = (cast)ALLOC_CALLOC((count), (size));                                                                   \
    if (!_ptr) {                                                                                                       \
      FATAL(ERROR_MEMORY, "Memory allocation failed: %zu elements x %zu bytes", (size_t)(count), (size_t)(size));      \
    }                                                                                                                  \
    _ptr;                                                                                                              \
  })

◆ SAFE_CALLOC_SIMD

#define SAFE_CALLOC_SIMD	(	count,
		size,
		cast
	)

#include <common.h>

Value:

  ({                                                                                                                   \
    size_t total_size = (count) * (size);                                                                              \
    cast _ptr = SAFE_MALLOC_SIMD(total_size, cast);                                                                    \
    memset(_ptr, 0, total_size);                                                                                       \
    _ptr;                                                                                                              \
  })

Definition at line 311 of file common.h.

   {                                                                                                                   \
    size_t total_size = (count) * (size);                                                                              \
    cast _ptr = SAFE_MALLOC_SIMD(total_size, cast);                                                                    \
    memset(_ptr, 0, total_size);                                                                                       \
    _ptr;                                                                                                              \
  })

◆ SAFE_FCLOSE

#define SAFE_FCLOSE ( fp )

#include <common.h>

Value:

  do {                                                                                                                 \
    if ((fp) != NULL) {                                                                                                \
      fclose(fp);                                                                                                      \
      (fp) = NULL;                                                                                                     \
    }                                                                                                                  \
  } while (0)

Definition at line 330 of file common.h.

     {                                                                                                                 \
    if ((fp) != NULL) {                                                                                                \
      fclose(fp);                                                                                                      \
      (fp) = NULL;                                                                                                     \
    }                                                                                                                  \
  } while (0)

◆ SAFE_FREE

#define SAFE_FREE ( ptr )

#include <common.h>

Value:

  do {                                                                                                                 \
    if ((ptr) != NULL) {                                                                                               \
      ALLOC_FREE((void *)(ptr));                                                                                       \
      (ptr) = NULL;                                                                                                    \
    }                                                                                                                  \
  } while (0)

Definition at line 320 of file common.h.

     {                                                                                                                 \
    if ((ptr) != NULL) {                                                                                               \
      ALLOC_FREE((void *)(ptr));                                                                                       \
      (ptr) = NULL;                                                                                                    \
    }                                                                                                                  \
  } while (0)

◆ SAFE_GETENV

#define SAFE_GETENV ( name ) platform_getenv(name)

#include <common.h>

Definition at line 378 of file common.h.

◆ SAFE_MALLOC

#define SAFE_MALLOC	(	size,
		cast
	)

#include <common.h>

Value:

  ({                                                                                                                   \
    cast _ptr = (cast)ALLOC_MALLOC(size);                                                                              \
    if (!_ptr) {                                                                                                       \
      FATAL(ERROR_MEMORY, "Memory allocation failed: %zu bytes", (size_t)(size));                                      \
    }                                                                                                                  \
    _ptr;                                                                                                              \
  })

Definition at line 208 of file common.h.

   {                                                                                                                   \
    cast _ptr = (cast)ALLOC_MALLOC(size);                                                                              \
    if (!_ptr) {                                                                                                       \
      FATAL(ERROR_MEMORY, "Memory allocation failed: %zu bytes", (size_t)(size));                                      \
    }                                                                                                                  \
    _ptr;                                                                                                              \
  })

◆ SAFE_MALLOC_ALIGNED

#define SAFE_MALLOC_ALIGNED	(	size,
		alignment,
		cast
	)

#include <common.h>

Value:

  ({                                                                                                                   \
    size_t aligned_size = (((size) + (alignment) - 1) / (alignment)) * (alignment);                                    \
    cast _ptr = (cast)aligned_alloc((alignment), aligned_size);                                                        \
    if (!_ptr) {                                                                                                       \
      FATAL(ERROR_MEMORY, "Aligned memory allocation failed: %zu bytes, %zu alignment", aligned_size,                  \
            (size_t)(alignment));                                                                                      \
    }                                                                                                                  \
    TRACK_ALIGNED_ALLOC(_ptr, aligned_size, __FILE__, __LINE__);                                                       \
    _ptr;                                                                                                              \
  })

Definition at line 293 of file common.h.

   {                                                                                                                   \
    size_t aligned_size = (((size) + (alignment) - 1) / (alignment)) * (alignment);                                    \
    cast _ptr = (cast)aligned_alloc((alignment), aligned_size);                                                        \
    if (!_ptr) {                                                                                                       \
      FATAL(ERROR_MEMORY, "Aligned memory allocation failed: %zu bytes, %zu alignment", aligned_size,                  \
            (size_t)(alignment));                                                                                      \
    }                                                                                                                  \
    TRACK_ALIGNED_ALLOC(_ptr, aligned_size, __FILE__, __LINE__);                                                       \
    _ptr;                                                                                                              \
  })

◆ SAFE_MALLOC_SIMD

#define SAFE_MALLOC_SIMD	(	size,
		cast
	)	SAFE_MALLOC_ALIGNED(size, 16, cast)

#include <common.h>

Definition at line 308 of file common.h.

◆ SAFE_MEMCPY

#define SAFE_MEMCPY	(	dest,
		dest_size,
		src,
		count
	)	platform_memcpy((dest), (dest_size), (src), (count))

#include <common.h>

Definition at line 388 of file common.h.

◆ SAFE_MEMMOVE

#define SAFE_MEMMOVE	(	dest,
		dest_size,
		src,
		count
	)	platform_memmove((dest), (dest_size), (src), (count))

#include <common.h>

Definition at line 390 of file common.h.

◆ SAFE_MEMSET

#define SAFE_MEMSET	(	dest,
		dest_size,
		ch,
		count
	)	platform_memset((dest), (dest_size), (ch), (count))

#include <common.h>

Definition at line 389 of file common.h.

◆ SAFE_REALLOC

#define SAFE_REALLOC	(	ptr,
		size,
		cast
	)

#include <common.h>

Value:

  ({                                                                                                                   \
    void *tmp_ptr = ALLOC_REALLOC((ptr), (size));                                                                      \
    if (!tmp_ptr) {                                                                                                    \
      FATAL(ERROR_MEMORY, "Memory reallocation failed: %zu bytes", (size_t)(size));                                    \
    }                                                                                                                  \
    (cast)(tmp_ptr);                                                                                                   \
  })

Definition at line 228 of file common.h.

   {                                                                                                                   \
    void *tmp_ptr = ALLOC_REALLOC((ptr), (size));                                                                      \
    if (!tmp_ptr) {                                                                                                    \
      FATAL(ERROR_MEMORY, "Memory reallocation failed: %zu bytes", (size_t)(size));                                    \
    }                                                                                                                  \
    (cast)(tmp_ptr);                                                                                                   \
  })

◆ safe_size_mul

#define safe_size_mul bytes_safe_size_mul

#include <common.h>

Definition at line 408 of file common.h.

◆ SAFE_SNPRINTF

#define SAFE_SNPRINTF	(	buffer,
		buffer_size,
		...
	)	(size_t)safe_snprintf((buffer), (buffer_size), __VA_ARGS__)

#include <common.h>

Definition at line 412 of file common.h.

◆ SAFE_SSCANF

#define SAFE_SSCANF	(	str,
		format,
		...
	)	sscanf(str, format, __VA_ARGS__)

#include <common.h>

Definition at line 381 of file common.h.

◆ SAFE_STRCPY

#define SAFE_STRCPY	(	dest,
		dest_size,
		src
	)	platform_strcpy((dest), (dest_size), (src))

#include <common.h>

Definition at line 391 of file common.h.

◆ SAFE_STRDUP

#define SAFE_STRDUP	(	dst,
		src
	)

#include <common.h>

Value:

  do {                                                                                                                 \
    if (src) {                                                                                                         \
      size_t _len = strlen(src) + 1;                                                                                   \
      (dst) = SAFE_MALLOC(_len, char *);                                                                               \
      if (dst) {                                                                                                       \
        SAFE_MEMCPY((dst), _len, (src), _len);                                                                         \
      } else {                                                                                                         \
        SET_ERRNO(ERROR_MEMORY, "String duplication failed for: %s", (src));                                           \
      }                                                                                                                \
    } else {                                                                                                           \
      (dst) = NULL;                                                                                                    \
    }                                                                                                                  \
  } while (0)

Definition at line 362 of file common.h.

     {                                                                                                                 \
    if (src) {                                                                                                         \
      size_t _len = strlen(src) + 1;                                                                                   \
      (dst) = SAFE_MALLOC(_len, char *);                                                                               \
      if (dst) {                                                                                                       \
        SAFE_MEMCPY((dst), _len, (src), _len);                                                                         \
      } else {                                                                                                         \
        SET_ERRNO(ERROR_MEMORY, "String duplication failed for: %s", (src));                                           \
      }                                                                                                                \
    } else {                                                                                                           \
      (dst) = NULL;                                                                                                    \
    }                                                                                                                  \
  } while (0)

◆ SAFE_STRERROR

#define SAFE_STRERROR ( errnum ) platform_strerror(errnum)

#include <common.h>

Definition at line 385 of file common.h.

◆ SAFE_STRNCPY

#define SAFE_STRNCPY	(	dst,
		src,
		size
	)	platform_strlcpy((dst), (src), (size))

#include <common.h>

Definition at line 358 of file common.h.

◆ THREAD_CREATE_OR_RETURN

#define THREAD_CREATE_OR_RETURN	(	thread,
		func,
		arg
	)

#include <common.h>

Value:

  do {                                                                                                                 \
    if (asciichat_thread_create(&(thread), (func), (arg)) != 0) {                                                      \
      log_error("Failed to create thread: %s", #func);                                                                 \
      return -1;                                                                                                       \
    }                                                                                                                  \
  } while (0)

Create a thread or log error and return.

Parameters

thread	Pointer to thread_t variable
func	Thread function (should match void* ()(void) signature)
arg	Thread argument

Handles common pattern: create thread, log error if failed, then return -1. Example usage:

THREAD_CREATE_OR_RETURN(thread, thread_func, arg); // Thread created successfully, continue

Definition at line 442 of file common.h.

     {                                                                                                                 \
    if (asciichat_thread_create(&(thread), (func), (arg)) != 0) {                                                      \
      log_error("Failed to create thread: %s", #func);                                                                 \
      return -1;                                                                                                       \
    }                                                                                                                  \
  } while (0)

◆ TRACK_ALIGNED_ALLOC

#define TRACK_ALIGNED_ALLOC	(	ptr,
		size,
		file,
		line
	)	((void)0)

#include <common.h>

Definition at line 247 of file common.h.

◆ UNTRACKED_FREE

#define UNTRACKED_FREE ( ptr )

#include <common.h>

Value:

  do {                                                                                                                 \
    if ((ptr) != NULL) {                                                                                               \
      free((void *)(ptr));                                                                                             \
      (ptr) = NULL;                                                                                                    \
    }                                                                                                                  \
  } while (0)

Definition at line 349 of file common.h.

     {                                                                                                                 \
    if ((ptr) != NULL) {                                                                                               \
      free((void *)(ptr));                                                                                             \
      (ptr) = NULL;                                                                                                    \
    }                                                                                                                  \
  } while (0)

◆ UNTRACKED_MALLOC

#define UNTRACKED_MALLOC	(	size,
		cast
	)

#include <common.h>

Value:

  ({                                                                                                                   \
    cast _ptr = (cast)malloc(size);                                                                                    \
    if (!_ptr) {                                                                                                       \
      FATAL(ERROR_MEMORY, "Memory allocation failed: %zu bytes", (size_t)(size));                                      \
    }                                                                                                                  \
    _ptr;                                                                                                              \
  })

Definition at line 340 of file common.h.

   {                                                                                                                   \
    cast _ptr = (cast)malloc(size);                                                                                    \
    if (!_ptr) {                                                                                                       \
      FATAL(ERROR_MEMORY, "Memory allocation failed: %zu bytes", (size_t)(size));                                      \
    }                                                                                                                  \
    _ptr;                                                                                                              \
  })

◆ write_u16_unaligned

#define write_u16_unaligned bytes_write_u16_unaligned

#include <common.h>

Definition at line 406 of file common.h.

◆ write_u32_unaligned

#define write_u32_unaligned bytes_write_u32_unaligned

#include <common.h>

Definition at line 407 of file common.h.

Typedef Documentation

◆ uint16_t

typedef unsigned short uint16_t

#include <common.h>

Definition at line 57 of file common.h.

◆ uint32_t

typedef unsigned int uint32_t

#include <common.h>

Definition at line 58 of file common.h.

◆ uint64_t

typedef unsigned long long uint64_t

#include <common.h>

Definition at line 59 of file common.h.

◆ uint8_t

typedef unsigned char uint8_t

#include <common.h>

Definition at line 56 of file common.h.

Function Documentation

◆ asciichat_fatal_with_context()

void asciichat_fatal_with_context	(	asciichat_error_t	code,
		const char *	file,
		int	line,
		const char *	function,
		const char *	format,
			...
	)

#include <common.h>

Exit with error code and context (used by FATAL macro)

Parameters

code	Error code (asciichat_error_t)
file	Source file name (can be NULL)
line	Line number (0 if not provided)
function	Function name (can be NULL)
format	Format string (printf-style)
...	Format arguments

Low-level function used by FATAL() macro. Sets error context and exits the program with the specified error code. In debug builds, prints stack trace before exiting.

Note: This function never returns (terminates program).; In debug builds, prints full error context and stack trace.; Thread-safe: Uses thread-local storage.

Warning: This function terminates the program. Use FATAL() macro instead of calling this directly.

Definition at line 275 of file asciichat_errno.c.

                                                           {
  (void)file;
  (void)line;
  (void)function;
 
  // Print library error context if available
  asciichat_error_context_t err_ctx;
  if (HAS_ERRNO(&err_ctx)) {
    log_labeled("\nasciichat_errno: libary code error context", LOG_COLOR_ERROR, "");
    asciichat_print_error_context(&err_ctx);
  } else {
    log_plain("WARNING: No error context found (asciichat_errno_context.code=%d)", asciichat_errno_context.code);
  }
 
  safe_fprintf(stderr, "\n");
  log_labeled("FATAL ERROR", LOG_COLOR_FATAL, "exit code %d (%s)", (int)code, asciichat_error_string(code));
#ifndef NDEBUG
  const char *relative_file = extract_project_relative_path(file);
  log_plain("  Location: %s:%d in %s()", relative_file, line, function);
#endif
 
  if (format) {
    va_list args;
    va_start(args, format);
    char *formatted_message = format_message(format, args);
    log_plain("  Error message: %s", formatted_message);
    SAFE_FREE(formatted_message);
    va_end(args);
  }
 
#ifndef NDEBUG
  // Always print platform backtrace in debug/dev builds
  void *buffer[32];
  int size = platform_backtrace(buffer, 32);
  if (size > 0) {
    char **symbols = platform_backtrace_symbols(buffer, size);
    if (symbols) {
      platform_print_backtrace_symbols("\nFATAL BACKTRACE", symbols, size, 0, 0, skip_backtrace_frame);
      platform_backtrace_symbols_free(symbols);
    }
  }
#endif
 
  exit(code);
}

References asciichat_errno_context, asciichat_print_error_context(), asciichat_error_context_t::code, extract_project_relative_path(), format_message(), HAS_ERRNO, LOG_COLOR_ERROR, LOG_COLOR_FATAL, log_labeled(), log_plain, platform_backtrace(), platform_backtrace_symbols(), platform_backtrace_symbols_free(), platform_print_backtrace_symbols(), safe_fprintf(), and SAFE_FREE.

◆ asciichat_shared_init()

asciichat_error_t asciichat_shared_init	(	const char *	default_log_filename,
		bool	is_client
	)

#include <common.h>

Initialize common subsystems shared by client and server.

This function performs initialization that is common to both client and server modes:

Platform initialization (Winsock, etc.)
Logging setup with default filename
Palette configuration
Buffer pool initialization
Cleanup registration (errno, known_hosts, platform, buffer pool)
Mimalloc debug registration (if enabled)

Note: Memory debugging setup is handled separately by each mode due to different requirements (client has snapshot mode, server doesn't).

Parameters

default_log_filename	Default log filename (e.g., "client.log" or "server.log")
is_client	true for client mode (routes all logs to stderr), false for server mode

Returns: ASCIICHAT_OK on success, error code on failure

Definition at line 64 of file common.c.

                                                                                          {
  // Register memory debugging stats FIRST so it runs LAST at exit
  // (atexit callbacks run in LIFO order - last registered runs first)
  // This ensures all cleanup handlers run before the memory report is printed
#if defined(DEBUG_MEMORY) && !defined(USE_MIMALLOC_DEBUG) && !defined(NDEBUG)
  (void)atexit(debug_memory_report);
#elif defined(USE_MIMALLOC_DEBUG) && !defined(NDEBUG)
  (void)atexit(print_mimalloc_stats);
  UNUSED(print_mimalloc_stats);
#endif
 
  // Initialize platform-specific functionality (Winsock, etc)
  if (platform_init() != ASCIICHAT_OK) {
    FATAL(ERROR_PLATFORM_INIT, "Failed to initialize platform");
  }
  (void)atexit(platform_cleanup);
 
  // Apply quiet mode setting BEFORE log_init so initialization messages are suppressed
  if (GET_OPTION(quiet)) {
    log_set_terminal_output(false);
  }
 
  // Initialize logging with default filename
  // Client mode: route ALL logs to stderr to keep stdout clean for ASCII art output
  const options_t *opts = options_get();
  const char *log_file = opts && opts->log_file[0] != '\0' ? opts->log_file : default_log_filename;
  // Use log_level from parsed options (set by options_init)
  // Default levels (when no --log-level arg or LOG_LEVEL env var):
  //   Debug/Dev builds: LOG_DEBUG
  //   Release/RelWithDebInfo builds: LOG_INFO
  // Precedence: LOG_LEVEL env var > --log-level CLI arg > build type default
  // use_mmap=true: Lock-free mmap logging for performance and crash safety
  log_init(log_file, GET_OPTION(log_level), is_client, true /* use_mmap */);
 
  // Initialize palette based on command line options
  const char *custom_chars = opts && opts->palette_custom_set ? opts->palette_custom : NULL;
  if (apply_palette_config(GET_OPTION(palette_type), custom_chars) != 0) {
    FATAL(ERROR_CONFIG, "Failed to apply palette configuration");
  }
 
  // Initialize global shared buffer pool
  buffer_pool_init_global();
  (void)atexit(buffer_pool_cleanup_global);
 
  // Register errno cleanup
  (void)atexit(asciichat_errno_cleanup);
 
  // Register options state cleanup
  (void)atexit(options_state_shutdown);
 
  // Register known_hosts cleanup
  (void)atexit(known_hosts_cleanup);
 
  // Truncate log if it's already too large
  log_truncate_if_large();
 
  // Set quiet mode for memory debugging (registration done at function start)
#if defined(DEBUG_MEMORY) && !defined(USE_MIMALLOC_DEBUG) && !defined(NDEBUG)
  debug_memory_set_quiet_mode(GET_OPTION(quiet));
#endif
 
  return ASCIICHAT_OK;
}

References apply_palette_config(), asciichat_errno_cleanup(), ASCIICHAT_OK, buffer_pool_cleanup_global(), buffer_pool_init_global(), ERROR_CONFIG, ERROR_PLATFORM_INIT, FATAL, GET_OPTION, known_hosts_cleanup(), log_file, options_state::log_file, log_init(), log_set_terminal_output(), log_truncate_if_large(), options_get(), options_state_shutdown(), options_state::palette_custom, options_state::palette_custom_set, platform_cleanup(), platform_init(), and UNUSED.

Referenced by main(), and main().

◆ fps_frame()

void fps_frame	(	fps_t *	tracker,
		const struct timespec *	current_time,
		const char *	context
	)

#include <fps.h>

Track a frame and detect lag conditions.

Call this function when a frame is processed. Automatically detects when frames arrive late and generates periodic FPS reports every report_interval_us.

Parameters

tracker	FPS tracker state
current_time	Timestamp of this frame (CLOCK_MONOTONIC)
context	Optional context string for lag logging (e.g., "ASCII frame received")

Definition at line 57 of file fps.c.

                                                                                         {
  if (!tracker || !current_time) {
    return;
  }
 
  // Initialize on first frame
  if (tracker->last_fps_report.tv_sec == 0) {
    tracker->last_fps_report = *current_time;
    tracker->last_frame_time = *current_time;
  }
 
  tracker->frame_count++;
 
  // Calculate time since last frame
  uint64_t current_us = timespec_to_us(current_time);
  uint64_t last_frame_us = timespec_to_us(&tracker->last_frame_time);
  uint64_t frame_interval_us = current_us - last_frame_us;
  tracker->last_frame_time = *current_time;
 
  // Expected frame interval in microseconds
  uint64_t expected_interval_us = 1000000ULL / (uint64_t)tracker->expected_fps;
  uint64_t lag_threshold_us = expected_interval_us + (expected_interval_us / 2); // 50% over expected
 
  // Log error if frame arrived too late
  if (tracker->frame_count > 1 && frame_interval_us > lag_threshold_us) {
    const char *context_str = context ? context : "Frame";
    double late_ms = (double)(frame_interval_us - expected_interval_us) / 1000.0;
    double expected_ms = (double)expected_interval_us / 1000.0;
    double actual_ms = (double)frame_interval_us / 1000.0;
    double actual_fps = 1000000.0 / (double)frame_interval_us;
    log_lag_event(tracker->tracker_name, context_str, late_ms, expected_ms, actual_ms, actual_fps);
  }
 
  // Report FPS every report_interval_us (default 10 seconds)
  uint64_t report_us = timespec_to_us(&tracker->last_fps_report);
  uint64_t elapsed_us = current_us - report_us;
 
  if (elapsed_us >= tracker->report_interval_us) {
    double elapsed_seconds = (double)elapsed_us / 1000000.0;
    double actual_fps = (double)tracker->frame_count / elapsed_seconds;
    log_fps_report(tracker->tracker_name, actual_fps, tracker->frame_count, elapsed_seconds);
 
    // Reset counters for next interval
    tracker->frame_count = 0;
    tracker->last_fps_report = *current_time;
  }
}

References fps_t::expected_fps, fps_t::frame_count, fps_t::last_fps_report, fps_t::last_frame_time, fps_t::report_interval_us, and fps_t::tracker_name.

Referenced by __attribute__(), client_audio_render_thread(), and client_video_render_thread().

◆ fps_init()

void fps_init	(	fps_t *	tracker,
		int	expected_fps,
		const char *	name
	)

#include <fps.h>

Initialize FPS tracker.

Sets up the tracker with expected FPS and default reporting interval (10 seconds). Should be called once before using the tracker.

Parameters

tracker	Pointer to uninitialized fps_t (should be zero-initialized)
expected_fps	Expected frame rate in FPS (e.g., 60, 30, 20)
name	Display name for logging (e.g., "CLIENT", "WEBCAM", "AUDIO", "KEEPALIVE")

Definition at line 36 of file fps.c.

                                                                  {
  fps_init_with_interval(tracker, expected_fps, name, 10000000ULL); // 10 seconds default
}

References fps_init_with_interval().

Referenced by client_audio_render_thread(), and client_video_render_thread().

◆ fps_init_with_interval()

void fps_init_with_interval	(	fps_t *	tracker,
		int	expected_fps,
		const char *	name,
		uint64_t	report_interval_us
	)

#include <fps.h>

Initialize FPS tracker with custom report interval.

Sets up the tracker with expected FPS and custom reporting interval. Useful for different threads that may need different reporting frequencies.

Parameters

tracker	Pointer to uninitialized fps_t (should be zero-initialized)
expected_fps	Expected frame rate in FPS
name	Display name for logging
report_interval_us	Custom report interval in microseconds

Definition at line 40 of file fps.c.

                                                                                                             {
  if (!tracker) {
    return;
  }
 
  tracker->frame_count = 0;
  tracker->expected_fps = expected_fps > 0 ? expected_fps : 60;
  tracker->tracker_name = name ? name : "FPS";
  tracker->report_interval_us = report_interval_us;
 
  // Initialize timestamps to zero (will be set on first frame)
  tracker->last_fps_report.tv_sec = 0;
  tracker->last_fps_report.tv_nsec = 0;
  tracker->last_frame_time.tv_sec = 0;
  tracker->last_frame_time.tv_nsec = 0;
}

References fps_t::expected_fps, fps_t::frame_count, fps_t::last_fps_report, fps_t::last_frame_time, fps_t::report_interval_us, and fps_t::tracker_name.

Referenced by __attribute__(), and fps_init().

Files

Data Structures

Macros

Typedefs

Functions

Memory Debugging Macros

Detailed Description

USAGE:

FEATURES:

Common Definitions

Overview

Error Handling System

Error Code Enumeration

Error Context

Error Handling Macros

Memory Management

Memory Allocation Macros

Debug Memory Tracking

Logging System

Log Levels

Standard Logging Macros

Rate-Limited Logging

Logging Configuration

Common Type Definitions

Common Constants

Usage Examples

Comprehensive Error Handling

Memory Management with Leak Detection

Rate-Limited Logging in Video Loop

Macro Definition Documentation

◆ ALLOC_CALLOC

◆ ALLOC_FREE

◆ ALLOC_MALLOC

◆ ALLOC_REALLOC

◆ ASCII_CHAT_APP_NAME

◆ ASCIICHAT_CHECK_AND_LOG

◆ FATAL

◆ MUTEX_INIT_OR_RETURN

◆ PLATFORM_MAX_PATH_LENGTH

◆ read_u16_unaligned

◆ read_u32_unaligned

◆ SAFE_BUFFER_SIZE

◆ SAFE_CALLOC

◆ SAFE_CALLOC_SIMD

◆ SAFE_FCLOSE

◆ SAFE_FREE

◆ SAFE_GETENV

◆ SAFE_MALLOC

◆ SAFE_MALLOC_ALIGNED

◆ SAFE_MALLOC_SIMD

◆ SAFE_MEMCPY

◆ SAFE_MEMMOVE

◆ SAFE_MEMSET

◆ SAFE_REALLOC

◆ safe_size_mul

◆ SAFE_SNPRINTF

◆ SAFE_SSCANF

◆ SAFE_STRCPY

◆ SAFE_STRDUP

◆ SAFE_STRERROR

◆ SAFE_STRNCPY

◆ THREAD_CREATE_OR_RETURN

◆ TRACK_ALIGNED_ALLOC

◆ UNTRACKED_FREE

◆ UNTRACKED_MALLOC

◆ write_u16_unaligned

◆ write_u32_unaligned

Typedef Documentation

◆ uint16_t

◆ uint32_t

◆ uint64_t

◆ uint8_t

Function Documentation

◆ asciichat_fatal_with_context()

◆ asciichat_shared_init()

◆ fps_frame()

◆ fps_init()

◆ fps_init_with_interval()