Common Definitions

⚙️ Code shared throughout the library More...

Files
file	common.c
	🔧 Core utilities: memory management, safe macros, and cross-platform helpers
file	fps.c
	⏱️ FPS tracking utility implementation (nanosecond-precision)
file	common.h
	⚙️ Common definitions, error codes, macros, and types shared throughout the application
file	embedded_resources.h
	Embedded resource management for production builds.
file	fps.h
	⏱️ FPS tracking utility for monitoring frame throughput across all threads

Data Structures
struct	fps_t
	Counters and timestamps used to calculate and report frame rate. More...

Macros
#define	ASCII_CHAT_APP_NAME   "ascii-chat"
	Application name for key comments ("ascii-chat").
#define	PLATFORM_MAX_PATH_LENGTH   4096
#define	NONSTRING   /* nothing */
#define	FATAL(code, ...)
	Exit with error code and custom message, with stack trace in debug builds.
#define	MIN(a, b)
	Return the minimum of two values.
#define	MAX(a, b)
	Return the maximum of two values.
#define	ARRAY_SIZE(arr)
	Calculate the number of elements in an array.
#define	RUN_BURST_AND_THROTTLE(burst_ns, throttle_ns, code_block)
#define	ALLOC_MALLOC(size)
#define	ALLOC_CALLOC(count, size)
#define	ALLOC_REALLOC(ptr, size)
#define	ALLOC_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,...)
asciichat_error_t	asciichat_shared_init (const char *log_file, bool is_client, bool quiet_startup)
	Initialize common subsystems shared by client and server.
void	asciichat_shared_destroy (void)
	Clean up shared library subsystems.
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_ns)
	Initialize FPS tracker with custom report interval.
void	fps_frame_ns (fps_t *tracker, uint64_t current_time_ns, const char *context)
	Track a frame and detect lag conditions (nanosecond version - PRIMARY).

Variables
int	g_argc
	Global argc for early argument inspection (e.g., –color flag detection) Set by main() for access from lib/platform/terminal.c during early execution.
char **	g_argv
	Global argv for early argument inspection (e.g., –color flag detection) Set by main() for access from lib/platform/terminal.c during early execution.
bool	g_color_flag_passed
	Was –color explicitly passed in command-line arguments? Set by options_init() before RCU is initialized, used by terminal_should_color_output().
bool	g_color_flag_value
	Value of –color flag (true if –color was in argv) Set by options_init() before RCU is initialized, used by terminal_should_color_output().

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)
#define	SAFE_MALLOC_ALIGNED(size, alignment, cast)
#define	SAFE_MALLOC_SIMD(size, cast)
#define	SAFE_CALLOC_SIMD(count, size, cast)
#define	SAFE_FREE(ptr)
#define	SAFE_MALLOC_DEFER_FREE(name, size, cast)
#define	SAFE_CALLOC_DEFER_FREE(name, count, size, cast)
#define	SAFE_FCLOSE(fp)
#define	UNTRACKED_MALLOC(size, cast)
#define	UNTRACKED_FREE(ptr)
#define	SAFE_STRNCPY(dst, src, size)
#define	SAFE_STRDUP(dst, src)
#define	SAFE_GETENV(name)
#define	SAFE_SSCANF(str, format, ...)
#define	SAFE_STRERROR(errnum)
#define	SAFE_MEMCPY(dest, dest_size, src, count)
#define	SAFE_MEMSET(dest, dest_size, ch, count)
#define	SAFE_MEMMOVE(dest, dest_size, src, count)
#define	SAFE_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, ...)
#define	SAFE_BUFFER_SIZE(buffer_size, 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)

Macro Definition Documentation

ALLOC_CALLOC

#define ALLOC_CALLOC	(		count,
			size )

#include <include/ascii-chat/common.h>

Value:

calloc((count), (size))

Definition at line 254 of file common.h.

Referenced by buffer_domain_create().

ALLOC_FREE

#define ALLOC_FREE

(

ptr

)

#include <include/ascii-chat/common.h>

Value:

free(ptr)

Definition at line 256 of file common.h.

ALLOC_MALLOC

#define ALLOC_MALLOC

(

size

)

#include <include/ascii-chat/common.h>

Value:

malloc(size)

Definition at line 253 of file common.h.

Referenced by buffer_acquire().

ALLOC_REALLOC

#define ALLOC_REALLOC	(		ptr,
			size )

#include <include/ascii-chat/common.h>

Value:

realloc((ptr), (size))

Definition at line 255 of file common.h.

ARRAY_SIZE

#define ARRAY_SIZE

(

arr

)

#include <include/ascii-chat/common.h>

Value:

(sizeof(arr) / sizeof((arr)[0]))

Calculate the number of elements in an array.

Definition at line 180 of file common.h.

Referenced by asciichat_error_stats_print(), options_preset_unified(), and ui_error_popup_preserve().

ASCII_CHAT_APP_NAME

#define ASCII_CHAT_APP_NAME   "ascii-chat"

#include <include/ascii-chat/common.h>

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

Definition at line 47 of file common.h.

Referenced by add_known_host().

ASCIICHAT_CHECK_AND_LOG

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

#include <include/ascii-chat/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 644 of file common.h.

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

FATAL

#define FATAL	(		code,
			... )

#include <include/ascii-chat/common.h>

Value:

asciichat_fatal_with_context(code, __FILE__, __LINE__, __func__, ##__VA_ARGS__)

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 160 of file common.h.

Referenced by asciichat_fatal_with_context(), asciichat_shared_init(), debug_errno_cleanup_thread(), debug_stats_cleanup_thread(), main(), ob_reserve(), and server_main().

MAX

#define MAX	(		a,
			b )

#include <include/ascii-chat/common.h>

Value:

((a) > (b) ? (a) : (b))

Return the maximum of two values.

Definition at line 175 of file common.h.

Referenced by receive_packet_secure_with_timeout(), session_display_write_ascii_frame(), and ui_error_popup_preserve().

MIN

#define MIN	(		a,
			b )

#include <include/ascii-chat/common.h>

Value:

((a) < (b) ? (a) : (b))

Return the minimum of two values.

Definition at line 170 of file common.h.

Referenced by errno_notifications_snapshot(), network_server_create(), packet_decoder_feed(), session_display_write_ascii_frame(), ui_error_popup_preserve(), and ui_error_popup_render().

MUTEX_INIT_OR_RETURN

#define MUTEX_INIT_OR_RETURN

(

m

)

#include <include/ascii-chat/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 557 of file common.h.

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

NONSTRING

#define NONSTRING   /* nothing */

#include <include/ascii-chat/common.h>

Definition at line 102 of file common.h.

PLATFORM_MAX_PATH_LENGTH

#define PLATFORM_MAX_PATH_LENGTH   4096

#include <include/ascii-chat/common.h>

Definition at line 95 of file common.h.

Referenced by acds_identity_save(), audio_analysis_init(), audio_client_init(), client_audio_pipeline_create(), discovery_keys_clear_cache(), discovery_keys_load_cached(), discovery_keys_save_cached(), get_log_dir(), gpg_agent_connect(), gpg_sign_with_key(), gpg_verify_detached_ed25519(), gpg_verify_signature_with_binary(), mcp_download_finalize(), mcp_download_prune(), mcp_request_parse(), parse_gpg_keys_from_response(), path_validate_user_path(), query_init(), and render_file_create().

read_u16_unaligned

#define read_u16_unaligned   bytes_read_u16_unaligned

#include <include/ascii-chat/common.h>

Definition at line 499 of file common.h.

read_u32_unaligned

#define read_u32_unaligned   bytes_read_u32_unaligned

#include <include/ascii-chat/common.h>

Definition at line 500 of file common.h.

RUN_BURST_AND_THROTTLE

#define RUN_BURST_AND_THROTTLE	(		burst_ns,
			throttle_ns,
			code_block )

#include <include/ascii-chat/common.h>

Value:

  do {                                                                                                                 \
    static uint64_t burst_start = 0;                                                                                   \
    uint64_t now = time_get_ns();                                                                                      \
                                                                                                                       \
    /* First call or timer reset */                                                                                    \
    if (burst_start == 0) {                                                                                            \
      burst_start = now;                                                                                               \
      code_block;                                                                                                      \
    } else {                                                                                                           \
      uint64_t elapsed_ns = now - burst_start;                                                                         \
                                                                                                                       \
      if (elapsed_ns < (uint64_t)(burst_ns)) {                                                                         \
        /* Within burst window */                                                                                      \
        code_block;                                                                                                    \
      } else if (elapsed_ns >= (uint64_t)(throttle_ns)) {                                                              \
        /* Throttle period complete, reset and execute */                                                              \
        burst_start = now;                                                                                             \
        code_block;                                                                                                    \
      }                                                                                                                \
      /* else: in throttle period, do nothing */                                                                       \
    }                                                                                                                  \
  } while (0)

Definition at line 208 of file common.h.

#define RUN_BURST_AND_THROTTLE(burst_ns, throttle_ns, code_block)                                                      \
  do {                                                                                                                 \
    static uint64_t burst_start = 0;                                                                                   \
    uint64_t now = time_get_ns();                                                                                      \
                                                                                                                       \
    /* First call or timer reset */                                                                                    \
    if (burst_start == 0) {                                                                                            \
      burst_start = now;                                                                                               \
      code_block;                                                                                                      \
    } else {                                                                                                           \
      uint64_t elapsed_ns = now - burst_start;                                                                         \
                                                                                                                       \
      if (elapsed_ns < (uint64_t)(burst_ns)) {                                                                         \
        /* Within burst window */                                                                                      \
        code_block;                                                                                                    \
      } else if (elapsed_ns >= (uint64_t)(throttle_ns)) {                                                              \
        /* Throttle period complete, reset and execute */                                                              \
        burst_start = now;                                                                                             \
        code_block;                                                                                                    \
      }                                                                                                                \
      /* else: in throttle period, do nothing */                                                                       \
    }                                                                                                                  \
  } while (0)

SAFE_BUFFER_SIZE

#define SAFE_BUFFER_SIZE	(		buffer_size,
			offset )

#include <include/ascii-chat/common.h>

Value:

  ((offset) < 0 || (size_t)(offset) >= (buffer_size) ? 0 : (buffer_size) - (size_t)(offset))

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 516 of file common.h.

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

SAFE_CALLOC

#define SAFE_CALLOC	(		count,
			size,
			cast )

#include <include/ascii-chat/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 275 of file common.h.

#define SAFE_CALLOC(count, size, cast)                                                                                 \
  ({                                                                                                                   \
    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;                                                                                                              \
  })

Referenced by acip_async_tcp_transport_create(), acip_outbound_create(), acip_security_init_options(), acip_tcp_transport_create(), acip_websocket_runtime_create(), ascii_create_grid(), ascii_render(), ascii_stabilizer_prepare(), asciichat_instr_runtime_get(), audio_processor_create(), audio_recording_create_channels(), client_audio_pipeline_create(), client_connection_create(), crypto_session_create(), digital_rain_init(), discovery_session_create(), face_follow_image_process(), ffmpeg_encoder_create_scaled(), fps_counter_create(), h265_client_context_create(), h265_decoder_create(), h265_server_context_create(), http2_connection_create(), http2_connection_submit_response(), http_renderer_init(), http_renderer_process(), http_renderer_submit(), http_response_retain(), http_server_http3_create(), http_server_init(), levenshtein_n(), mcp_request_parse(), mcp_server_main(), mixer_add_source(), mutex_stack_get_all_threads(), nat_upnp_open_protocol(), network_server_create(), options_get_enum_entries(), options_json_parse_value(), peer_crypto_create(), platform_event_listen(), platform_event_loop_create(), platform_event_loop_work(), platform_event_stream_work(), quic_connection_matches_cid(), quic_connection_submit_datagram(), quic_endpoint_open(), quic_udp_endpoint_create(), render_file_create(), render_progress_create(), render_progress_frame(), ringbuffer_create(), session_audio_create(), session_av_state_create(), session_capture_create(), session_consensus_create(), session_display_create(), session_host_create(), session_log_buffer_create(), session_network_capture_create(), session_participant_create(), session_pipeline_create(), simple_frame_swap_create(), spectral_create(), stats_runtime_peer_open(), stats_sampler_create(), stats_scope_create(), term_renderer_create(), terminal_fd_reader_create(), terminal_fd_writer_create(), test_pattern_create(), ui_password_prompt_present(), ui_session_create(), video_encoder_create(), webrtc_create_datachannel(), and webrtc_create_peer_connection().

SAFE_CALLOC_DEFER_FREE

#define SAFE_CALLOC_DEFER_FREE	(		name,
			count,
			size,
			cast )

#include <include/ascii-chat/common.h>

Value:

  cast name = SAFE_CALLOC(count, size, cast);                                                                          \
  defer(SAFE_FREE(name))

Definition at line 389 of file common.h.

#define SAFE_CALLOC_DEFER_FREE(name, count, size, cast)                                                                \
  cast name = SAFE_CALLOC(count, size, cast);                                                                          \
  defer(SAFE_FREE(name))

Referenced by framebuffer_create(), framebuffer_create_multi(), levenshtein(), packet_queue_create_config(), video_frame_buffer_create(), and webrtc_create_peer_connection().

SAFE_CALLOC_SIMD

#define SAFE_CALLOC_SIMD	(		count,
			size,
			cast )

#include <include/ascii-chat/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 368 of file common.h.

#define SAFE_CALLOC_SIMD(count, size, cast)                                                                            \
  ({                                                                                                                   \
    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 <include/ascii-chat/common.h>

Value:

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

Definition at line 395 of file common.h.

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

Referenced by add_known_host(), check_known_host_no_identity(), check_known_host_with_key(), config_create_default(), parse_keys_from_file(), parse_public_key(), remove_known_host(), and update_check_load_cache().

SAFE_FREE

#define SAFE_FREE

(

ptr

)

#include <include/ascii-chat/common.h>

Value:

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

Definition at line 377 of file common.h.

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

Referenced by acds_identity_default_path(), acds_server_shutdown(), acds_strings_destroy(), acip_async_tcp_transport_create(), acip_outbound_create(), acip_outbound_destroy(), acip_render_settings_capabilities(), acip_security_cleanup(), acip_settings_request(), acip_settings_send(), acip_tcp_transport_create(), acip_transport_destroy(), acip_websocket_client_transport_create(), acip_websocket_runtime_create(), acip_websocket_runtime_destroy(), add_known_host(), ascii_convert(), ascii_convert_with_buffers_stabilized(), ascii_create_grid(), ascii_render(), ascii_stabilizer_prepare(), ascii_stabilizer_reset(), ascii_write(), asciichat_instr_runtime_destroy(), asciichat_instr_runtime_get(), asciichat_mdns_destroy(), asciichat_mdns_init(), audio_destroy(), audio_free_device_list(), audio_init(), audio_processor_create(), audio_processor_destroy(), audio_recording_destroy(), audio_visualization_render_fft(), audio_visualization_render_waveform(), buffer_domain_create(), check_known_host_no_identity(), check_known_host_with_key(), client_audio_pipeline_create(), client_audio_pipeline_destroy(), client_audio_render_thread(), client_connection_destroy(), client_settings_receive(), client_settings_values(), client_video_render_thread(), colorscheme_cleanup_compiled(), completions_collect_all_modes_unique(), completions_generate_fish(), completions_generate_powershell(), completions_generate_zsh(), config_create_default(), config_load_and_apply(), config_schema_build_from_configs(), config_schema_destroy(), consensus_coordinator_create(), consensus_coordinator_destroy(), consensus_election_choose_hosts(), consensus_metrics_collection_add(), consensus_metrics_collection_destroy(), consensus_state_destroy(), consensus_topology_create(), consensus_topology_destroy(), create_mixed_ascii_frame_for_client(), crypto_handshake_server_start(), crypto_regex_match_known_hosts(), crypto_regex_match_public_key(), crypto_session_create(), crypto_session_destroy(), detect_client_utf8_support(), detect_default_ssh_key(), digital_rain_destroy(), digital_rain_init(), digital_rain_render_at(), discover_session_parallel(), discovery_keys_get_cache_path(), discovery_mdns_destroy(), discovery_session_create(), discovery_session_destroy(), display_height(), display_width(), ducking_destroy(), ducking_init(), face_follow_image_destroy(), fetch_github_gpg_keys(), fetch_github_ssh_keys(), fetch_gitlab_gpg_keys(), fetch_gitlab_ssh_keys(), ffmpeg_decoder_create_stdin(), ffmpeg_decoder_create_with_request_options(), ffmpeg_decoder_destroy(), ffmpeg_encoder_create_scaled(), format_message(), fps_counter_destroy(), frame_buffer_append(), frame_buffer_create(), frame_buffer_destroy(), frame_buffer_flush(), frame_buffer_printf(), framebuffer_destroy(), get_discovery_database_dir(), get_known_hosts_path(), get_log_dir(), gpg_get_public_key(), gpg_homedir_destroy(), grep_destroy(), grep_init(), grep_restore_patterns(), grep_save_patterns(), grep_should_output(), h265_client_context_create(), h265_client_context_destroy(), h265_client_init_media_source(), h265_decoder_destroy(), h265_encoder_destroy(), h265_server_context_destroy(), handle_audio_batch_packet(), handle_audio_opus_batch_packet(), handle_audio_packet(), handle_image_frame_h265_packet(), handle_image_frame_packet(), http2_connection_create(), http2_connection_destroy(), http2_connection_submit_response(), http_render_result_destroy(), http_renderer_destroy(), http_renderer_init(), http_renderer_process(), http_renderer_process_result_destroy(), http_renderer_reap(), http_renderer_submit(), http_response_finish(), http_response_release(), http_response_retain(), http_server_destroy(), http_server_dispatch_http3(), http_server_http3_destroy(), http_server_init(), https_get(), initial_options(), keyboard_help_toggle_terminal(), known_hosts_destroy(), layout_print_two_column_row(), levenshtein_n(), log_mmap_write(), log_net_message(), log_search_filter_buffer(), manpage_content_free_environment(), manpage_content_free_examples(), manpage_content_free_options(), manpage_content_free_positional(), manpage_content_free_usage(), manpage_content_generate_environment_with_manual(), manpage_content_generate_examples(), manpage_content_generate_options(), manpage_merger_free_content(), manpage_parser_free_sections(), manpage_resources_destroy(), mcp_request_destroy(), mcp_server_main(), mcp_stdio_run(), media_source_create_interruptible(), media_source_destroy(), memory_backend_create(), mirror_convert_frame(), mirror_free_string(), mirror_render_audio_visualization(), mixer_add_source(), mixer_create_channels(), mixer_destroy(), mixer_remove_source(), mutex_stack_free_all_threads(), mutex_stack_get_all_threads(), nat_upnp_close(), nat_upnp_open_protocol(), network_server_create(), network_server_destroy(), openpgp_base64_decode(), openpgp_parse_armored_pubkey(), openpgp_parse_armored_seckey(), options_apply_patch(), options_init(), options_json_parse_value(), options_state_destroy(), opus_codec_create_decoder_channels(), opus_codec_create_encoder_channels(), opus_codec_destroy(), packet_queue_destroy(), packet_send_error(), packet_send_remote_log(), parse_gpg_key_binary(), parse_gpg_keys_from_response(), parse_keys_from_file(), parse_log_file(), parse_private_key(), parse_public_key(), parse_public_keys(), parse_ssh_ed25519_line(), parse_ssh_keys_from_response(), parse_ssh_private_key(), path_validate_user_path(), peer_crypto_destroy(), peer_crypto_output_pop(), platform_event_listen(), platform_event_loop_create(), platform_event_loop_destroy(), platform_event_loop_work(), platform_event_stream_close(), platform_event_stream_work(), platform_event_stream_write(), quic_connection_destroy(), quic_connection_matches_cid(), quic_endpoint_destroy(), quic_endpoint_open(), quic_release(), quic_tls_destroy(), quic_transport_destroy_unclaimed_on_lane(), quic_udp_connect(), quic_udp_endpoint_create(), quic_udp_endpoint_destroy(), quic_udp_remove(), quic_worker_stop(), read_password_from_stdin(), remove_known_host(), render_file_create(), render_file_destroy(), render_progress_create(), render_progress_destroy(), render_progress_frame(), ringbuffer_destroy(), sdp_session_destroy(), session_audio_create(), session_audio_destroy(), session_av_state_destroy(), session_capture_create(), session_capture_destroy(), session_consensus_create(), session_consensus_destroy(), session_display_destroy(), session_display_encode_frame(), session_display_release_ascii(), session_display_render_frame(), session_display_write_ascii_frame(), session_entry_destroy(), session_host_create(), session_host_destroy(), session_log_buffer_destroy(), session_network_capture_create(), session_participant_create(), session_participant_destroy(), session_participant_receive_settings(), session_participant_request_settings(), session_pipeline_create(), session_pipeline_destroy(), session_protocol_dispatch(), session_settings_from_options(), simd_caches_destroy_all(), simple_frame_swap_destroy(), spectral_destroy(), ssh_agent_sign(), stats_runtime_peer_close(), stats_runtime_peer_open(), stats_sampler_create(), stats_sampler_destroy(), stats_scope_create(), stats_scope_destroy(), term_renderer_create(), term_renderer_destroy(), term_renderer_feed(), terminal_fd_reader_destroy(), terminal_fd_reader_next(), terminal_fd_writer_destroy(), terminal_screen_compose(), terminal_screen_render(), test_pattern_destroy(), test_pattern_resize(), thread_pool_create(), thread_pool_create_with_workers(), thread_pool_destroy(), thread_pool_spawn(), thread_pool_stop_all(), timer_start(), timer_stop(), timer_system_destroy(), ui_notice_present(), ui_notice_present_first_use(), ui_password_prompt_present(), ui_prompt_present_kind(), ui_session_destroy(), ui_session_help_free(), update_check_load_cache(), update_check_perform(), update_check_save_cache(), url_parse(), url_parts_destroy(), utf8_palette_create(), utf8_palette_destroy(), validate_options_and_report(), validate_ssh_key_file(), video_frame_buffer_destroy(), wav_writer_close(), wav_writer_open(), webrtc_close_peer_connection(), webrtc_create_peer_connection(), webrtc_datachannel_destroy(), webrtc_peer_connection_destroy(), webrtc_peer_manager_create(), webrtc_peer_manager_destroy(), webrtc_peer_manager_handle_sdp(), and zalgo_apply().

SAFE_GETENV

#define SAFE_GETENV

(

name

)

#include <include/ascii-chat/common.h>

Value:

platform_getenv(name)

Definition at line 449 of file common.h.

Referenced by ascii_otel_init(), asciichat_instr_log_line(), asciichat_instr_runtime_get(), client_connection_checkpoint(), detect_client_utf8_support(), detect_terminal_background(), env_has_prompt_response(), env_pop_prompt_response(), env_validate_prompt_response_format(), log_init(), render_file_create(), sdp_detect_terminal_capabilities(), session_client_like_run(), test_get_binary_path(), update_banner_install_update(), update_check_perform(), and wav_dump_enabled().

SAFE_MALLOC

#define SAFE_MALLOC	(		size,
			cast )

#include <include/ascii-chat/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 265 of file common.h.

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

Referenced by acip_render_settings_capabilities(), acip_settings_request(), acip_tcp_transport_create(), add_known_host(), ansi_strip_escapes(), ascii_create_grid(), ascii_pad_frame_height(), ascii_pad_frame_width(), ascii_write(), asciichat_mdns_init(), asciichat_pcre2_extract_group(), asciichat_pcre2_extract_named_group(), audio_init(), audio_visualization_render_fft(), audio_visualization_render_waveform(), client_audio_render_thread(), client_settings_receive(), client_settings_values(), colorscheme_compile_scheme(), config_create_default(), config_load_and_apply(), config_schema_build_from_configs(), consensus_coordinator_create(), consensus_election_choose_hosts(), consensus_metrics_collection_add(), consensus_metrics_collection_create(), consensus_state_create(), consensus_topology_create(), crypto_handshake_server_start(), digital_rain_render_at(), discover_session_parallel(), discovery_mdns_query(), ducking_init(), expand_path(), ffmpeg_decoder_create_stdin(), ffmpeg_decoder_create_with_request_options(), format_message(), frame_buffer_append(), frame_buffer_create(), frame_buffer_flush(), frame_buffer_printf(), get_known_hosts_path(), get_log_dir(), get_modes_by_group(), get_utf8_palette_cache(), grep_highlight_colored_copy(), grep_init(), grep_should_output(), h265_client_context_create(), h265_client_init_media_source(), handle_audio_batch_packet(), handle_audio_opus_batch_packet(), handle_audio_packet(), handle_image_frame_h265_packet(), http2_connection_submit_response(), http_render_result_add_text_frame(), http_renderer_process(), http_renderer_render_file(), http_response_finish(), http_response_retain(), initial_options(), log_search_filter_buffer(), manpage_content_generate_environment(), manpage_content_generate_environment_with_manual(), manpage_content_generate_examples(), manpage_content_generate_options(), manpage_content_generate_positional(), manpage_content_generate_usage(), manpage_merger_generate_synopsis(), manpage_merger_generate_usage(), manpage_merger_merge_environment(), manpage_merger_merge_options(), manpage_merger_merge_positional(), mcp_stdio_run(), media_source_create_interruptible(), memory_backend_create(), mirror_convert_frame(), mixer_add_source(), mixer_create_channels(), mutex_stack_get_all_threads(), openpgp_base64_decode(), options_apply_patch(), options_get_enum_values(), options_registry_get_binary_options(), options_registry_get_for_display(), options_registry_get_for_mode(), options_state_init(), options_state_set(), opus_codec_create_decoder_channels(), opus_codec_create_encoder_channels(), packet_send_error(), packet_send_remote_log(), parse_gpg_key_binary(), parse_gpg_keys_from_response(), parse_public_keys(), parse_ssh_keys_from_response(), path_validate_user_path(), platform_event_stream_write(), rainbow_render_ansi_at(), read_password_from_stdin(), render_file_create(), sdp_generate_answer(), sdp_generate_offer(), sdp_parse(), session_capture_create(), session_display_write_ascii_frame(), session_network_capture_create(), session_participant_receive_settings(), session_participant_request_settings(), session_protocol_dispatch(), session_settings_from_options(), simple_frame_swap_create(), ssh_agent_sign(), term_renderer_create(), term_renderer_feed(), terminal_fd_reader_create(), terminal_fd_reader_next(), terminal_screen_compose(), terminal_screen_render(), test_pattern_rgba(), thread_pool_create(), thread_pool_create_with_workers(), thread_pool_queue_work(), thread_pool_spawn(), timer_start(), ui_notice_present(), ui_notice_present_first_use(), ui_prompt_present_kind(), ui_session_context_help_render(), ui_session_help_render(), utf8_palette_create(), video_encoder_create(), visualization_encode(), wav_writer_open(), webrtc_create_peer_connection(), webrtc_peer_manager_create(), webrtc_peer_manager_handle_sdp(), and zalgo_apply().

SAFE_MALLOC_ALIGNED

#define SAFE_MALLOC_ALIGNED	(		size,
			alignment,
			cast )

#include <include/ascii-chat/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 350 of file common.h.

#define SAFE_MALLOC_ALIGNED(size, alignment, cast)                                                                     \
  ({                                                                                                                   \
    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_DEFER_FREE

#define SAFE_MALLOC_DEFER_FREE	(		name,
			size,
			cast )

#include <include/ascii-chat/common.h>

Value:

  cast name = SAFE_MALLOC(size, cast);                                                                                 \
  defer(SAFE_FREE(name))

Definition at line 386 of file common.h.

#define SAFE_MALLOC_DEFER_FREE(name, size, cast)                                                                       \
  cast name = SAFE_MALLOC(size, cast);                                                                                 \
  defer(SAFE_FREE(name))

Referenced by crypto_handshake_client_key_exchange(), crypto_handshake_server_auth_challenge(), gpg_homedir_create(), https_get(), levenshtein(), openpgp_base64_decode(), parse_keys_from_file(), parse_private_key(), parse_public_key(), session_protocol_update_settings(), video_frame_buffer_create(), and zalgo_apply().

SAFE_MALLOC_SIMD

#define SAFE_MALLOC_SIMD	(		size,
			cast )

#include <include/ascii-chat/common.h>

Value:

SAFE_MALLOC_ALIGNED(size, 16, cast)

Definition at line 365 of file common.h.

SAFE_MEMCPY

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

#include <include/ascii-chat/common.h>

Value:

platform_memcpy((dest), (dest_size), (src), (count))

Definition at line 483 of file common.h.

Referenced by ansi_expand_rle(), ansi_rle_finish(), ascii_create_grid(), ascii_pad_frame_height(), ascii_pad_frame_width(), audio_ring_buffer_peek(), audio_ring_buffer_read(), audio_ring_buffer_write(), client_audio_render_thread(), crypto_create_auth_challenge(), crypto_create_encrypted_packet(), crypto_create_public_key_packet(), crypto_encrypt(), crypto_get_public_key(), crypto_process_auth_challenge(), crypto_process_auth_response(), crypto_process_encrypted_packet(), crypto_process_public_key_packet(), crypto_rekey_commit(), crypto_set_peer_public_key(), framebuffer_peek_latest_multi_frame(), framebuffer_write_frame(), framebuffer_write_multi_frame(), http_render_result_add_text_frame(), http_renderer_render_file(), initialize_client_palette(), ob_write(), ringbuffer_peek(), ringbuffer_read(), ringbuffer_write(), simple_frame_swap_update(), and utf8_palette_create().

SAFE_MEMMOVE

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

#include <include/ascii-chat/common.h>

Value:

platform_memmove((dest), (dest_size), (src), (count))

Definition at line 485 of file common.h.

SAFE_MEMSET

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

#include <include/ascii-chat/common.h>

Value:

platform_memset((dest), (dest_size), (ch), (count))

Definition at line 484 of file common.h.

Referenced by ascii_pad_frame_width(), audio_analysis_init(), audio_init(), audio_ring_buffer_clear(), detect_client_utf8_support(), ducking_init(), framebuffer_clear(), image_clear(), mixer_create_channels(), mixer_process(), mixer_process_excluding_source(), resample_linear(), session_protocol_build_capabilities(), threaded_send_client_join_packet(), and utf8_palette_create().

SAFE_REALLOC

#define SAFE_REALLOC	(		ptr,
			size,
			cast )

#include <include/ascii-chat/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 285 of file common.h.

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

Referenced by completions_collect_all_modes_unique(), consensus_state_add_metrics(), grep_init(), http_response_write(), https_get(), manpage_content_generate_environment(), manpage_content_generate_environment_with_manual(), manpage_content_generate_examples(), manpage_content_generate_options(), manpage_content_generate_positional(), manpage_content_generate_usage(), manpage_merger_generate_usage(), ob_reserve(), remove_known_host(), and session_display_write_ascii_frame().

safe_size_mul

#define safe_size_mul   bytes_safe_size_mul

#include <include/ascii-chat/common.h>

Definition at line 503 of file common.h.

Referenced by handle_audio_batch_packet(), and packet_validate_frame_dimensions().

SAFE_SNPRINTF

#define SAFE_SNPRINTF	(		buffer,
			buffer_size,
			... )

#include <include/ascii-chat/common.h>

Value:

(size_t)safe_snprintf((buffer), (buffer_size), __VA_ARGS__)

Definition at line 507 of file common.h.

Referenced by ascii_otel_init(), client_crypto_init(), connection_endpoint_resolve(), crypto_get_status(), detect_default_ssh_key(), expand_ipv6(), format_available_modes(), format_ip_with_port(), http_renderer_process(), ipv4_to_ipv6_mapped(), mcp_download_finalize(), mcp_request_parse(), mcp_server_main(), options_json_parse_value(), parse_client_address(), parse_mirror_media(), parse_server_bind_address(), parse_volume(), rgb_to_ansi_bg(), rgb_to_ansi_fg(), session_connection_establish(), strip_equals_prefix(), thread_pool_create_with_workers(), thread_pool_spawn(), threaded_send_client_join_packet(), validate_opt_color_mode(), validate_opt_device_index(), validate_opt_float_non_negative(), validate_opt_ip_address(), validate_opt_log_level(), validate_opt_palette(), validate_opt_password(), validate_opt_port(), validate_opt_reconnect(), validate_opt_render_mode(), validate_opt_volume(), and webrtc_create_peer_connection().

SAFE_SSCANF

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

#include <include/ascii-chat/common.h>

Value:

sscanf(str, format, __VA_ARGS__)

Definition at line 455 of file common.h.

Referenced by parse_hex_color().

SAFE_STRCPY

#define SAFE_STRCPY	(		dest,
			dest_size,
			src )

#include <include/ascii-chat/common.h>

Value:

platform_strcpy((dest), (dest_size), (src))

Definition at line 486 of file common.h.

Referenced by h265_client_init_media_source(), log_named_format_or_original(), main(), mixer_add_source(), and video_frame_buffer_create().

SAFE_STRDUP

#define SAFE_STRDUP	(		dst,
			src )

#include <include/ascii-chat/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 433 of file common.h.

#define SAFE_STRDUP(dst, src)                                                                                          \
  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)

Referenced by detect_client_utf8_support(), and url_parse().

SAFE_STRERROR

#define SAFE_STRERROR

(

errnum

)

#include <include/ascii-chat/common.h>

Value:

platform_strerror(errnum)

Definition at line 480 of file common.h.

Referenced by acip_tcp_transport_create(), gpg_sign_with_key(), gpg_verify_signature_with_binary(), and packet_send().

SAFE_STRNCPY

#define SAFE_STRNCPY	(		dst,
			src,
			size )

#include <include/ascii-chat/common.h>

Value:

  do {                                                                                                               \
    size_t _safe_strncpy_size = (size);                                                                              \
    if (_safe_strncpy_size > 0) {                                                                                    \
      (void)platform_strncpy((dst), _safe_strncpy_size, (src), _safe_strncpy_size - 1);                              \
    }                                                                                                                \
  } while (0)

Definition at line 423 of file common.h.

#define SAFE_STRNCPY(dst, src, size)                                                                                  \
  do {                                                                                                               \
    size_t _safe_strncpy_size = (size);                                                                              \
    if (_safe_strncpy_size > 0) {                                                                                    \
      (void)platform_strncpy((dst), _safe_strncpy_size, (src), _safe_strncpy_size - 1);                              \
    }                                                                                                                \
  } while (0)

Referenced by acds_client_config_init_defaults(), acds_identity_save(), acds_protocol_create(), acds_protocol_enter(), acds_protocol_join(), acds_protocol_lookup(), acds_protocol_receive(), acds_session_create(), acds_session_join(), acip_render_settings_capabilities(), acip_render_settings_options(), acip_render_settings_prepare(), acip_security_init_options(), asciichat_instr_log_line(), asciichat_mdns_advertise(), asciichat_mdns_query(), build_github_gpg_url(), build_gitlab_gpg_url(), client_audio_render_thread(), client_configure_crypto_options(), client_crypto_init(), client_main(), client_set_server_address(), client_video_render_thread(), colorscheme_compile_scheme(), colorscheme_load_from_file(), config_create_default(), config_schema_build_from_configs(), connection_endpoint_resolve(), crypto_handshake_init_with_password(), database_session_join(), database_session_leave(), detect_client_utf8_support(), disconnect_client_for_bad_data(), discovery_config_init_defaults(), discovery_main(), discovery_session_create(), env_pop_prompt_response(), extract_gpg_key_comment(), extract_ip_from_address(), format_gpg_key_display(), format_ip_with_port(), get_utf8_palette_cache(), gpg_get_public_key(), grep_highlight_colored(), handle_client_join_packet(), http_render_result_add_file_frame(), http_renderer_process(), is_valid_ipv4(), is_valid_ipv6(), layout_print_wrapped_description(), log_init(), log_mmap_init(), log_recolor_plain_entry(), log_search_get_match_info(), log_search_init(), main(), mcp_dispatch(), mcp_request_parse(), mcp_server_main(), mirror_convert_frame(), nat_upnp_get_endpoint(), nat_upnp_open_protocol(), negotiate_determine_result(), network_connection_prepare_security(), options_collect_identity_keys(), options_json_parse_value(), options_t_new(), parse_address_with_optional_port(), parse_gpg_keys_from_response(), parse_ip_with_port(), parse_log_file(), parse_palette_chars(), parse_palette_chars_option(), path_validate_user_path(), render_file_create(), sdp_generate_answer(), sdp_parse(), send_error_packet_message(), server_connection_set_ip(), session_host_add_client(), session_host_add_memory_participant(), session_host_create(), session_host_find_client(), session_participant_connect(), session_participant_create(), session_protocol_build_capabilities(), session_settings_from_values(), session_settings_to_options(), splash_set_discovery_session(), splash_set_update_notification(), TerminalRendererBinding::TerminalRendererBinding(), thread_pool_create(), thread_pool_create_with_workers(), thread_pool_spawn(), time_pretty(), timer_start(), ui_session_loading(), ui_status_gather(), ui_status_render_header(), update_check_load_cache(), update_check_perform(), utf8_palette_create(), and webrtc_turn_servers_parse().

THREAD_CREATE_OR_RETURN

#define THREAD_CREATE_OR_RETURN	(		thread,
			func,
			arg )

#include <include/ascii-chat/common.h>

Value:

  do {                                                                                                                 \
    if (platform_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 537 of file common.h.

#define THREAD_CREATE_OR_RETURN(thread, func, arg)                                                                     \
  do {                                                                                                                 \
    if (platform_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 )

#include <include/ascii-chat/common.h>

Value:

((void)0)

Definition at line 304 of file common.h.

UNTRACKED_FREE

#define UNTRACKED_FREE

(

ptr

)

#include <include/ascii-chat/common.h>

Value:

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

Definition at line 414 of file common.h.

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

Referenced by debug_sync_check_cond_deadlocks(), named_registry_for_each(), named_update_name(), and ui_sync_stop().

UNTRACKED_MALLOC

#define UNTRACKED_MALLOC	(		size,
			cast )

#include <include/ascii-chat/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 405 of file common.h.

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

Referenced by debug_sync_check_cond_deadlocks(), and named_registry_for_each().

write_u16_unaligned

#define write_u16_unaligned   bytes_write_u16_unaligned

#include <include/ascii-chat/common.h>

Definition at line 501 of file common.h.

write_u32_unaligned

#define write_u32_unaligned   bytes_write_u32_unaligned

#include <include/ascii-chat/common.h>

Definition at line 502 of file common.h.

Typedef Documentation

uint16_t

typedef unsigned short uint16_t

#include <include/ascii-chat/common.h>

Definition at line 61 of file common.h.

uint32_t

typedef unsigned int uint32_t

#include <include/ascii-chat/common.h>

Definition at line 62 of file common.h.

uint64_t

typedef unsigned long long uint64_t

#include <include/ascii-chat/common.h>

Definition at line 63 of file common.h.

uint8_t

typedef unsigned char uint8_t

#include <include/ascii-chat/common.h>

Definition at line 60 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 <include/ascii-chat/common.h>

Definition at line 884 of file asciichat_errno.c.

                                                           {
  // This path must also work when an allocator or a diagnostic itself failed.
  bool previous = g_recording;
  g_recording = true;
  char message[ASCIICHAT_ERRNO_MESSAGE_MAX];
  va_list args;
  va_start(args, format);
  vsnprintf(message, sizeof(message), format ? format : "", args);
  va_end(args);
  NOTICE(FATAL, "FATAL ERROR", "%s", asciichat_error_format(message, code));
  log_error("Fatal: %s (at %s:%d in %s)", asciichat_error_format(message, code), file ? file : "?", line,
            function ? function : "?");
  errno_print_stacks();
  g_recording = previous;
#ifdef EMSCRIPTEN_BUILD
  SET_ERRNO(code, "%s", message);
#else
  exit(code);
#endif
}

References args, ASCIICHAT_ERRNO_MESSAGE_MAX, asciichat_error_format(), errno_print_stacks(), FATAL, log_error, NOTICE, and SET_ERRNO.

asciichat_shared_destroy()

void asciichat_shared_destroy

(

void

)

#include <include/ascii-chat/common.h>

Clean up shared library subsystems.

Performs cleanup of all subsystems initialized by asciichat_shared_init(). All cleanup functions are idempotent and safe to call multiple times.

Applications should typically register this with atexit(): asciichat_shared_init(log_file, is_client); atexit(asciichat_shared_destroy);

Note

This function is safe to call even if init failed or wasn't called.

Cleanup order is the reverse of initialization order.

Library code never calls atexit() - only application code should.

Clean up shared library subsystems.

Performs comprehensive cleanup of all subsystems initialized by asciichat_shared_init(). All cleanup functions are idempotent (safe to call multiple times), so this can be called explicitly and also via atexit() without issues.

Cleanup order is carefully chosen to be the reverse of initialization, ensuring dependencies are respected (e.g., timer cleanup before memory reporting, memory reporting before errno cleanup).

Note

This function is safe to call even if init failed or wasn't called.

All subsystem cleanup functions must remain idempotent.

Definition at line 217 of file common.c.

                                    {
  // Guard against double cleanup (can be called explicitly + via atexit)
  static bool shutdown_done = false;
  if (shutdown_done) {
    return;
  }
  shutdown_done = true;
 
  // Stop diagnostic readers before destroying symbols or synchronization state.
  debug_sync_cleanup_thread();
  debug_errno_cleanup_thread();
  debug_stats_cleanup_thread();
 
  stats_runtime_stop();
  ui_controller_shutdown();
  ui_input_shutdown();
  keyboard_destroy();
  symbol_cache_destroy();
 
  // Cleanup in reverse order of initialization (LIFO)
  // This ensures dependencies are properly handled
 
  // 0. Stop background threads first (before any cleanup that might use them)
  // Terminal resize detection thread (Windows only, checks if active)
  terminal_stop_resize_detection();
 
#ifndef NDEBUG
 
  // Clean up all remaining mutex stacks before memory report
  mutex_stack_cleanup();
 
  // Clean up current thread's allocations
  debug_sync_final_cleanup();
 
  // Atomic debug cleanup
  debug_atomic_shutdown();
#endif
  debug_sync_destroy();
  debug_errno_destroy();
  debug_stats_destroy();
 
  // 1. Terminal screen - cleanup frame buffer
  terminal_screen_cleanup();
 
  // 2. SIMD caches - cleanup CPU-specific caches
  simd_caches_destroy_all();
 
  // 3. Discovery service strings cache - cleanup session string cache
  acds_strings_destroy();
 
  // 4. Logging - in correct order (end first, then begin)
  log_shutdown_end();
  log_shutdown_begin();
 
  // 5. Known hosts - cleanup authentication state
  known_hosts_destroy();
 
  // 6. Options state - cleanup RCU-based options
  options_state_destroy();
 
  // 7. buffer domain - cleanup global buffer domain
  buffer_system_cleanup();
 
  // 8. Platform cleanup - restores terminal, cleans up platform resources
  // (includes symbol cache cleanup on Windows)
  platform_destroy();
 
  // 9. Keyboard - restore terminal settings (redundant with platform_destroy but safe)
  keyboard_destroy();
 
  // Workers have stopped; restore argv/environment before releasing title storage.
  platform_process_title_destroy();
 
  // 10. Timer system - cleanup timers (may still log!)
  timer_system_destroy();
 
  // 11. Error context cleanup
  errno_destroy();
 
  // 12. Logging cleanup - free log format buffers and system state
  log_destroy();
  sanitizer_log_destroy();
  log_system_destroy();
 
  // 13. Mutex stack cleanup - must be before memory report so stacks are freed
#ifndef NDEBUG
  mutex_stack_cleanup();
  // Final cleanup: free the main thread's debug allocations
  debug_sync_final_cleanup();
#endif
 
  // 14. Memory stats (debug builds only) - runs with colors still available
  //     Note: debug_memory_report() is also called manually during shutdown in server_main()
  //     The function is safe to call multiple times with polling-based locking
#if defined(USE_MIMALLOC_DEBUG) && !defined(NDEBUG)
  print_mimalloc_stats();
#endif
 
#if defined(DEBUG_MEMORY) && !defined(NDEBUG)
  debug_memory_report(GET_OPTION(color));
#endif
 
  // 15. Color cleanup - free compiled ANSI strings (AFTER memory report)
  log_cleanup_colors();
  colorscheme_destroy();
 
  // 16. Clean up binary path cache explicitly
  // Note: This is also called by platform_destroy() via atexit(), but it's idempotent
  platform_cleanup_binary_path_cache();
 
  // 17. Clean up RCU-based options state
  options_state_destroy();
 
  // 18. Clean up errno context (allocated strings, backtrace symbols)
  errno_shutdown();
 
#ifndef NDEBUG
  // 19. Named registry - cleanup all registered thread names and debug entries
  named_destroy();
#endif
 
  // 21. timer resolution restore
  platform_restore_timer_resolution(); // Restore timer resolution (no-op on POSIX)
 
  // 22. Clean up SIMD caches
  simd_caches_destroy_all();
 
  // 23. Clean up symbol cache
  // This must be called BEFORE log_destroy() as symbol_cache_destroy() uses log_debug()
  // Safe to call even if atexit() runs - it's idempotent (checks g_symbol_cache_initialized)
  // Also called via platform_destroy() atexit handler, but explicit call ensures proper ordering
  symbol_cache_destroy();
 
  // 24. Clean up global buffer domain (explicitly, as atexit may not run on Ctrl-C)
  // Note: This is also registered with atexit(), but calling it explicitly is safe (idempotent)
  // Safe to call even if atexit() runs - it checks the default domain and sets it to NULL
  buffer_system_cleanup();
 
#ifndef NDEBUG
  // 25. Symbol cache cleanup
  symbol_cache_destroy();
#endif
  // No more shutdown diagnostics may scroll pending terminal errors away.
  ui_error_popup_flush();
}

References acds_strings_destroy(), buffer_system_cleanup(), colorscheme_destroy(), debug_errno_cleanup_thread(), debug_errno_destroy(), debug_stats_cleanup_thread(), debug_stats_destroy(), errno_destroy(), errno_shutdown(), GET_OPTION, keyboard_destroy(), known_hosts_destroy(), log_cleanup_colors(), log_destroy(), log_shutdown_begin(), log_shutdown_end(), log_system_destroy(), mutex_stack_cleanup(), named_destroy(), options_state_destroy(), platform_destroy(), platform_process_title_destroy(), platform_restore_timer_resolution(), sanitizer_log_destroy(), simd_caches_destroy_all(), stats_runtime_stop(), symbol_cache_destroy(), terminal_screen_cleanup(), timer_system_destroy(), ui_controller_shutdown(), ui_error_popup_flush(), and ui_input_shutdown().

Referenced by client_main(), and main().

asciichat_shared_init()

asciichat_error_t asciichat_shared_init	(	const char *	log_file,
		bool	is_client,
		bool	quiet_startup )

#include <include/ascii-chat/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 domain initialization
• Cleanup registration (errno, known_hosts, platform, buffer domain)
• 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).

Call this BEFORE options_init() so that options parsing can use properly configured logging with colors. This initializes timer system, logging, and platform subsystems.

Parameters

log_file	Log filename to use (e.g., "client.log" or "ascii-chat.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 131 of file common.c.

                                                                                                  {
  // Initialize shared subsystems BEFORE options_init()
  // This allows options_init() to use properly configured logging with colors
  //
  // NOTE: This function is called BEFORE options_init(), so we can't use GET_OPTION()
  // Palette config and quiet mode will be applied after options_init() is called
 
  // Only register initialization tracking once
  if (!g_shared_initialized) {
    // 1. TIMER SYSTEM - Initialize first so timing is available for everything else
    if (!timer_system_init()) {
      FATAL(ERROR_PLATFORM_INIT, "Failed to initialize timer system");
    }
 
    // KEYBOARD SYSTEM must be initialized BEFORE logging since keyboard_init() calls log_info()
    // But we need to initialize logging AFTER timer_system_init() and BEFORE keyboard_init()
    // So we move keyboard_init() to AFTER log_init()
 
#ifndef NDEBUG
    if (named_init() != ASCIICHAT_OK) {
      return SET_ERRNO(ERROR_PLATFORM_INIT, "Failed to initialize named.");
    }
    debug_memory_ensure_init();
    symbol_cache_init();
#endif
 
    // 2. LOGGING - Initialize system state first, then user-level logging
    // Initialize logging system internal state (terminal caps, colors)
    log_system_init();
 
    // Initialize with provided log file
    // Force stderr for client-like modes when stdout is piped to keep stdout clean
    bool force_stderr = is_client && terminal_is_piped_output();
 
    if (quiet_startup) {
      log_set_terminal_output(false);
    }
 
    // Use LOG_DEBUG by default; will be reconfigured after options_init()
    sanitizer_log_init(log_file);
    log_init(log_file, LOG_DEBUG, force_stderr, false /* don't use_mmap */);
 
    // 2. KEYBOARD SYSTEM - Initialize keyboard input AFTER logging (may fail if stdin/tty not available)
    // Failure is not fatal - keyboard_read_nonblocking() safely handles uninitialized state
    if (terminal_is_stdin_tty()) {
      keyboard_init();
    }
 
    // 3. PLATFORM - Initialize platform-specific functionality (Winsock, etc)
    if (platform_init() != ASCIICHAT_OK) {
      FATAL(ERROR_PLATFORM_INIT, "Failed to initialize platform");
    }
    if (socket_init() != 0) {
      FATAL(ERROR_PLATFORM_INIT, "Failed to initialize sockets");
    }
 
    // 4. buffer domain - Initialize global shared buffer domain
    buffer_system_init();
 
    // Mark that we've initialized (prevents re-registration of subsystems)
    g_shared_initialized = true;
  }
 
  // NOTE: This library function does NOT register atexit() handlers.
  // Library code should not own the process lifecycle. The application
  // is responsible for calling atexit(asciichat_shared_destroy) if it
  // wants automatic cleanup on normal exit.
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, buffer_system_init(), ERROR_PLATFORM_INIT, FATAL, keyboard_init(), LOG_DEBUG, log_file, log_init(), log_set_terminal_output(), log_system_init(), named_init(), platform_init(), sanitizer_log_init(), SET_ERRNO, symbol_cache_init(), and timer_system_init().

Referenced by main().

fps_frame_ns()

void fps_frame_ns	(	fps_t *	tracker,
		uint64_t	current_time_ns,
		const char *	context )

#include <include/ascii-chat/util/fps.h>

Track a frame and detect lag conditions (nanosecond version - PRIMARY).

Call this function when a frame is processed. Automatically detects when frames arrive late and generates periodic FPS reports every report_interval_ns. This is the primary API that all code should use going forward.

Parameters

tracker	FPS tracker state
current_time_ns	Timestamp of this frame in nanoseconds (from time_get_ns())
context	Optional context string for lag logging (e.g., "ASCII frame received")

Example usage:

fps_t tracker;
fps_init(&tracker, 60, "RENDER");
 
// In your frame loop
uint64_t now = time_get_ns();
fps_frame_ns(&tracker, now, "frame rendered");

Definition at line 52 of file fps.c.

                                                                                 {
  if (!tracker) {
    return;
  }
 
  // Initialize on first frame
  if (tracker->last_fps_report_ns == 0) {
    tracker->last_fps_report_ns = current_time_ns;
    tracker->last_frame_time_ns = current_time_ns;
  }
 
  tracker->frame_count++;
 
  // Calculate time since last frame in nanoseconds
  uint64_t frame_interval_ns = time_elapsed_ns(tracker->last_frame_time_ns, current_time_ns);
  tracker->last_frame_time_ns = current_time_ns;
 
  // Expected frame interval in nanoseconds
  // For 60 FPS: 1 second / 60 = 16,666,666 ns per frame
  uint64_t expected_interval_ns = NS_PER_SEC_INT / (uint64_t)tracker->expected_fps;
  uint64_t lag_threshold_ns = expected_interval_ns + (expected_interval_ns / 2); // 50% over expected
 
  // Log error if frame arrived too late (only after first frame)
  if (tracker->frame_count > 1 && frame_interval_ns > lag_threshold_ns) {
    const char *context_str = context ? context : "Frame";
 
    // Convert to milliseconds for display (but calculations stay in nanoseconds)
    double late_ms = time_ns_to_us(frame_interval_ns - expected_interval_ns) / 1000.0;
    double expected_ms = time_ns_to_us(expected_interval_ns) / 1000.0;
    double actual_ms = time_ns_to_us(frame_interval_ns) / 1000.0;
    double actual_fps = 1e9 / (double)frame_interval_ns;
 
    log_lag_event(tracker->tracker_name, context_str, late_ms, expected_ms, actual_ms, actual_fps);
  }
 
  // Report FPS every report_interval_ns
  uint64_t elapsed_ns = time_elapsed_ns(tracker->last_fps_report_ns, current_time_ns);
 
  if (elapsed_ns >= tracker->report_interval_ns) {
    double elapsed_seconds = time_ns_to_s(elapsed_ns);
    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_ns = current_time_ns;
  }
}

References fps_t::expected_fps, fps_t::frame_count, fps_t::last_fps_report_ns, fps_t::last_frame_time_ns, NS_PER_SEC_INT, fps_t::report_interval_ns, time_elapsed_ns(), and fps_t::tracker_name.

Referenced by client_audio_render_thread(), and client_video_render_thread().

fps_init()

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

#include <include/ascii-chat/util/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 32 of file fps.c.

                                                                  {
  // Default report interval: 1 second
  fps_init_with_interval(tracker, expected_fps, name, 1 * NS_PER_SEC_INT);
}

References fps_init_with_interval(), and NS_PER_SEC_INT.

Referenced by client_audio_render_thread(), client_video_render_thread(), session_capture_create(), and session_network_capture_create().

fps_init_with_interval()

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

#include <include/ascii-chat/util/fps.h>

Initialize FPS tracker with custom report interval.

Sets up the tracker with expected FPS and custom reporting interval in nanoseconds. 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_ns	Custom report interval in nanoseconds (e.g., 10000000000 = 10 seconds)

Definition at line 37 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_ns = report_interval_ns;
 
  // Initialize timestamps to zero (will be set on first frame)
  tracker->last_fps_report_ns = 0;
  tracker->last_frame_time_ns = 0;
}

References fps_t::expected_fps, fps_t::frame_count, fps_t::last_fps_report_ns, fps_t::last_frame_time_ns, fps_t::report_interval_ns, and fps_t::tracker_name.

Referenced by fps_init().

Variable Documentation

g_argc

int g_argc

extern

#include <include/ascii-chat/common.h>

Global argc for early argument inspection (e.g., –color flag detection) Set by main() for access from lib/platform/terminal.c during early execution.

Definition at line 61 of file common.c.

Referenced by main().

g_argv

char** g_argv

extern

#include <include/ascii-chat/common.h>

Global argv for early argument inspection (e.g., –color flag detection) Set by main() for access from lib/platform/terminal.c during early execution.

Definition at line 62 of file common.c.

Referenced by main().

g_color_flag_passed

bool g_color_flag_passed

extern

#include <include/ascii-chat/common.h>

Was –color explicitly passed in command-line arguments? Set by options_init() before RCU is initialized, used by terminal_should_color_output().

Definition at line 65 of file common.c.

Referenced by colored_string(), and main().

g_color_flag_value

bool g_color_flag_value

extern

#include <include/ascii-chat/common.h>

Value of –color flag (true if –color was in argv) Set by options_init() before RCU is initialized, used by terminal_should_color_output().

Definition at line 66 of file common.c.

Referenced by colored_string(), and main().