ascii-chat
Binary v0.16.50-198-g78f51665f
Library lib/v0.3.2-2240-g78f51665f
Video chat in your terminal
Loading...
Searching...
No Matches

🐛 Tools to help you figure out what's going on with the code More...

Files

file  mutex.c
 Per-thread mutex lock stack for deadlock detection.
file  named.c
 Named object registry for debugging.
file  mutex.h
 Per-thread mutex lock stack for deadlock detection.
file  named.h
 Named object registry for debugging — log identifiable resource names.

Data Structures

 The useful part of named metadata is in its fields: together they describe what is pending, who owns it, and how much data is valid. Keep the object with its parent operation and use the parent cleanup path. More...

Macros

#define DEBUG_NAMED_NAME_BUFFER_SIZE   256
#define DEBUG_NAMED_TYPE_BUFFER_SIZE   64
#define DEBUG_NAMED_FORMAT_BUFFER_SIZE   64
#define NAMED_REGISTER(ptr, name, type, fmt, parent_ptr)
 Register any pointer with base name, type, format spec, and location (auto-suffix).
#define NAMED_REGISTER_FMT(ptr, type, fmt_spec, fmt, ...)
 Register with a formatted name, type, and format spec.
#define NAMED_UNREGISTER(ptr)
 Unregister a pointer.
#define NAMED_GET(ptr)
 Look up registered name for a pointer.
#define NAMED_DESCRIBE(ptr, hint)
 Describe a pointer in log format.
#define NAMED_REGISTER_ID(id, name, type, fmt, parent_ptr)
 Register an integer handle (fd, socket, etc.) with type.
#define NAMED_UNREGISTER_ID(id)
 Unregister an integer handle.
#define NAMED_DESCRIBE_ID(id, hint)
 Describe an integer handle in log format.
#define NAMED_REGISTER_MUTEX(mutex, name, parent_ptr)
 Register a mutex with automatic format specifier.
#define NAMED_REGISTER_RWLOCK(lock, name, parent_ptr)
 Register an rwlock with automatic format specifier.
#define NAMED_REGISTER_COND(cond, name, parent_ptr)
 Register a condition variable with automatic format specifier.
#define NAMED_REGISTER_SOCKET(socket, name, parent_ptr)
 Register a socket with automatic format specifier.
#define NAMED_UNREGISTER_SOCKET(socket)
#define NAMED_REGISTER_WEBSOCKET(websocket, name, parent_ptr)
 Register a WebSocket connection with automatic format specifier.
#define NAMED_REGISTER_DATACHANNEL(datachannel, name, parent_ptr)
 Register a data channel with automatic format specifier.
#define NAMED_REGISTER_THREADPOOL_WORK(work, name, parent_ptr)
 Register a thread pool work item with automatic format specifier.
#define NAMED_REGISTER_CLIENT(client, name, parent_ptr)
 Register a client connection with automatic format specifier.
#define NAMED_REGISTER_CRYPTO_CONTEXT(ctx, name, parent_ptr)
 Register a crypto context with automatic format specifier.
#define NAMED_REGISTER_TRANSPORT(transport, name, parent_ptr)
 Register a transport with automatic format specifier.
#define NAMED_REGISTER_FRAME_BUFFER(buf, name, parent_ptr)
 Register a frame buffer with automatic format specifier.
#define NAMED_REGISTER_PACKET_QUEUE(queue, name, parent_ptr)
 Register a packet queue with automatic format specifier.
#define NAMED_REGISTER_AUDIO_RINGBUF(buf, name, parent_ptr)
 Register an audio ring buffer with automatic format specifier.
#define NAMED_REGISTER_MIXER(mixer, name, parent_ptr)
 Register an audio mixer with automatic format specifier.
#define NAMED_REGISTER_AUDIO_CODEC(codec, name, parent_ptr)
 Register an audio codec with automatic format specifier.
#define NAMED_REGISTER_VIDEO_ENCODER(encoder, name, parent_ptr)
 Register a video encoder with automatic format specifier.
#define NAMED_REGISTER_BUFFER_DOMAIN(pool, name, parent_ptr)
 Register a buffer domain with automatic format specifier.
#define NAMED_REGISTER_FFMPEG_DECODER(decoder, name, parent_ptr)
 Register an FFmpeg decoder with automatic format specifier.
#define NAMED_REGISTER_FFMPEG_ENCODER(encoder, name, parent_ptr)
 Register an FFmpeg encoder with automatic format specifier.
#define NAMED_REGISTER_H265_ENCODER(encoder, name, parent_ptr)
 Register an H.265 encoder with automatic format specifier.
#define NAMED_REGISTER_H265_DECODER(decoder, name, parent_ptr)
 Register an H.265 decoder with automatic format specifier.
#define NAMED_REGISTER_AUDIO_CONTEXT(ctx, name, parent_ptr)
 Register an audio context with automatic format specifier.
#define NAMED_REGISTER_RATE_LIMITER(limiter, name, parent_ptr)
 Register a rate limiter with automatic format specifier.
#define NAMED_REGISTER_WAV_WRITER(writer, name, parent_ptr)
 Register a WAV writer with automatic format specifier.
#define NAMED_REGISTER_MEDIA_SOURCE(source, name, parent_ptr)
 Register a media source with automatic format specifier.
#define NAMED_OPEN(pathname, name, flags, ...)
 Open a file and register the file descriptor.
#define NAMED_UNREGISTER_FD(fd)
 Unregister a file descriptor.
#define NAMED_REGISTER_FD(fd, name)
 Register an existing file descriptor.
#define NAMED_REGISTER_ATOMIC(a, name, parent_ptr)
 Register an atomic_t with automatic format specifier.
#define NAMED_REGISTER_ATOMIC_PTR(a, name, parent_ptr)
 Register an _Atomic(void *) with automatic format specifier.
#define NAMED_REGISTER_THREAD(thread, name, parent_ptr)
 Register a thread handle with name and automatic format specifier.
#define NAMED_UNREGISTER_THREAD(thread)
 Unregister a thread handle.
#define NAMED_REGISTER_TCP_CLIENT(client, name, parent_ptr)
 Register a TCP client with automatic format specifier.
#define NAMED_REGISTER_WEBSOCKET_CLIENT(client, name, parent_ptr)
 Register a WebSocket client with automatic format specifier.
#define NAMED_REGISTER_APP_CLIENT(client, name, parent_ptr)
 Register an app client with automatic format specifier.
#define NAMED_REGISTER_VIDEO_FRAME_BUFFER(buf, name, parent_ptr)
 Register a video frame buffer with automatic format specifier.
#define NAMED_REGISTER_THREAD_POOL(pool, name, parent_ptr)
 Register a thread pool with automatic format specifier.
#define NAMED_REGISTER_OPTIONS_BUILDER(builder, name, parent_ptr)
 Register an options builder with automatic format specifier.
#define NAMED_REGISTER_SIMPLE_FRAME_SWAP(swap, name, parent_ptr)
 Register a simple frame swap with automatic format specifier.
#define NAMED_REGISTER_CLIENT_AUDIO_PIPELINE(pipeline, name, parent_ptr)
 Register a client audio pipeline with automatic format specifier.
#define NAMED_REGISTER_WEBSOCKET_IMPL(data, name, parent_ptr)
#define NAMED_REGISTER_LWS_CONTEXT(context, name, parent_ptr)
 Register a libwebsockets context with automatic format specifier.
#define NAMED_REGISTER_FFMPEG_CONTEXT(context, name, parent_ptr)
 Register an FFmpeg decoder context with automatic format specifier.
#define NAMED_REGISTER_CONTEXT(context, context_type, name, parent_ptr)
 Register a generic context with automatic format specifier.
#define NAMED_GET_BY_PTR(key, buffer, size)
 Get name of a pointer/key or format as address fallback.
#define NAMED_GET_BY_INT(id, buffer, size)
 Get name of an integer ID or format as hex fallback.
#define NAMED_GET_BY_STR(str, buffer, size)
 Copy a string to buffer, with bounds checking.

Typedefs

typedef void(* named_iter_callback_t) (uintptr_t key, const char *name, void *user_data)
 Callback function for iterating registered entries.
typedef void(* named_snapshot_fn) (uintptr_t key, uint64_t generation, const char *name, const char *type, const char *file, int line, void *data)

Functions

void debug_sync_check_cond_deadlocks (void)
 The useful part of cond deadlock batch is in entries, count: together they describe what is pending, who owns it, and how much data is valid. Keep the object with its parent operation and use the parent cleanup path.
asciichat_error_t named_init (void)
 Initialize the named object registry.
void named_destroy (void)
 Destroy the named object registry.
const char * named_register (uintptr_t key, const char *base_name, const char *type, const char *format_spec, const char *file, int line, const char *func, uintptr_t parent_key)
 Register a resource with an auto-suffixed name, type, and location info.
const char * named_register_fmt (uintptr_t key, const char *type, const char *format_spec, const char *file, int line, const char *func, const char *fmt,...)
 Register a resource with a formatted name, type, and location info (no auto-suffix).
void named_unregister (uintptr_t key)
 Unregister a resource by key.
const char * named_update_name (uintptr_t key, const char *new_base_name)
 Update the registered name for a resource with a new base name.
const char * named_get (uintptr_t key)
 Look up the registered name for a resource.
bool named_metadata_copy (uintptr_t key, named_metadata_t *output)
bool named_fd_metadata_copy (int fd, named_metadata_t *output)
bool named_packet_metadata_copy (int packet_type, named_metadata_t *output)
const char * named_get_type (uintptr_t key)
 Look up the registered type for a resource.
bool named_registry_has_type (const char *type, size_t length)
const char * named_get_format_spec (uintptr_t key)
 Get the format specifier for a registered named object.
const char * named_register_fd (int fd, const char *name, const char *file, int line, const char *func)
 Register a file descriptor with namespace encoding.
const char * named_get_fd (int fd)
 Look up a registered file descriptor.
const char * named_get_fd_format_spec (int fd)
 Get the format specifier for a registered file descriptor.
const char * named_register_packet_type (int pkt_type, const char *file, int line, const char *func)
 Register a packet type with namespace encoding.
const char * named_get_packet_type (int pkt_type)
 Look up a registered packet type.
const char * named_get_packet_type_format_spec (int pkt_type)
 Get the format specifier for a registered packet type.
const char * named_get_by_type_and_id (const char *type_name, size_t type_len, int id)
 Look up an integer ID by type name and value.
const char * named_describe (uintptr_t key, const char *type_hint)
 Format a description string for logging.
uintptr_t thread_to_key (platform_thread_t thread)
 Convert a thread handle to a registry key.
const char * named_describe_thread (void *thread)
 Describe a thread for logging (function wrapper).
void named_registry_register_packet_types (void)
 Register all packet types from packet_type_t enum.
asciichat_error_t named_registry_for_each (named_iter_callback_t callback, void *user_data, bool *completed)
 Iterate through all registered entries.
bool named_registry_read (uintptr_t key, const char *type, void(*read_object)(uintptr_t, void *), void *user_data)
asciichat_error_t named_registry_try_snapshot (size_t capacity, size_t *required, bool *completed, named_snapshot_fn copy, void *data)
void named_print_hash_stats (void)

Type-Specific Description Macros

These macros encapsulate the proper casting and type hint for common types. Use these instead of NAMED_DESCRIBE for better readability and consistency.

#define NAME_DESCRIBE_MUTEX(m)
 Describe a mutex_t for logging.
#define NAME_DESCRIBE_RWLOCK(l)
 Describe an rwlock_t for logging.
#define NAME_DESCRIBE_COND(c)
 Describe a cond_t for logging.
#define NAME_DESCRIBE_THREAD(t)
 Describe a thread for logging.
#define NAME_DESCRIBE_TRANSPORT(tr)
 Describe a transport for logging.
#define NAME_DESCRIBE_SOCKET(fd)
 Describe a socket for logging.
#define NAME_DESCRIBE_RINGBUF(rb)
 Describe a ring buffer for logging.

Detailed Description

🐛 Tools to help you figure out what's going on with the code

This module provides a centralized registry for naming any addressable resource: mutexes, threads, sockets, ring buffers, network connections, etc.

Any value that fits in a uintptr_t can be registered with a human-readable name. Names are auto-suffixed with a unique ID (e.g., "recv_mutex.7") to distinguish multiple instances of the same conceptual resource.

The registry is thread-safe and zero-overhead in release builds (NDEBUG).

Note
Registry is not thread-safe for unregistration during unwind. Always unregister resources before they become invalid (e.g., in destroy/cleanup).

USAGE EXAMPLES:

// Pointer-based (for heap objects, structs) ringbuffer_t *rb = ringbuffer_create(...); NAMED_REGISTER(rb, "recv_audio"); // auto name: "recv_audio.3" // ... use rb ... NAMED_UNREGISTER(rb); ringbuffer_destroy(rb);

// Integer handle-based (for fd, socket, etc.) int client_fd = accept(server_fd, ...); NAMED_REGISTER_ID(client_fd, "client_socket"); // ... use client_fd ... NAMED_UNREGISTER_ID(client_fd); close(client_fd);

// Describing in logs log_info("Data received on %s", NAME_DESCRIBE_SOCKET(fd)); // Output: "socket: client_socket.2 (0x8)"

Author
Zachary Fogg me@zf.nosp@m.o.gg
Date
February 2026

Debug README

Overview

The Debugging Utilities module provides comprehensive debugging and diagnostic tools for ascii-chat development and troubleshooting. This module includes error tracking, lock debugging, memory leak detection, and diagnostic utilities to help identify and resolve issues in the codebase.

Key Features:

  • Thread-local error context with stack traces
  • Lock debugging and deadlock detection
  • Memory leak detection and tracking
  • Safe memory allocation macros with error checking
  • Debug build utilities for diagnostics

Debug Modules

Error Handling (asciichat_errno)

The error handling system provides thread-local error tracking with full context:

Thread-Local Error Context:

  • Each thread has independent error state
  • Automatic file/line/function capture
  • Stack trace capture in debug builds
  • System error integration (errno, WSA errors)

Error Context Structure:

typedef struct {
asciichat_error_t error_code; // Error code
const char *file; // Source file
int line; // Line number
const char *function; // Function name
char *stack_trace; // Stack trace (debug builds)
char *context_message; // Custom context message
time_t timestamp; // Error timestamp
int system_error; // System errno/WSA error
asciichat_error_t
Error and exit codes - unified status values (0-255).
Definition error_codes.h:48

Library Macros:

// In library code (lib/):
SET_ERRNO(ERROR_NETWORK, "Connection failed");
SET_ERRNO_SYS(ERROR_MEMORY, "malloc failed", errno);
#define SET_ERRNO(code,...)
#define SET_ERRNO_SYS(code,...)
@ ERROR_NETWORK
Definition error_codes.h:76
@ ERROR_MEMORY
Definition error_codes.h:55

Application Macros:

// In application code (src/):
if (HAS_ERRNO()) {
log_error("Library error: %s at %s:%d in %s()",
ctx->context_message, ctx->file, ctx->line, ctx->function);
}
#define HAS_ERRNO(context)
#define GET_ERRNO()
#define CLEAR_ERRNO()
#define log_error(...)
Log an ERROR message.
Definition log/log.h:628

Debug Features:

  • Stack traces captured automatically in debug builds
  • Full error context in log messages
  • Error statistics tracking per thread
  • Integration with FATAL() macro

Lock Debugging (lock_debug)

The lock debugging system tracks all mutex and rwlock acquisitions to help identify deadlocks and lock contention issues:

Lock Tracking:

  • Tracks all mutex and rwlock acquisitions with backtraces
  • Thread-safe lock record management
  • Automatic cleanup of lock records on unlock
  • Integration with platform backtrace functionality

Lock Record Structure:

typedef struct lock_record {
void *lock_address; // Lock object address
lock_type_t lock_type; // MUTEX, RWLOCK_READ, RWLOCK_WRITE
uint64_t thread_id; // Thread that acquired lock
struct timespec acquisition_time; // When lock was acquired
const char *file_name; // Source file
int line_number; // Line number
const char *function_name; // Function name
void *backtrace_buffer[32]; // Raw backtrace addresses
char **backtrace_symbols; // Symbolized backtrace
} lock_record_t;
unsigned long long uint64_t

Usage:

// Initialize lock debugging
lock_debug_init();
// Replace regular locks with debug versions
DEBUG_MUTEX_LOCK(&my_mutex);
// ... critical section ...
DEBUG_MUTEX_UNLOCK(&my_mutex);
// Start debug thread to print locks on '?' key
lock_debug_start_thread();
// Print lock debug state (held locks, orphaned releases, statistics)
lock_debug_print_state();

Debug Thread:

  • Runs in background monitoring lock state
  • Press '?' key to trigger lock information printing
  • Prints all held locks with full backtraces
  • Helps identify deadlocks and lock contention

Lock Statistics:

  • Total locks acquired/released (lifetime)
  • Current number of held locks
  • Lock usage statistics by code location
  • Orphaned release detection (unlocks without locks)

Memory Debugging (common.h)

The memory debugging system provides comprehensive memory leak detection and tracking:

Memory Macros:

  • SAFE_MALLOC: Safe malloc with error checking
  • SAFE_CALLOC: Safe calloc with error checking
  • SAFE_REALLOC: Safe realloc with error checking
  • SAFE_FREE: Safe free that sets pointer to NULL
  • SAFE_MALLOC_ALIGNED: Aligned memory allocation
  • SAFE_MALLOC_SIMD: SIMD-aligned memory allocation

Usage:

// Allocate memory (automatically checks for NULL)
int *array = SAFE_MALLOC(100 * sizeof(int), int*);
// Allocate zero-initialized memory
char *buffer = SAFE_CALLOC(1024, sizeof(char), char*);
// Reallocate memory
buffer = SAFE_REALLOC(buffer, 2048, char*);
// Free memory (sets pointer to NULL, removes from leak tracker)
SAFE_FREE(buffer);
#define SAFE_REALLOC(ptr, size, cast)
#define SAFE_FREE(ptr)
#define SAFE_MALLOC(size, cast)
#define SAFE_CALLOC(count, size, cast)

Debug Memory Tracking:

When DEBUG_MEMORY is defined and CMAKE_BUILD_TYPE=Debug:

Leak Detection:

  • All allocations tracked with address, size, file, line, timestamp
  • On program exit, reports any unfreed allocations
  • Thread-safe allocation tracking
  • Comprehensive leak reports

Allocation Logging:

[MEMORY] malloc(1024) = 0x7f1234567890 at src/client.c:123 in process_frame()
[MEMORY] free(0x7f1234567890) at src/client.c:456 in cleanup_frame()

Double-Free Detection:

  • Detects freeing already-freed memory
  • Triggers assertion with full context
  • Prevents use-after-free bugs

Memory Reports:

debug_memory_report();
// Output:
// Current allocations: 5 (total 4096 bytes)
// Peak allocations: 10 (total 8192 bytes)
// Total malloc calls: 100
// Total free calls: 95
// Leaked: 5 allocations (4096 bytes)

Memory Statistics:

  • Current allocations and total size
  • Peak allocations and peak size
  • Total allocation/deallocation calls
  • Leak summary (unfreed allocations)

Integration

Build Configuration

Debug Build:

cmake -DCMAKE_BUILD_TYPE=Debug -DDEBUG_MEMORY=ON ..

Enable Debug Features:

// Enable memory debugging
#define DEBUG_MEMORY 1
// Enable lock debugging
lock_debug_init();
lock_debug_start_thread();
// Error tracking is always enabled (thread-local)

Runtime Usage

Error Handling:

// Library code sets errors
if (connect_failed) {
SET_ERRNO(ERROR_NETWORK, "Connection timeout");
return ERROR_NETWORK;
}
// Application code checks errors
if (some_library_function() != ASCIICHAT_OK) {
if (HAS_ERRNO()) {
log_error("Error: %s", ctx->context_message);
}
}
@ ASCIICHAT_OK
Definition error_codes.h:50

Lock Debugging:

// Replace mutex_lock with DEBUG_MUTEX_LOCK
DEBUG_MUTEX_LOCK(&my_mutex);
// ... critical section ...
DEBUG_MUTEX_UNLOCK(&my_mutex);
// Print lock debug state anytime (held locks, orphaned releases, statistics)
lock_debug_print_state();

Memory Debugging:

// Use SAFE_* macros for all allocations
void *data = SAFE_MALLOC(size, void*);
// Check for leaks at any time
debug_memory_report();
// Quiet mode (suppress stderr output)
debug_memory_set_quiet_mode(true);

Best Practices

  1. Use Error Handling Consistently:
    // Always use SET_ERRNO in library code
    SET_ERRNO(ERROR_MEMORY, "Allocation failed");
    // Always check HAS_ERRNO in application code
    if (HAS_ERRNO()) {
    handle_error();
    }
  2. Enable Lock Debugging During Development:
    // Initialize early in main()
    lock_debug_init();
    lock_debug_start_thread();
    // Use DEBUG_* lock macros everywhere
    DEBUG_MUTEX_LOCK(&mutex);
  3. Use SAFE_* Macros for All Allocations:
    // Always use SAFE_MALLOC instead of malloc
    void *ptr = SAFE_MALLOC(size, void*);
    // Always use SAFE_FREE (sets pointer to NULL)
    SAFE_FREE(ptr);
  4. Check Memory Leaks Regularly:
    // Call before program exit
    debug_memory_report();
    // Or enable automatic leak detection
    // Leaks are reported on program exit automatically
  5. Debug Thread for Lock Monitoring:
    // Start debug thread
    lock_debug_start_thread();
    // Press '?' key anytime to see held locks
    // Useful for debugging deadlocks

Performance Impact

Debug Builds:

  • Stack trace capture adds ~5-10ms per error
  • Lock tracking adds ~1-2µs per lock operation
  • Memory tracking adds ~1-2µs per allocation
  • Debug thread uses minimal CPU (waits for '?' key)

Release Builds:

  • Error handling: Minimal overhead (thread-local storage)
  • Lock debugging: Disabled (no overhead)
  • Memory debugging: Disabled (no overhead)
  • All debug features are compiled out

Recommendations:

  • Use debug builds during development
  • Disable debug features in production builds
  • Enable memory debugging only when investigating leaks
  • Enable lock debugging only when investigating deadlocks

Examples

Error Handling Example

// Library code (lib/network/network.c)
asciichat_error_t network_connect(const char *host, int port) {
socket_t sock = socket_create();
if (sock == INVALID_SOCKET) {
SET_ERRNO_SYS(ERROR_NETWORK, "socket() failed", errno);
return ERROR_NETWORK;
}
if (connect_failed) {
SET_ERRNO(ERROR_NETWORK_CONNECT, "Connection timeout");
socket_close(sock);
}
return ASCIICHAT_OK;
}
// Application code (src/client/main.c)
int main() {
asciichat_error_t err = network_connect("server.example.com", 8080);
if (err != ASCIICHAT_OK) {
if (HAS_ERRNO()) {
log_error("Network error: %s at %s:%d",
ctx->context_message, ctx->file, ctx->line);
if (ctx->stack_trace) {
log_debug("Stack trace:\n%s", ctx->stack_trace);
}
}
return err;
}
return 0;
}
int socket_close(socket_t sock)
@ ERROR_NETWORK_CONNECT
Definition error_codes.h:78
#define log_debug(...)
Log a DEBUG message.
Definition log/log.h:589
int socket_t
int main(int argc, char *argv[])
Definition main.c:543

Lock Debugging Example

// Initialize lock debugging
int main() {
lock_debug_init();
lock_debug_start_thread();
// Use debug lock macros
static mutex_t g_shared_mutex;
void critical_section() {
DEBUG_MUTEX_LOCK(&g_shared_mutex);
// ... critical code ...
DEBUG_MUTEX_UNLOCK(&g_shared_mutex);
}
// Press '?' key to see all held locks
// Output:
// Lock at 0x7f1234567890 (MUTEX)
// Acquired by thread 0x1234 at client.c:123 in critical_section()
// Backtrace:
// #0: critical_section() at client.c:123
// #1: process_frame() at client.c:456
// #2: main() at client.c:789
lock_debug_cleanup();
}

Memory Debugging Example

// Enable memory debugging
#define DEBUG_MEMORY 1
void process_data() {
// All allocations are tracked
int *data = SAFE_MALLOC(1000 * sizeof(int), int*);
char *buffer = SAFE_CALLOC(1024, sizeof(char), char*);
// Use data...
process(data, buffer);
// Free memory (removes from leak tracker)
SAFE_FREE(data);
SAFE_FREE(buffer);
}
// At program exit, automatic leak report:
// Memory leak detected:
// Address: 0x7f1234567890
// Size: 1024 bytes
// Allocated at: client.c:123 in process_data()
// Thread: 0x7f123456
// Total leaked: 1024 bytes in 1 allocation

Debugging Tools

These external tools help with debugging and crash analysis. They are not build tools and are not required to compile ascii-chat, but are essential for development.

Stack Trace Symbolizers

Symbolizers convert raw memory addresses into human-readable function names and source locations. The shared libplatform backtrace system (libplatform/symbols.c) source locations. The shared libplatform backtrace system (libplatform/symbols.c) automatically detects and uses these tools when available.

Tool Platform Priority
llvm-symbolizer All Preferred - best for Clang-compiled binaries
addr2line Linux/macOS Fallback - GNU binutils alternative
Note
Important: Ensure at least one symbolizer is in your PATH for readable backtraces during debugging. Without a symbolizer, you'll only see raw memory addresses like 0x401234 instead of main() at src/client.c:42.

Automatic Detection (libplatform/symbols.c): Automatic Detection (libplatform/symbols.c):

The symbol cache system automatically:

  1. Checks for llvm-symbolizer in PATH (preferred)
  2. Falls back to addr2line if llvm-symbolizer is not found
  3. Uses raw addresses if neither tool is available
  4. Caches resolved symbols in a hashtable to avoid repeated subprocess calls

You can override the tool paths with environment variables:

  • LLVM_SYMBOLIZER_PATH - Full path to llvm-symbolizer binary
  • ADDR2LINE_PATH - Full path to addr2line binary

Verify Symbolizer Availability:

# Check if llvm-symbolizer is available (preferred)
which llvm-symbolizer || echo "llvm-symbolizer not found"
# Check if addr2line is available (fallback)
which addr2line || echo "addr2line not found"
# Windows (PowerShell)
Get-Command llvm-symbolizer -ErrorAction SilentlyContinue
Get-Command addr2line -ErrorAction SilentlyContinue

Manual Symbolization Examples:

# Manual symbolization of an address
llvm-symbolizer --obj=build/bin/ascii-chat 0x401234
# Using addr2line
addr2line -e build/bin/ascii-chat -f 0x401234
# Filter through symbolizer for readable crash output
./build/bin/ascii-chat 2>&1 | llvm-symbolizer

Installation:

# Install on Debian/Ubuntu
sudo apt install llvm binutils
# Install on Arch
sudo pacman -S llvm binutils
# Install on macOS (via Homebrew)
brew install llvm binutils
# Install on Windows (via scoop or LLVM installer)
scoop install llvm

Interactive Debuggers

Tool Platform Description
lldb All LLVM debugger (recommended for Clang builds)
gdb Linux GNU debugger

LLDB Usage:

# Start debugging
lldb ./build/bin/ascii-chat
# Run with arguments
(lldb) run server --port 8080
# Set breakpoint
(lldb) breakpoint set --name main
(lldb) b network_connect
# Examine backtrace on crash
(lldb) bt
# Examine variables
(lldb) frame variable
(lldb) p my_variable
# Continue execution
(lldb) continue

GDB Usage (Linux):

# Start debugging
gdb ./build/bin/ascii-chat
# Run with arguments
(gdb) run server --port 8080
# Set breakpoint
(gdb) break main
# Backtrace
(gdb) bt

Memory Checking Tools

Tool Platform Description
valgrind Linux Memory error detector (slower but thorough)
leaks macOS Apple's memory leak checker
ASan All AddressSanitizer (built into Debug builds)

Valgrind Usage (Linux):

# Check for memory leaks
valgrind --leak-check=full ./build/bin/ascii-chat server
# Check for invalid memory access
valgrind --tool=memcheck ./build/bin/ascii-chat server

Leaks Usage (macOS):

# Check for leaks at exit
leaks --atExit -- ./build/bin/ascii-chat server
Note
Debug builds (CMAKE_BUILD_TYPE=Debug) automatically enable AddressSanitizer and UndefinedBehaviorSanitizer, which catch most memory errors at runtime.

Binary Analysis Tools

Tool Platform Description
ldd Linux List dynamic dependencies
otool macOS List dynamic dependencies
objdump Linux Disassemble binary
llvm-objdump All LLVM disassembler

Verifying Static Linking (Release builds):

# Linux - should say "not a dynamic executable" for static builds
ldd build/bin/ascii-chat
# macOS - should only show system libraries
otool -L build/bin/ascii-chat
Note
The build system automatically verifies static linking in Release builds using check_static_linking.sh - see Build System.

Troubleshooting

Common Issues:

  1. Stack Traces Not Appearing:
    • Ensure CMAKE_BUILD_TYPE=Debug
    • Check that debug symbols are available
    • Verify addr2line or llvm-symbolizer is in PATH
  2. Lock Debugging Not Working:
    • Ensure lock_debug_init() is called before any locks
    • Use DEBUG_* macros instead of regular lock functions
    • Check that debug thread is started: lock_debug_start_thread()
  3. Memory Leaks Not Detected:
    • Ensure DEBUG_MEMORY is defined
    • Check that CMAKE_BUILD_TYPE=Debug
    • Verify mimalloc override is disabled (MI_MALLOC_OVERRIDE not set)
    • Use SAFE_* macros for all allocations
  4. Performance Issues in Debug Builds:
    • Stack trace capture adds overhead
    • Lock tracking adds small overhead per operation
    • Memory tracking adds small overhead per allocation
    • Use release builds for performance testing
Note
Debug utilities are designed for development and troubleshooting. Disable debug features in production builds for optimal performance.
See also
lib/asciichat_errno.h for Errors handling documentation
lib/lock_debug.h for lock debugging documentation
lib/common.h for memory debugging macros

Macro Definition Documentation

◆ DEBUG_NAMED_FORMAT_BUFFER_SIZE

#define DEBUG_NAMED_FORMAT_BUFFER_SIZE   64

#include <include/ascii-chat/debug/named.h>

Definition at line 49 of file debug/named.h.

◆ DEBUG_NAMED_NAME_BUFFER_SIZE

#define DEBUG_NAMED_NAME_BUFFER_SIZE   256

◆ DEBUG_NAMED_TYPE_BUFFER_SIZE

#define DEBUG_NAMED_TYPE_BUFFER_SIZE   64

#include <include/ascii-chat/debug/named.h>

Definition at line 48 of file debug/named.h.

◆ NAME_DESCRIBE_COND

#define NAME_DESCRIBE_COND ( c)

#include <include/ascii-chat/debug/named.h>

Value:
named_describe((uintptr_t)(const void *)(c), "cond")
const char * named_describe(uintptr_t key, const char *type_hint)
Format a description string for logging.

Describe a cond_t for logging.

Parameters
cPointer to cond_t

Definition at line 821 of file debug/named.h.

◆ NAME_DESCRIBE_MUTEX

#define NAME_DESCRIBE_MUTEX ( m)

#include <include/ascii-chat/debug/named.h>

Value:
named_describe((uintptr_t)(const void *)(m), "mutex")

Describe a mutex_t for logging.

Parameters
mPointer to mutex_t

Definition at line 807 of file debug/named.h.

◆ NAME_DESCRIBE_RINGBUF

#define NAME_DESCRIBE_RINGBUF ( rb)

#include <include/ascii-chat/debug/named.h>

Value:
named_describe((uintptr_t)(const void *)(rb), "ringbuf")

Describe a ring buffer for logging.

Parameters
rbPointer to ringbuffer_t

Definition at line 851 of file debug/named.h.

◆ NAME_DESCRIBE_RWLOCK

#define NAME_DESCRIBE_RWLOCK ( l)

#include <include/ascii-chat/debug/named.h>

Value:
named_describe((uintptr_t)(const void *)(l), "rwlock")

Describe an rwlock_t for logging.

Parameters
lPointer to rwlock_t

Definition at line 814 of file debug/named.h.

◆ NAME_DESCRIBE_SOCKET

#define NAME_DESCRIBE_SOCKET ( fd)

#include <include/ascii-chat/debug/named.h>

Value:
named_describe((uintptr_t)(intptr_t)(fd), "socket")

Describe a socket for logging.

Parameters
fdsocket_t file descriptor

Definition at line 844 of file debug/named.h.

◆ NAME_DESCRIBE_THREAD

#define NAME_DESCRIBE_THREAD ( t)

#include <include/ascii-chat/debug/named.h>

Value:
const char * named_describe_thread(void *thread)
Describe a thread for logging (function wrapper).

Describe a thread for logging.

Parameters
tplatform_thread_t handle

Uses named_describe_thread() function to handle platform-specific conversion.

Definition at line 830 of file debug/named.h.

◆ NAME_DESCRIBE_TRANSPORT

#define NAME_DESCRIBE_TRANSPORT ( tr)

#include <include/ascii-chat/debug/named.h>

Value:
named_describe((uintptr_t)(const void *)(tr), "transport")

Describe a transport for logging.

Parameters
trPointer to acip_transport_t

Definition at line 837 of file debug/named.h.

◆ NAMED_DESCRIBE

#define NAMED_DESCRIBE ( ptr,
hint )

#include <include/ascii-chat/debug/named.h>

Value:
named_describe((uintptr_t)(const void *)(ptr), (hint))

Describe a pointer in log format.

Parameters
ptrObject pointer
hintType hint string (e.g., "mutex")

Definition at line 381 of file debug/named.h.

Referenced by websocket_server_run().

◆ NAMED_DESCRIBE_ID

#define NAMED_DESCRIBE_ID ( id,
hint )

#include <include/ascii-chat/debug/named.h>

Value:
named_describe((uintptr_t)(intptr_t)(id), (hint))

Describe an integer handle in log format.

Parameters
idInteger handle
hintType hint string (e.g., "socket")

Definition at line 412 of file debug/named.h.

◆ NAMED_GET

#define NAMED_GET ( ptr)

#include <include/ascii-chat/debug/named.h>

Value:
named_get((uintptr_t)(const void *)(ptr))
const char * named_get(uintptr_t key)
Look up the registered name for a resource.

Look up registered name for a pointer.

Parameters
ptrObject pointer

Definition at line 373 of file debug/named.h.

◆ NAMED_GET_BY_INT

#define NAMED_GET_BY_INT ( id,
buffer,
size )

#include <include/ascii-chat/debug/named.h>

Value:
do { \
const char *_name = named_get((uintptr_t)(id)); \
if (_name) { \
size_t _len = strlen(_name); \
if (_len >= (size)) \
_len = (size) - 1; \
memcpy((buffer), (_name), _len); \
(buffer)[_len] = '\0'; \
} else { \
snprintf((buffer), (size), "0x%lx", (unsigned long)(id)); \
} \
} while (0)

Get name of an integer ID or format as hex fallback.

Parameters
idThe integer ID to look up (e.g., thread ID, FD, packet type)
bufferOutput buffer for the result
sizeSize of the output buffer

Tries to look up the registered name for an integer ID. If found, copies it to buffer. If not found, formats the ID as "0x%lx" (hexadecimal).

Use this for thread IDs and other small integer identifiers. In release builds (NDEBUG), always formats as hex.

Definition at line 1086 of file debug/named.h.

1086#define NAMED_GET_BY_INT(id, buffer, size) \
1087 do { \
1088 const char *_name = named_get((uintptr_t)(id)); \
1089 if (_name) { \
1090 size_t _len = strlen(_name); \
1091 if (_len >= (size)) \
1092 _len = (size) - 1; \
1093 memcpy((buffer), (_name), _len); \
1094 (buffer)[_len] = '\0'; \
1095 } else { \
1096 snprintf((buffer), (size), "0x%lx", (unsigned long)(id)); \
1097 } \
1098 } while (0)

◆ NAMED_GET_BY_PTR

#define NAMED_GET_BY_PTR ( key,
buffer,
size )

#include <include/ascii-chat/debug/named.h>

Value:
do { \
const char *_name = named_get(key); \
if (_name) { \
size_t _len = strlen(_name); \
if (_len >= (size)) \
_len = (size) - 1; \
memcpy((buffer), (_name), _len); \
(buffer)[_len] = '\0'; \
} else { \
snprintf((buffer), (size), "0x%tx", (ptrdiff_t)(key)); \
} \
} while (0)

Get name of a pointer/key or format as address fallback.

Parameters
keyThe uintptr_t key to look up
bufferOutput buffer for the result
sizeSize of the output buffer

Tries to look up the registered name for the key. If found, copies it to buffer. If not found, formats the key as "0x%tx" (hexadecimal address).

Useful in hot paths like logging where you want the name if available, but need a reasonable fallback for unregistered keys.

In release builds (NDEBUG), always formats as address.

Definition at line 1059 of file debug/named.h.

1059#define NAMED_GET_BY_PTR(key, buffer, size) \
1060 do { \
1061 const char *_name = named_get(key); \
1062 if (_name) { \
1063 size_t _len = strlen(_name); \
1064 if (_len >= (size)) \
1065 _len = (size) - 1; \
1066 memcpy((buffer), (_name), _len); \
1067 (buffer)[_len] = '\0'; \
1068 } else { \
1069 snprintf((buffer), (size), "0x%tx", (ptrdiff_t)(key)); \
1070 } \
1071 } while (0)

Referenced by mutex_stack_detect_deadlocks().

◆ NAMED_GET_BY_STR

#define NAMED_GET_BY_STR ( str,
buffer,
size )

#include <include/ascii-chat/debug/named.h>

Value:
do { \
if ((str)) { \
strncpy((buffer), (str), (size) - 1); \
(buffer)[(size) - 1] = '\0'; \
} else { \
(buffer)[0] = '\0'; \
} \
} while (0)

Copy a string to buffer, with bounds checking.

Parameters
strThe string to copy (may be NULL)
bufferOutput buffer
sizeSize of the output buffer

Safe string copy that handles NULL inputs and ensures null termination. Useful for formatting optional or variable string fields.

In release builds (NDEBUG), copies the string as-is.

Definition at line 1112 of file debug/named.h.

1112#define NAMED_GET_BY_STR(str, buffer, size) \
1113 do { \
1114 if ((str)) { \
1115 strncpy((buffer), (str), (size) - 1); \
1116 (buffer)[(size) - 1] = '\0'; \
1117 } else { \
1118 (buffer)[0] = '\0'; \
1119 } \
1120 } while (0)

◆ NAMED_OPEN

#define NAMED_OPEN ( pathname,
name,
flags,
... )

#include <include/ascii-chat/debug/named.h>

Value:
({ \
int _fd; \
if ((flags) & O_CREAT) { \
_fd = platform_open((pathname), (flags), __VA_ARGS__); \
} else { \
_fd = platform_open((pathname), (flags)); \
} \
if (_fd >= 0) { \
named_register_fd(_fd, NULL, __FILE__, __LINE__, __func__); \
} \
_fd; \
})
int platform_open(const char *name, const char *pathname, int flags,...)
Definition filesystem.c:65

Open a file and register the file descriptor.

Parameters
pathnameFile path to open
nameDebug name for the file descriptor
flagsOpen flags (O_RDONLY, O_WRONLY, etc.)
...Optional mode argument for O_CREAT

Convenience macro that opens a file and registers the returned FD. Automatically uses "%d" format specifier for file descriptor integers.

Usage: int fd = NAMED_OPEN("/path/to/file", "myfile", O_RDONLY); int fd = NAMED_OPEN("/path/to/file", "myfile", O_CREAT | O_WRONLY, 0644);

Definition at line 711 of file debug/named.h.

711#define NAMED_OPEN(pathname, name, flags, ...) \
712 ({ \
713 int _fd; \
714 if ((flags) & O_CREAT) { \
715 _fd = platform_open((pathname), (flags), __VA_ARGS__); \
716 } else { \
717 _fd = platform_open((pathname), (flags)); \
718 } \
719 if (_fd >= 0) { \
720 named_register_fd(_fd, NULL, __FILE__, __LINE__, __func__); \
721 } \
722 _fd; \
723 })

◆ NAMED_REGISTER

#define NAMED_REGISTER ( ptr,
name,
type,
fmt,
parent_ptr )

#include <include/ascii-chat/debug/named.h>

Value:
named_register((uintptr_t)(const void *)(ptr), (name), (type), (fmt), __FILE__, __LINE__, __func__, (uintptr_t)(const void *)(parent_ptr))
const char * named_register(uintptr_t key, const char *base_name, const char *type, const char *format_spec, const char *file, int line, const char *func, uintptr_t parent_key)
Register a resource with an auto-suffixed name, type, and location info.

Register any pointer with base name, type, format spec, and location (auto-suffix).

Parameters
ptrObject pointer (void* or typed pointer)
nameBase name string
typeData type label (e.g., "mutex", "socket")
fmtFormat specifier for printing (e.g., "0x%tx")

In debug builds, automatically captures FILE, LINE, and func for location info. In release builds (NDEBUG), this is a no-op.

Definition at line 345 of file debug/named.h.

Referenced by acds_client_connect(), acip_tcp_transport_create(), animation_init(), audio_init(), consensus_coordinator_create(), media_source_create_interruptible(), tcp_server_init(), webrtc_create_peer_connection(), and websocket_server_init().

◆ NAMED_REGISTER_APP_CLIENT

#define NAMED_REGISTER_APP_CLIENT ( client,
name,
parent_ptr )

#include <include/ascii-chat/debug/named.h>

Value:
named_register((uintptr_t)(const void *)(client), (name), "app_client", "0x%tx", __FILE__, __LINE__, __func__, (uintptr_t)(const void *)(parent_ptr))

Register an app client with automatic format specifier.

Parameters
clientApp client pointer
nameBase name string

Definition at line 910 of file debug/named.h.

910#define NAMED_REGISTER_APP_CLIENT(client, name, parent_ptr) \
911 named_register((uintptr_t)(const void *)(client), (name), "app_client", "0x%tx", __FILE__, __LINE__, __func__, (uintptr_t)(const void *)(parent_ptr))

◆ NAMED_REGISTER_ATOMIC

#define NAMED_REGISTER_ATOMIC ( a,
name,
parent_ptr )

#include <include/ascii-chat/debug/named.h>

Value:
named_register((uintptr_t)(const void *)(a), (name), "atomic", "0x%tx", __FILE__, __LINE__, __func__, (uintptr_t)(const void *)(parent_ptr))

Register an atomic_t with automatic format specifier.

Parameters
aPointer to atomic_t
nameBase name string

Convenience macro that automatically uses "0x%tx" format specifier for atomic addresses.

Definition at line 754 of file debug/named.h.

Referenced by audio_init(), audio_ring_buffer_register_atomics(), buffer_system_init(), create_mixed_ascii_frame_for_client(), discovery_session_create(), ffmpeg_decoder_create_stdin(), ffmpeg_decoder_create_with_request_options(), media_source_create_interruptible(), ringbuffer_create(), session_av_state_create(), session_pipeline_create(), tcp_server_init(), terminal_screen_log_init(), video_frame_buffer_create(), and websocket_server_init().

◆ NAMED_REGISTER_ATOMIC_PTR

#define NAMED_REGISTER_ATOMIC_PTR ( a,
name,
parent_ptr )

#include <include/ascii-chat/debug/named.h>

Value:
named_register((uintptr_t)(const void *)(a), (name), "atomic_ptr", "0x%tx", __FILE__, __LINE__, __func__, (uintptr_t)(const void *)(parent_ptr))

Register an _Atomic(void *) with automatic format specifier.

Parameters
aPointer to _Atomic(void *)
nameBase name string

Convenience macro that automatically uses "0x%tx" format specifier for atomic_ptr addresses.

Definition at line 764 of file debug/named.h.

Referenced by session_pipeline_create().

◆ NAMED_REGISTER_AUDIO_CODEC

#define NAMED_REGISTER_AUDIO_CODEC ( codec,
name,
parent_ptr )

#include <include/ascii-chat/debug/named.h>

Value:
named_register((uintptr_t)(const void *)(codec), (name), "audio_codec", "0x%tx", __FILE__, __LINE__, __func__, (uintptr_t)(const void *)(parent_ptr))

Register an audio codec with automatic format specifier.

Parameters
codecAudio codec pointer
nameBase name string

Convenience macro that automatically uses "0x%tx" format specifier for audio codec addresses.

Definition at line 580 of file debug/named.h.

580#define NAMED_REGISTER_AUDIO_CODEC(codec, name, parent_ptr) \
581 named_register((uintptr_t)(const void *)(codec), (name), "audio_codec", "0x%tx", __FILE__, __LINE__, __func__, (uintptr_t)(const void *)(parent_ptr))

◆ NAMED_REGISTER_AUDIO_CONTEXT

#define NAMED_REGISTER_AUDIO_CONTEXT ( ctx,
name,
parent_ptr )

#include <include/ascii-chat/debug/named.h>

Value:
named_register((uintptr_t)(const void *)(ctx), (name), "audio_context", "0x%tx", __FILE__, __LINE__, __func__, (uintptr_t)(const void *)(parent_ptr))

Register an audio context with automatic format specifier.

Parameters
ctxAudio context pointer
nameBase name string

Convenience macro that automatically uses "0x%tx" format specifier for audio context addresses.

Definition at line 660 of file debug/named.h.

660#define NAMED_REGISTER_AUDIO_CONTEXT(ctx, name, parent_ptr) \
661 named_register((uintptr_t)(const void *)(ctx), (name), "audio_context", "0x%tx", __FILE__, __LINE__, __func__, (uintptr_t)(const void *)(parent_ptr))

◆ NAMED_REGISTER_AUDIO_RINGBUF

#define NAMED_REGISTER_AUDIO_RINGBUF ( buf,
name,
parent_ptr )

#include <include/ascii-chat/debug/named.h>

Value:
named_register((uintptr_t)(const void *)(buf), (name), "audio_ringbuf", "0x%tx", __FILE__, __LINE__, __func__, (uintptr_t)(const void *)(parent_ptr))

Register an audio ring buffer with automatic format specifier.

Parameters
bufAudio ring buffer pointer
nameBase name string

Convenience macro that automatically uses "0x%tx" format specifier for ring buffer addresses.

Definition at line 559 of file debug/named.h.

559#define NAMED_REGISTER_AUDIO_RINGBUF(buf, name, parent_ptr) \
560 named_register((uintptr_t)(const void *)(buf), (name), "audio_ringbuf", "0x%tx", __FILE__, __LINE__, __func__, (uintptr_t)(const void *)(parent_ptr))

Referenced by audio_init(), and audio_ring_buffer_register_atomics().

◆ NAMED_REGISTER_BUFFER_DOMAIN

#define NAMED_REGISTER_BUFFER_DOMAIN ( pool,
name,
parent_ptr )

#include <include/ascii-chat/debug/named.h>

Value:
named_register((uintptr_t)(const void *)(pool), (name), "buffer_domain", "0x%tx", __FILE__, __LINE__, __func__, (uintptr_t)(const void *)(parent_ptr))

Register a buffer domain with automatic format specifier.

Parameters
poolbuffer domain pointer
nameBase name string

Convenience macro that automatically uses "0x%tx" format specifier for buffer domain addresses.

Definition at line 602 of file debug/named.h.

602#define NAMED_REGISTER_BUFFER_DOMAIN(pool, name, parent_ptr) \
603 named_register((uintptr_t)(const void *)(pool), (name), "buffer_domain", "0x%tx", __FILE__, __LINE__, __func__, (uintptr_t)(const void *)(parent_ptr))

◆ NAMED_REGISTER_CLIENT

#define NAMED_REGISTER_CLIENT ( client,
name,
parent_ptr )

#include <include/ascii-chat/debug/named.h>

Value:
named_register((uintptr_t)(const void *)(client), (name), "client", "0x%tx", __FILE__, __LINE__, __func__, (uintptr_t)(const void *)(parent_ptr))

Register a client connection with automatic format specifier.

Parameters
clientClient pointer
nameBase name string

Convenience macro that automatically uses "0x%tx" format specifier for client addresses.

Definition at line 504 of file debug/named.h.

504#define NAMED_REGISTER_CLIENT(client, name, parent_ptr) \
505 named_register((uintptr_t)(const void *)(client), (name), "client", "0x%tx", __FILE__, __LINE__, __func__, (uintptr_t)(const void *)(parent_ptr))

◆ NAMED_REGISTER_CLIENT_AUDIO_PIPELINE

#define NAMED_REGISTER_CLIENT_AUDIO_PIPELINE ( pipeline,
name,
parent_ptr )

#include <include/ascii-chat/debug/named.h>

Value:
named_register((uintptr_t)(const void *)(pipeline), (name), "client_audio_pipeline", "0x%tx", __FILE__, __LINE__, __func__, (uintptr_t)(const void *)(parent_ptr))

Register a client audio pipeline with automatic format specifier.

Parameters
pipelineClient audio pipeline pointer
nameBase name string

Definition at line 955 of file debug/named.h.

955#define NAMED_REGISTER_CLIENT_AUDIO_PIPELINE(pipeline, name, parent_ptr) \
956 named_register((uintptr_t)(const void *)(pipeline), (name), "client_audio_pipeline", "0x%tx", __FILE__, __LINE__, __func__, (uintptr_t)(const void *)(parent_ptr))

Referenced by client_audio_pipeline_create().

◆ NAMED_REGISTER_COND

#define NAMED_REGISTER_COND ( cond,
name,
parent_ptr )

#include <include/ascii-chat/debug/named.h>

Value:
named_register((uintptr_t)(const void *)(cond), (name), "cond", "0x%tx", __FILE__, __LINE__, __func__, (uintptr_t)(const void *)(parent_ptr))

Register a condition variable with automatic format specifier.

Parameters
condCondition variable pointer
nameBase name string

Convenience macro that automatically uses "0x%tx" format specifier for cond addresses.

Definition at line 450 of file debug/named.h.

Referenced by audio_init(), and thread_pool_create_with_workers().

◆ NAMED_REGISTER_CONTEXT

#define NAMED_REGISTER_CONTEXT ( context,
context_type,
name,
parent_ptr )

#include <include/ascii-chat/debug/named.h>

Value:
named_register((uintptr_t)(const void *)(context), (name), (context_type), "0x%tx", __FILE__, __LINE__, __func__, (uintptr_t)(const void *)(parent_ptr))

Register a generic context with automatic format specifier.

Parameters
contextAny context pointer
context_typeType string (e.g., "ssl_context", "decoder_context")
nameBase name string

Convenience macro for naming any opaque context. Automatically uses "0x%tx" format. Usage: NAMED_REGISTER_CONTEXT(ctx, "ssl_context", "tls_server");

Definition at line 1041 of file debug/named.h.

1041#define NAMED_REGISTER_CONTEXT(context, context_type, name, parent_ptr) \
1042 named_register((uintptr_t)(const void *)(context), (name), (context_type), "0x%tx", __FILE__, __LINE__, __func__, (uintptr_t)(const void *)(parent_ptr))

Referenced by asciichat_mdns_init(), opus_codec_create_decoder_channels(), opus_codec_create_encoder_channels(), and render_file_create().

◆ NAMED_REGISTER_CRYPTO_CONTEXT

#define NAMED_REGISTER_CRYPTO_CONTEXT ( ctx,
name,
parent_ptr )

#include <include/ascii-chat/debug/named.h>

Value:
named_register((uintptr_t)(const void *)(ctx), (name), "crypto", "0x%tx", __FILE__, __LINE__, __func__, (uintptr_t)(const void *)(parent_ptr))

Register a crypto context with automatic format specifier.

Parameters
ctxCrypto context pointer
nameBase name string (typically "crypto_client_<id>")

Convenience macro that automatically uses "0x%tx" format specifier for crypto context addresses.

Definition at line 515 of file debug/named.h.

515#define NAMED_REGISTER_CRYPTO_CONTEXT(ctx, name, parent_ptr) \
516 named_register((uintptr_t)(const void *)(ctx), (name), "crypto", "0x%tx", __FILE__, __LINE__, __func__, (uintptr_t)(const void *)(parent_ptr))

Referenced by crypto_handshake_init(), and crypto_handshake_init_with_password().

◆ NAMED_REGISTER_DATACHANNEL

#define NAMED_REGISTER_DATACHANNEL ( datachannel,
name,
parent_ptr )

#include <include/ascii-chat/debug/named.h>

Value:
named_register((uintptr_t)(const void *)(datachannel), (name), "datachannel", "0x%tx", __FILE__, __LINE__, __func__, (uintptr_t)(const void *)(parent_ptr))

Register a data channel with automatic format specifier.

Parameters
datachannelData channel pointer
nameBase name string

Convenience macro that automatically uses "0x%tx" format specifier for datachannel addresses.

Definition at line 482 of file debug/named.h.

482#define NAMED_REGISTER_DATACHANNEL(datachannel, name, parent_ptr) \
483 named_register((uintptr_t)(const void *)(datachannel), (name), "datachannel", "0x%tx", __FILE__, __LINE__, __func__, (uintptr_t)(const void *)(parent_ptr))

Referenced by webrtc_create_datachannel().

◆ NAMED_REGISTER_FD

#define NAMED_REGISTER_FD ( fd,
name )

#include <include/ascii-chat/debug/named.h>

Value:
named_register_fd((fd), (name), __FILE__, __LINE__, __func__)
const char * named_register_fd(int fd, const char *name, const char *file, int line, const char *func)
Register a file descriptor with namespace encoding.

Register an existing file descriptor.

Parameters
fdFile descriptor (must be >= 0)
nameHuman-readable name for the fd (e.g., "inhibit"), or NULL for auto-generated

Convenience macro for registering file descriptors that are already open. If name is non-NULL, registers as "name (fd=N)"; otherwise uses "fd=N". In release builds (NDEBUG), this is a no-op.

Definition at line 744 of file debug/named.h.

Referenced by platform_fopen(), and platform_open().

◆ NAMED_REGISTER_FFMPEG_CONTEXT

#define NAMED_REGISTER_FFMPEG_CONTEXT ( context,
name,
parent_ptr )

#include <include/ascii-chat/debug/named.h>

Value:
named_register((uintptr_t)(const void *)(context), (name), "ffmpeg_context", "0x%tx", __FILE__, __LINE__, __func__, (uintptr_t)(const void *)(parent_ptr))

Register an FFmpeg decoder context with automatic format specifier.

Parameters
contextFFmpeg context pointer (AVFormatContext * or similar)
nameBase name string (e.g., "ffmpeg_decoder")

Convenience macro for naming FFmpeg contexts. Automatically uses "0x%tx" format. Usage: NAMED_REGISTER_FFMPEG_CONTEXT(avctx, "ffmpeg_input");

Definition at line 1028 of file debug/named.h.

1028#define NAMED_REGISTER_FFMPEG_CONTEXT(context, name, parent_ptr) \
1029 named_register((uintptr_t)(const void *)(context), (name), "ffmpeg_context", "0x%tx", __FILE__, __LINE__, __func__, (uintptr_t)(const void *)(parent_ptr))

◆ NAMED_REGISTER_FFMPEG_DECODER

#define NAMED_REGISTER_FFMPEG_DECODER ( decoder,
name,
parent_ptr )

#include <include/ascii-chat/debug/named.h>

Value:
named_register((uintptr_t)(const void *)(decoder), (name), "ffmpeg_decoder", "0x%tx", __FILE__, __LINE__, __func__, (uintptr_t)(const void *)(parent_ptr))

Register an FFmpeg decoder with automatic format specifier.

Parameters
decoderFFmpeg decoder pointer
nameBase name string

Convenience macro that automatically uses "0x%tx" format specifier for decoder addresses.

Definition at line 613 of file debug/named.h.

613#define NAMED_REGISTER_FFMPEG_DECODER(decoder, name, parent_ptr) \
614 named_register((uintptr_t)(const void *)(decoder), (name), "ffmpeg_decoder", "0x%tx", __FILE__, __LINE__, __func__, (uintptr_t)(const void *)(parent_ptr))

Referenced by ffmpeg_decoder_create_stdin(), and ffmpeg_decoder_create_with_request_options().

◆ NAMED_REGISTER_FFMPEG_ENCODER

#define NAMED_REGISTER_FFMPEG_ENCODER ( encoder,
name,
parent_ptr )

#include <include/ascii-chat/debug/named.h>

Value:
named_register((uintptr_t)(const void *)(encoder), (name), "ffmpeg_encoder", "0x%tx", __FILE__, __LINE__, __func__, (uintptr_t)(const void *)(parent_ptr))

Register an FFmpeg encoder with automatic format specifier.

Parameters
encoderFFmpeg encoder pointer
nameBase name string
parent_ptrParent context pointer (uintptr_t cast)

Convenience macro that automatically uses "0x%tx" format specifier for encoder addresses.

Definition at line 625 of file debug/named.h.

625#define NAMED_REGISTER_FFMPEG_ENCODER(encoder, name, parent_ptr) \
626 named_register((uintptr_t)(const void *)(encoder), (name), "ffmpeg_encoder", "0x%tx", __FILE__, __LINE__, __func__, (uintptr_t)(const void *)(parent_ptr))

Referenced by ffmpeg_encoder_create_scaled().

◆ NAMED_REGISTER_FMT

#define NAMED_REGISTER_FMT ( ptr,
type,
fmt_spec,
fmt,
... )

#include <include/ascii-chat/debug/named.h>

Value:
named_register_fmt((uintptr_t)(const void *)(ptr), (type), (fmt_spec), __FILE__, __LINE__, __func__, (fmt), __VA_ARGS__)
const char * named_register_fmt(uintptr_t key, const char *type, const char *format_spec, const char *file, int line, const char *func, const char *fmt,...)
Register a resource with a formatted name, type, and location info (no auto-suffix).

Register with a formatted name, type, and format spec.

Parameters
ptrObject pointer
typeData type label
fmt_specFormat specifier for printing (e.g., "0x%tx")
fmtPrintf-style format string for name
...Format arguments

In debug builds, automatically captures FILE, LINE, and func for location info. In release builds (NDEBUG), this is a no-op.

Definition at line 359 of file debug/named.h.

◆ NAMED_REGISTER_FRAME_BUFFER

#define NAMED_REGISTER_FRAME_BUFFER ( buf,
name,
parent_ptr )

#include <include/ascii-chat/debug/named.h>

Value:
named_register((uintptr_t)(const void *)(buf), (name), "frame_buffer", "0x%tx", __FILE__, __LINE__, __func__, (uintptr_t)(const void *)(parent_ptr))

Register a frame buffer with automatic format specifier.

Parameters
bufFrame buffer pointer
nameBase name string

Convenience macro that automatically uses "0x%tx" format specifier for frame buffer addresses.

Definition at line 537 of file debug/named.h.

537#define NAMED_REGISTER_FRAME_BUFFER(buf, name, parent_ptr) \
538 named_register((uintptr_t)(const void *)(buf), (name), "frame_buffer", "0x%tx", __FILE__, __LINE__, __func__, (uintptr_t)(const void *)(parent_ptr))

◆ NAMED_REGISTER_H265_DECODER

#define NAMED_REGISTER_H265_DECODER ( decoder,
name,
parent_ptr )

#include <include/ascii-chat/debug/named.h>

Value:
named_register((uintptr_t)(const void *)(decoder), (name), "h265_decoder", "0x%tx", __FILE__, __LINE__, __func__, (uintptr_t)(const void *)(parent_ptr))

Register an H.265 decoder with automatic format specifier.

Parameters
decoderH.265 decoder pointer
nameBase name string
parent_ptrParent context pointer (uintptr_t cast)

Convenience macro that automatically uses "0x%tx" format specifier for H.265 decoder addresses.

Definition at line 649 of file debug/named.h.

649#define NAMED_REGISTER_H265_DECODER(decoder, name, parent_ptr) \
650 named_register((uintptr_t)(const void *)(decoder), (name), "h265_decoder", "0x%tx", __FILE__, __LINE__, __func__, (uintptr_t)(const void *)(parent_ptr))

Referenced by h265_decoder_create().

◆ NAMED_REGISTER_H265_ENCODER

#define NAMED_REGISTER_H265_ENCODER ( encoder,
name,
parent_ptr )

#include <include/ascii-chat/debug/named.h>

Value:
named_register((uintptr_t)(const void *)(encoder), (name), "h265_encoder", "0x%tx", __FILE__, __LINE__, __func__, (uintptr_t)(const void *)(parent_ptr))

Register an H.265 encoder with automatic format specifier.

Parameters
encoderH.265 encoder pointer
nameBase name string
parent_ptrParent context pointer (uintptr_t cast)

Convenience macro that automatically uses "0x%tx" format specifier for H.265 encoder addresses.

Definition at line 637 of file debug/named.h.

637#define NAMED_REGISTER_H265_ENCODER(encoder, name, parent_ptr) \
638 named_register((uintptr_t)(const void *)(encoder), (name), "h265_encoder", "0x%tx", __FILE__, __LINE__, __func__, (uintptr_t)(const void *)(parent_ptr))

Referenced by video_encoder_create().

◆ NAMED_REGISTER_ID

#define NAMED_REGISTER_ID ( id,
name,
type,
fmt,
parent_ptr )

#include <include/ascii-chat/debug/named.h>

Value:
named_register((uintptr_t)(intptr_t)(id), (name), (type), (fmt), __FILE__, __LINE__, __func__, (uintptr_t)(const void *)(parent_ptr))

Register an integer handle (fd, socket, etc.) with type.

Parameters
idInteger handle (socket_t, int, etc.)
nameBase name string
typeData type label (e.g., "socket", "fd")

In debug builds, automatically captures FILE, LINE, and func for location info. In release builds (NDEBUG), this is a no-op.

Definition at line 397 of file debug/named.h.

◆ NAMED_REGISTER_LWS_CONTEXT

#define NAMED_REGISTER_LWS_CONTEXT ( context,
name,
parent_ptr )

#include <include/ascii-chat/debug/named.h>

Value:
named_register((uintptr_t)(const void *)(context), (name), "lws_context", "0x%tx", __FILE__, __LINE__, __func__, (uintptr_t)(const void *)(parent_ptr))

Register a libwebsockets context with automatic format specifier.

Parameters
contextLWS context pointer (struct lws_context *)
nameBase name string (e.g., "ws_server" or "ws_client")

Convenience macro for naming libwebsockets contexts. Automatically uses "0x%tx" format. Usage: NAMED_REGISTER_LWS_CONTEXT(lws_ctx, "ws_server");

Definition at line 1016 of file debug/named.h.

1016#define NAMED_REGISTER_LWS_CONTEXT(context, name, parent_ptr) \
1017 named_register((uintptr_t)(const void *)(context), (name), "lws_context", "0x%tx", __FILE__, __LINE__, __func__, (uintptr_t)(const void *)(parent_ptr))

◆ NAMED_REGISTER_MEDIA_SOURCE

#define NAMED_REGISTER_MEDIA_SOURCE ( source,
name,
parent_ptr )

#include <include/ascii-chat/debug/named.h>

Value:
named_register((uintptr_t)(const void *)(source), (name), "media_source", "0x%tx", __FILE__, __LINE__, __func__, (uintptr_t)(const void *)(parent_ptr))
audio_visualization_source_t source
Definition fft.c:25

Register a media source with automatic format specifier.

Parameters
sourceMedia source pointer
nameBase name string

Convenience macro that automatically uses "0x%tx" format specifier for media source addresses.

Definition at line 693 of file debug/named.h.

693#define NAMED_REGISTER_MEDIA_SOURCE(source, name, parent_ptr) \
694 named_register((uintptr_t)(const void *)(source), (name), "media_source", "0x%tx", __FILE__, __LINE__, __func__, (uintptr_t)(const void *)(parent_ptr))

◆ NAMED_REGISTER_MIXER

#define NAMED_REGISTER_MIXER ( mixer,
name,
parent_ptr )

#include <include/ascii-chat/debug/named.h>

Value:
named_register((uintptr_t)(const void *)(mixer), (name), "mixer", "0x%tx", __FILE__, __LINE__, __func__, (uintptr_t)(const void *)(parent_ptr))

Register an audio mixer with automatic format specifier.

Parameters
mixerMixer pointer
nameBase name string

Convenience macro that automatically uses "0x%tx" format specifier for mixer addresses.

Definition at line 570 of file debug/named.h.

Referenced by mixer_create_channels().

◆ NAMED_REGISTER_MUTEX

#define NAMED_REGISTER_MUTEX ( mutex,
name,
parent_ptr )

#include <include/ascii-chat/debug/named.h>

Value:
named_register((uintptr_t)(const void *)(mutex), (name), "mutex", "0x%tx", __FILE__, __LINE__, __func__, (uintptr_t)(const void *)(parent_ptr))

Register a mutex with automatic format specifier.

Parameters
mutexMutex pointer
nameBase name string

Convenience macro that automatically uses "0x%tx" format specifier for mutex addresses.

Definition at line 426 of file debug/named.h.

Referenced by audio_init(), audio_visualization_fft_init(), colorscheme_init(), media_source_create_interruptible(), spectral_create(), thread_pool_create(), and thread_pool_create_with_workers().

◆ NAMED_REGISTER_OPTIONS_BUILDER

#define NAMED_REGISTER_OPTIONS_BUILDER ( builder,
name,
parent_ptr )

#include <include/ascii-chat/debug/named.h>

Value:
named_register((uintptr_t)(const void *)(builder), (name), "options_builder", "0x%tx", __FILE__, __LINE__, __func__, (uintptr_t)(const void *)(parent_ptr))

Register an options builder with automatic format specifier.

Parameters
builderOptions builder pointer
nameBase name string

Definition at line 937 of file debug/named.h.

937#define NAMED_REGISTER_OPTIONS_BUILDER(builder, name, parent_ptr) \
938 named_register((uintptr_t)(const void *)(builder), (name), "options_builder", "0x%tx", __FILE__, __LINE__, __func__, (uintptr_t)(const void *)(parent_ptr))

◆ NAMED_REGISTER_PACKET_QUEUE

#define NAMED_REGISTER_PACKET_QUEUE ( queue,
name,
parent_ptr )

#include <include/ascii-chat/debug/named.h>

Value:
named_register((uintptr_t)(const void *)(queue), (name), "packet_queue", "0x%tx", __FILE__, __LINE__, __func__, (uintptr_t)(const void *)(parent_ptr))

Register a packet queue with automatic format specifier.

Parameters
queuePacket queue pointer
nameBase name string

Convenience macro that automatically uses "0x%tx" format specifier for packet queue addresses.

Definition at line 548 of file debug/named.h.

548#define NAMED_REGISTER_PACKET_QUEUE(queue, name, parent_ptr) \
549 named_register((uintptr_t)(const void *)(queue), (name), "packet_queue", "0x%tx", __FILE__, __LINE__, __func__, (uintptr_t)(const void *)(parent_ptr))

◆ NAMED_REGISTER_RATE_LIMITER

#define NAMED_REGISTER_RATE_LIMITER ( limiter,
name,
parent_ptr )

#include <include/ascii-chat/debug/named.h>

Value:
named_register((uintptr_t)(const void *)(limiter), (name), "rate_limiter", "0x%tx", __FILE__, __LINE__, __func__, (uintptr_t)(const void *)(parent_ptr))

Register a rate limiter with automatic format specifier.

Parameters
limiterRate limiter pointer
nameBase name string

Convenience macro that automatically uses "0x%tx" format specifier for rate limiter addresses.

Definition at line 671 of file debug/named.h.

671#define NAMED_REGISTER_RATE_LIMITER(limiter, name, parent_ptr) \
672 named_register((uintptr_t)(const void *)(limiter), (name), "rate_limiter", "0x%tx", __FILE__, __LINE__, __func__, (uintptr_t)(const void *)(parent_ptr))

◆ NAMED_REGISTER_RWLOCK

#define NAMED_REGISTER_RWLOCK ( lock,
name,
parent_ptr )

#include <include/ascii-chat/debug/named.h>

Value:
named_register((uintptr_t)(const void *)(lock), (name), "rwlock", "0x%tx", __FILE__, __LINE__, __func__, (uintptr_t)(const void *)(parent_ptr))

Register an rwlock with automatic format specifier.

Parameters
lockRWLock pointer
nameBase name string

Convenience macro that automatically uses "0x%tx" format specifier for rwlock addresses.

Definition at line 437 of file debug/named.h.

Referenced by mixer_create_channels().

◆ NAMED_REGISTER_SIMPLE_FRAME_SWAP

#define NAMED_REGISTER_SIMPLE_FRAME_SWAP ( swap,
name,
parent_ptr )

#include <include/ascii-chat/debug/named.h>

Value:
named_register((uintptr_t)(const void *)(swap), (name), "simple_frame_swap", "0x%tx", __FILE__, __LINE__, __func__, (uintptr_t)(const void *)(parent_ptr))

Register a simple frame swap with automatic format specifier.

Parameters
swapSimple frame swap pointer
nameBase name string

Definition at line 946 of file debug/named.h.

946#define NAMED_REGISTER_SIMPLE_FRAME_SWAP(swap, name, parent_ptr) \
947 named_register((uintptr_t)(const void *)(swap), (name), "simple_frame_swap", "0x%tx", __FILE__, __LINE__, __func__, (uintptr_t)(const void *)(parent_ptr))

◆ NAMED_REGISTER_SOCKET

#define NAMED_REGISTER_SOCKET ( socket,
name,
parent_ptr )

#include <include/ascii-chat/debug/named.h>

Value:
named_register((uintptr_t)(intptr_t)(socket), (name), "socket", "0x%tx", __FILE__, __LINE__, __func__, (uintptr_t)(const void *)(parent_ptr))

Register a socket with automatic format specifier.

Parameters
socketSocket pointer
nameBase name string

Convenience macro that automatically uses "0x%tx" format specifier for socket addresses.

Definition at line 460 of file debug/named.h.

◆ NAMED_REGISTER_TCP_CLIENT

#define NAMED_REGISTER_TCP_CLIENT ( client,
name,
parent_ptr )

#include <include/ascii-chat/debug/named.h>

Value:
named_register((uintptr_t)(const void *)(client), (name), "tcp_client", "0x%tx", __FILE__, __LINE__, __func__, (uintptr_t)(const void *)(parent_ptr))

Register a TCP client with automatic format specifier.

Parameters
clientTCP client pointer
nameBase name string

Definition at line 892 of file debug/named.h.

892#define NAMED_REGISTER_TCP_CLIENT(client, name, parent_ptr) \
893 named_register((uintptr_t)(const void *)(client), (name), "tcp_client", "0x%tx", __FILE__, __LINE__, __func__, (uintptr_t)(const void *)(parent_ptr))

◆ NAMED_REGISTER_THREAD

#define NAMED_REGISTER_THREAD ( thread,
name,
parent_ptr )

#include <include/ascii-chat/debug/named.h>

Value:
named_register(thread_to_key((thread)), (name), "thread", "0x%tx", __FILE__, __LINE__, __func__, (uintptr_t)(const void *)(parent_ptr))
uintptr_t thread_to_key(platform_thread_t thread)
Convert a thread handle to a registry key.

Register a thread handle with name and automatic format specifier.

Parameters
threadplatform_thread_t handle (NOT a pointer)
nameBase name string

Convenience macro that automatically uses "0x%tx" format specifier for thread addresses. In debug builds, automatically captures FILE, LINE, and func for location info. The thread handle itself (not a pointer) is used as the registry key. In release builds (NDEBUG), this is a no-op.

Definition at line 781 of file debug/named.h.

Referenced by main().

◆ NAMED_REGISTER_THREAD_POOL

#define NAMED_REGISTER_THREAD_POOL ( pool,
name,
parent_ptr )

#include <include/ascii-chat/debug/named.h>

Value:
named_register((uintptr_t)(const void *)(pool), (name), "thread_pool", "0x%tx", __FILE__, __LINE__, __func__, (uintptr_t)(const void *)(parent_ptr))

Register a thread pool with automatic format specifier.

Parameters
poolThread pool pointer
nameBase name string

Definition at line 928 of file debug/named.h.

928#define NAMED_REGISTER_THREAD_POOL(pool, name, parent_ptr) \
929 named_register((uintptr_t)(const void *)(pool), (name), "thread_pool", "0x%tx", __FILE__, __LINE__, __func__, (uintptr_t)(const void *)(parent_ptr))

Referenced by thread_pool_create(), and thread_pool_create_with_workers().

◆ NAMED_REGISTER_THREADPOOL_WORK

#define NAMED_REGISTER_THREADPOOL_WORK ( work,
name,
parent_ptr )

#include <include/ascii-chat/debug/named.h>

Value:
named_register((uintptr_t)(const void *)(work), (name), "work", "0x%tx", __FILE__, __LINE__, __func__, (uintptr_t)(const void *)(parent_ptr))

Register a thread pool work item with automatic format specifier.

Parameters
workWork item pointer
nameBase name string

Convenience macro that automatically uses "0x%tx" format specifier for work item addresses.

Definition at line 493 of file debug/named.h.

493#define NAMED_REGISTER_THREADPOOL_WORK(work, name, parent_ptr) \
494 named_register((uintptr_t)(const void *)(work), (name), "work", "0x%tx", __FILE__, __LINE__, __func__, (uintptr_t)(const void *)(parent_ptr))

Referenced by thread_pool_queue_work().

◆ NAMED_REGISTER_TRANSPORT

#define NAMED_REGISTER_TRANSPORT ( transport,
name,
parent_ptr )

#include <include/ascii-chat/debug/named.h>

Value:
named_register((uintptr_t)(const void *)(transport), (name), "transport", "0x%tx", __FILE__, __LINE__, __func__, (uintptr_t)(const void *)(parent_ptr))

Register a transport with automatic format specifier.

Parameters
transportTransport pointer
nameBase name string (typically "transport_client_<id>" or "transport_tcp_<id>")

Convenience macro that automatically uses "0x%tx" format specifier for transport addresses.

Definition at line 526 of file debug/named.h.

526#define NAMED_REGISTER_TRANSPORT(transport, name, parent_ptr) \
527 named_register((uintptr_t)(const void *)(transport), (name), "transport", "0x%tx", __FILE__, __LINE__, __func__, (uintptr_t)(const void *)(parent_ptr))

Referenced by acip_tcp_transport_create(), acip_websocket_client_transport_create(), and acip_websocket_server_transport_create().

◆ NAMED_REGISTER_VIDEO_ENCODER

#define NAMED_REGISTER_VIDEO_ENCODER ( encoder,
name,
parent_ptr )

#include <include/ascii-chat/debug/named.h>

Value:
named_register((uintptr_t)(const void *)(encoder), (name), "video_encoder", "0x%tx", __FILE__, __LINE__, __func__, (uintptr_t)(const void *)(parent_ptr))

Register a video encoder with automatic format specifier.

Parameters
encoderVideo encoder pointer
nameBase name string

Convenience macro that automatically uses "0x%tx" format specifier for video encoder addresses.

Definition at line 591 of file debug/named.h.

591#define NAMED_REGISTER_VIDEO_ENCODER(encoder, name, parent_ptr) \
592 named_register((uintptr_t)(const void *)(encoder), (name), "video_encoder", "0x%tx", __FILE__, __LINE__, __func__, (uintptr_t)(const void *)(parent_ptr))

◆ NAMED_REGISTER_VIDEO_FRAME_BUFFER

#define NAMED_REGISTER_VIDEO_FRAME_BUFFER ( buf,
name,
parent_ptr )

#include <include/ascii-chat/debug/named.h>

Value:
named_register((uintptr_t)(const void *)(buf), (name), "video_frame_buffer", "0x%tx", __FILE__, __LINE__, __func__, (uintptr_t)(const void *)(parent_ptr))

Register a video frame buffer with automatic format specifier.

Parameters
bufVideo frame buffer pointer
nameBase name string

Definition at line 919 of file debug/named.h.

919#define NAMED_REGISTER_VIDEO_FRAME_BUFFER(buf, name, parent_ptr) \
920 named_register((uintptr_t)(const void *)(buf), (name), "video_frame_buffer", "0x%tx", __FILE__, __LINE__, __func__, (uintptr_t)(const void *)(parent_ptr))

Referenced by video_frame_buffer_create().

◆ NAMED_REGISTER_WAV_WRITER

#define NAMED_REGISTER_WAV_WRITER ( writer,
name,
parent_ptr )

#include <include/ascii-chat/debug/named.h>

Value:
named_register((uintptr_t)(const void *)(writer), (name), "wav_writer", "0x%tx", __FILE__, __LINE__, __func__, (uintptr_t)(const void *)(parent_ptr))

Register a WAV writer with automatic format specifier.

Parameters
writerWAV writer pointer
nameBase name string

Convenience macro that automatically uses "0x%tx" format specifier for WAV writer addresses.

Definition at line 682 of file debug/named.h.

682#define NAMED_REGISTER_WAV_WRITER(writer, name, parent_ptr) \
683 named_register((uintptr_t)(const void *)(writer), (name), "wav_writer", "0x%tx", __FILE__, __LINE__, __func__, (uintptr_t)(const void *)(parent_ptr))

◆ NAMED_REGISTER_WEBSOCKET

#define NAMED_REGISTER_WEBSOCKET ( websocket,
name,
parent_ptr )

#include <include/ascii-chat/debug/named.h>

Value:
named_register((uintptr_t)(const void *)(websocket), (name), "websocket", "0x%tx", __FILE__, __LINE__, __func__, (uintptr_t)(const void *)(parent_ptr))

Register a WebSocket connection with automatic format specifier.

Parameters
websocketWebSocket pointer
nameBase name string

Convenience macro that automatically uses "0x%tx" format specifier for websocket addresses.

Definition at line 471 of file debug/named.h.

471#define NAMED_REGISTER_WEBSOCKET(websocket, name, parent_ptr) \
472 named_register((uintptr_t)(const void *)(websocket), (name), "websocket", "0x%tx", __FILE__, __LINE__, __func__, (uintptr_t)(const void *)(parent_ptr))

Referenced by websocket_server_init().

◆ NAMED_REGISTER_WEBSOCKET_CLIENT

#define NAMED_REGISTER_WEBSOCKET_CLIENT ( client,
name,
parent_ptr )

#include <include/ascii-chat/debug/named.h>

Value:
named_register((uintptr_t)(const void *)(client), (name), "websocket_client", "0x%tx", __FILE__, __LINE__, __func__, (uintptr_t)(const void *)(parent_ptr))

Register a WebSocket client with automatic format specifier.

Parameters
clientWebSocket client pointer
nameBase name string

Definition at line 901 of file debug/named.h.

901#define NAMED_REGISTER_WEBSOCKET_CLIENT(client, name, parent_ptr) \
902 named_register((uintptr_t)(const void *)(client), (name), "websocket_client", "0x%tx", __FILE__, __LINE__, __func__, (uintptr_t)(const void *)(parent_ptr))

◆ NAMED_REGISTER_WEBSOCKET_IMPL

#define NAMED_REGISTER_WEBSOCKET_IMPL ( data,
name,
parent_ptr )

#include <include/ascii-chat/debug/named.h>

Value:
((void)(data), (void)(name), (void)(parent_ptr))

Definition at line 962 of file debug/named.h.

Referenced by acip_websocket_client_transport_create(), and acip_websocket_server_transport_create().

◆ NAMED_UNREGISTER

◆ NAMED_UNREGISTER_FD

#define NAMED_UNREGISTER_FD ( fd)

#include <include/ascii-chat/debug/named.h>

Value:
#define NAMED_UNREGISTER_ID(id)
Unregister an integer handle.

Unregister a file descriptor.

Parameters
fdFile descriptor to unregister

Call this before closing a named file descriptor.

Definition at line 732 of file debug/named.h.

◆ NAMED_UNREGISTER_ID

#define NAMED_UNREGISTER_ID ( id)

#include <include/ascii-chat/debug/named.h>

Value:
named_unregister((uintptr_t)(intptr_t)(id))

Unregister an integer handle.

Parameters
idInteger handle

Definition at line 404 of file debug/named.h.

◆ NAMED_UNREGISTER_SOCKET

#define NAMED_UNREGISTER_SOCKET ( socket)

#include <include/ascii-chat/debug/named.h>

Value:

Definition at line 461 of file debug/named.h.

◆ NAMED_UNREGISTER_THREAD

#define NAMED_UNREGISTER_THREAD ( thread)

#include <include/ascii-chat/debug/named.h>

Value:

Unregister a thread handle.

Parameters
threadplatform_thread_t handle (NOT a pointer)

Definition at line 788 of file debug/named.h.

Typedef Documentation

◆ named_iter_callback_t

typedef void(* named_iter_callback_t) (uintptr_t key, const char *name, void *user_data)

#include <include/ascii-chat/debug/named.h>

Callback function for iterating registered entries.

Parameters
keyThe registered key (uintptr_t)
nameThe registered name string
user_dataUser-provided context pointer

Called for each entry in the registry. The callback should not modify the registry during iteration.

Definition at line 884 of file debug/named.h.

◆ named_snapshot_fn

typedef void(* named_snapshot_fn) (uintptr_t key, uint64_t generation, const char *name, const char *type, const char *file, int line, void *data)

#include <include/ascii-chat/debug/named.h>

Nonblocking protected visit. Callbacks may only copy data (no logging, allocation, or registry calls). If capacity is insufficient, no callbacks run; required receives the current size. Objects must unregister before free.

Definition at line 1004 of file debug/named.h.

Function Documentation

◆ debug_sync_check_cond_deadlocks()

void debug_sync_check_cond_deadlocks ( void )

#include <lib/debug/mutex.c>

The useful part of cond deadlock batch is in entries, count: together they describe what is pending, who owns it, and how much data is valid. Keep the object with its parent operation and use the parent cleanup path.

Check all condition variables for deadlocks

Scans all registered condition variables and logs warnings for any that have been waiting without signal for longer than COND_DEADLOCK_THRESHOLD_NS. The debug thread polls this deadline every 100ms. A new wait cannot become stuck before the five-second threshold, so healthy conditions need no registry scans between deadlines. Existing waits set an earlier deadline.

Skips checks during shutdown to avoid accessing freed memory.

Definition at line 877 of file mutex.c.

877 {
879 return;
880 }
881 uint64_t now = time_get_ns();
882 if (now < atomic_load(&g_next_cond_check_ns))
883 return;
884 bool completed = false;
885 size_t required = 0;
886 cond_deadlock_batch_t batch = {0};
887 if (named_registry_try_snapshot(0, &required, &completed, copy_cond_deadlock_entry, &batch) != ASCIICHAT_OK || !required || required > SIZE_MAX / sizeof(*batch.entries))
888 return;
889 // Registry metadata must not re-enter allocation tracking. Object state and
890 // names are copied while pinned, and diagnostics run after releasing the lock.
891 batch.entries = UNTRACKED_MALLOC(required * sizeof(*batch.entries), cond_deadlock_entry_t *);
892 if (!batch.entries)
893 return;
894 size_t capacity = required;
895 if (named_registry_try_snapshot(capacity, &required, &completed, copy_cond_deadlock_entry, &batch) == ASCIICHAT_OK && completed) {
897 for (size_t i = 0; i < batch.count; ++i) {
898 const cond_deadlock_snapshot_t *state = &batch.entries[i].state;
899 const char *name = batch.entries[i].name;
900 cond_deadlock_check_snapshot(state, name);
901 if (state->waiting_count && !strstr(name, "task_available") && !strstr(name, "work_available")) {
903 // A recent signal already rules out this wait. Repeated warnings for
904 // an actually stuck condition retain their existing 500 ms cadence.
905 if (state->last_signal_time_ns < state->last_wait_time_ns || !state->last_signal_time_ns) {
906 if (due <= now)
907 due = now + 500 * NS_PER_MS_INT;
908 if (due < next)
909 next = due;
910 }
911 }
912 }
913 atomic_store(&g_next_cond_check_ns, next);
914 }
915 UNTRACKED_FREE(batch.entries);
916}
#define UNTRACKED_FREE(ptr)
#define UNTRACKED_MALLOC(size, cast)
asciichat_error_t named_registry_try_snapshot(size_t capacity, size_t *required, bool *completed, named_snapshot_fn copy, void *data)
#define NS_PER_MS_INT
Definition time.h:172
bool debug_sync_is_cleanup_in_progress(void)
#define COND_DEADLOCK_THRESHOLD_NS
Definition mutex.c:748
When code needs to work with cond deadlock entry, it keeps state here instead of scattering it across...
Definition mutex.c:843
cond_deadlock_entry_t * entries
Definition mutex.c:844
Definition mutex.c:831
cond_deadlock_snapshot_t state
Definition mutex.c:832
char name[256]
Definition mutex.c:833
deadlock state is intentionally a small, concrete record. Fields such as count give callers the ident...
Definition mutex.c:756
uint64_t last_signal_time_ns
Definition mutex.c:759
uint64_t last_wait_time_ns
Definition mutex.c:758

References ASCIICHAT_OK, COND_DEADLOCK_THRESHOLD_NS, cond_deadlock_batch_t::count, debug_sync_is_cleanup_in_progress(), cond_deadlock_batch_t::entries, cond_deadlock_snapshot_t::last_signal_time_ns, cond_deadlock_snapshot_t::last_wait_time_ns, cond_deadlock_entry_t::name, named_registry_try_snapshot(), NS_PER_MS_INT, cond_deadlock_entry_t::state, UNTRACKED_FREE, UNTRACKED_MALLOC, and cond_deadlock_snapshot_t::waiting_count.

◆ named_describe()

const char * named_describe ( uintptr_t key,
const char * type_hint )

#include <include/ascii-chat/debug/named.h>

Format a description string for logging.

Parameters
keyThe resource key
type_hintA type label (e.g., "mutex", "socket", "thread")
Returns
Description string in format "type_hint: name (0xKEY)" or type_hint if not registered

Returns a per-thread static buffer suitable for a single log call. The buffer is overwritten on the next call to this function within the same thread. Do not store or free the returned pointer.

If the key is not registered, returns just the type_hint. In release builds (NDEBUG), this always returns "?".

Definition at line 550 of file debug/named.c.

550 {
551 if (!type_hint)
552 type_hint = "object";
553
554 static _Thread_local char buffer[DESCRIBE_BUFFER_SIZE];
555
556 if (!lifecycle_is_initialized(&g_named_registry.lifecycle)) {
557 snprintf(buffer, sizeof(buffer), "%s (0x%tx)", type_hint, (ptrdiff_t)key);
558 return buffer;
559 }
560
561 rwlock_rdlock(&g_named_registry.entries_lock);
562 named_entry_t *entry = NULL;
563 HASH_FIND(hh, g_named_registry.entries, &key, sizeof(uintptr_t), entry);
564 rwlock_rdunlock(&g_named_registry.entries_lock);
565
566 if (entry) {
567 const char *type = entry->type ? entry->type : type_hint;
568 const char *name = entry->name ? entry->name : "unknown";
569 if (entry->file && entry->func && entry->line > 0) {
570 snprintf(buffer, sizeof(buffer), "%s/%s (0x%tx) @ %s:%d:%s()", type, name, (ptrdiff_t)key, entry->file, entry->line, entry->func);
571 } else {
572 snprintf(buffer, sizeof(buffer), "%s/%s (0x%tx)", type, name, (ptrdiff_t)key);
573 }
574 } else {
575 snprintf(buffer, sizeof(buffer), "%s (0x%tx)", type_hint ? type_hint : "unknown", (ptrdiff_t)key);
576 }
577
578 return buffer;
579}
#define DESCRIBE_BUFFER_SIZE
Definition debug/named.c:38
struct named_entry named_entry_t
Registry entry for uthash.
char * func
Definition debug/named.c:75
char * file
Definition debug/named.c:73
int line
Definition debug/named.c:74
char * name
Definition debug/named.c:70
char * type
Definition debug/named.c:71

References DESCRIBE_BUFFER_SIZE, named_entry::file, named_entry::func, named_entry::line, named_entry::name, and named_entry::type.

Referenced by named_describe_thread().

◆ named_describe_thread()

const char * named_describe_thread ( void * thread)

#include <include/ascii-chat/debug/named.h>

Describe a thread for logging (function wrapper).

Parameters
threadplatform_thread_t handle
Returns
Description string "thread: name (0xID)"

This is a function (not a macro) to handle the opaque platform_thread_t type properly, converting it through thread_to_key().

Definition at line 581 of file debug/named.c.

581 {
582 uintptr_t key = thread_to_key((platform_thread_t)thread);
583 return named_describe(key, "thread");
584}

References named_describe(), and thread_to_key().

◆ named_destroy()

void named_destroy ( void )

#include <include/ascii-chat/debug/named.h>

Destroy the named object registry.

Cleans up all registered names and internal structures. Typically called from lock_debug_destroy().

Definition at line 257 of file debug/named.c.

257 {
258 if (!lifecycle_shutdown(&g_named_registry.lifecycle))
259 return;
260 rwlock_wrlock(&g_named_registry.entries_lock);
261 named_entry_t *entry, *next;
262 HASH_ITER(hh, g_named_registry.entries, entry, next) {
263 // Remove each hash node so uthash releases its bucket storage as well.
264 // Unregistration is disabled after lifecycle shutdown, including for the
265 // registry lock itself; all entries must be freed here.
266 HASH_DEL(g_named_registry.entries, entry);
267 free(entry->name);
268 free(entry->type);
269 free(entry->format_spec);
270 free(entry->file);
271 free(entry->func);
272 free(entry);
273 }
274 g_named_registry.entries_lock.name = NULL;
275 atomic_fetch_add(&g_metadata_revision, 1);
276 rwlock_wrunlock(&g_named_registry.entries_lock);
277 rwlock_destroy(&g_named_registry.entries_lock);
278 if (g_metadata_tls_ready) {
279 void *cache = g_thread_metadata;
280 platform_tls_set(g_metadata_tls, NULL);
281 metadata_cache_destroy(cache);
282 platform_tls_key_delete(g_metadata_tls);
283 g_metadata_tls_ready = false;
284 }
285}
char * format_spec
Definition debug/named.c:72

References named_entry::file, named_entry::format_spec, named_entry::func, named_entry::name, and named_entry::type.

Referenced by asciichat_shared_destroy().

◆ named_fd_metadata_copy()

bool named_fd_metadata_copy ( int fd,
named_metadata_t * output )

#include <include/ascii-chat/debug/named.h>

Definition at line 711 of file debug/named.c.

711 {
712 return fd >= 0 && named_metadata_copy(encode_fd_key(fd), output);
713}
bool named_metadata_copy(uintptr_t key, named_metadata_t *output)

References named_metadata_copy().

Referenced by log_named_format_message().

◆ named_get()

const char * named_get ( uintptr_t key)

#include <include/ascii-chat/debug/named.h>

Look up the registered name for a resource.

Parameters
keyThe resource key
Returns
Registered name string, or NULL if not registered

Returns the name string registered with named_register() or named_register_fmt(), or NULL if the key is not in the registry.

In release builds (NDEBUG), this always returns NULL.

Definition at line 497 of file debug/named.c.

497 {
498 if (!lifecycle_is_initialized(&g_named_registry.lifecycle)) {
499 return NULL;
500 }
501
502 rwlock_rdlock(&g_named_registry.entries_lock);
503 named_entry_t *entry = NULL;
504 HASH_FIND(hh, g_named_registry.entries, &key, sizeof(uintptr_t), entry);
505 const char *result = entry ? entry->name : NULL;
506 rwlock_rdunlock(&g_named_registry.entries_lock);
507 return result;
508}

References named_entry::name.

◆ named_get_by_type_and_id()

const char * named_get_by_type_and_id ( const char * type_name,
size_t type_len,
int id )

#include <include/ascii-chat/debug/named.h>

Look up an integer ID by type name and value.

Parameters
type_nameType string (e.g., "socket", "client", "connection")
type_lenLength of type name
idInteger ID value to look up
Returns
Registered name string, or NULL if not found

Searches the registry for entries matching the given type and integer ID. Enables formatting of patterns like "socket 12" → "socket/server_listener (socket=12)". In release builds (NDEBUG), this always returns NULL.

Referenced by log_named_format_message().

◆ named_get_fd()

const char * named_get_fd ( int fd)

#include <include/ascii-chat/debug/named.h>

Look up a registered file descriptor.

Parameters
fdFile descriptor value
Returns
Registered name string, or NULL if not registered

Looks up an FD using the same namespace encoding as named_register_fd(). In release builds (NDEBUG), this always returns NULL.

Definition at line 754 of file debug/named.c.

754 {
755 if (fd < 0)
756 return NULL;
757
758 if (!lifecycle_is_initialized(&g_named_registry.lifecycle)) {
759 return NULL;
760 }
761
762 uintptr_t key = encode_fd_key(fd);
763 rwlock_rdlock(&g_named_registry.entries_lock);
764 named_entry_t *entry = NULL;
765 HASH_FIND(hh, g_named_registry.entries, &key, sizeof(uintptr_t), entry);
766 const char *result = entry ? entry->name : NULL;
767 rwlock_rdunlock(&g_named_registry.entries_lock);
768 return result;
769}

References named_entry::name.

◆ named_get_fd_format_spec()

const char * named_get_fd_format_spec ( int fd)

#include <include/ascii-chat/debug/named.h>

Get the format specifier for a registered file descriptor.

Parameters
fdFile descriptor value
Returns
Format specifier string (e.g., "%d"), or NULL if not registered

Definition at line 771 of file debug/named.c.

771 {
772 if (fd < 0)
773 return NULL;
774
775 if (!lifecycle_is_initialized(&g_named_registry.lifecycle)) {
776 return NULL;
777 }
778
779 uintptr_t key = encode_fd_key(fd);
780 rwlock_rdlock(&g_named_registry.entries_lock);
781 named_entry_t *entry = NULL;
782 HASH_FIND(hh, g_named_registry.entries, &key, sizeof(uintptr_t), entry);
783 const char *result = entry ? entry->format_spec : NULL;
784 rwlock_rdunlock(&g_named_registry.entries_lock);
785 return result;
786}

References named_entry::format_spec.

◆ named_get_format_spec()

const char * named_get_format_spec ( uintptr_t key)

#include <include/ascii-chat/debug/named.h>

Get the format specifier for a registered named object.

Parameters
keyThe resource key
Returns
Format specifier string (e.g., "0x%tx"), or NULL if not registered

Returns the format specifier registered with named_register(), or NULL if the key is not in the registry.

In release builds (NDEBUG), this always returns NULL.

Definition at line 537 of file debug/named.c.

537 {
538 if (!lifecycle_is_initialized(&g_named_registry.lifecycle)) {
539 return NULL;
540 }
541
542 rwlock_rdlock(&g_named_registry.entries_lock);
543 named_entry_t *entry = NULL;
544 HASH_FIND(hh, g_named_registry.entries, &key, sizeof(uintptr_t), entry);
545 const char *result = entry ? entry->format_spec : NULL;
546 rwlock_rdunlock(&g_named_registry.entries_lock);
547 return result;
548}

References named_entry::format_spec.

◆ named_get_packet_type()

const char * named_get_packet_type ( int pkt_type)

#include <include/ascii-chat/debug/named.h>

Look up a registered packet type.

Parameters
pkt_typePacket type value
Returns
Registered name string, or NULL if not registered

Looks up a packet type using the same namespace encoding as named_register_packet_type(). In release builds (NDEBUG), this always returns NULL.

Definition at line 819 of file debug/named.c.

819 {
820 if (pkt_type < 0)
821 return NULL;
822
823 if (!lifecycle_is_initialized(&g_named_registry.lifecycle)) {
824 return NULL;
825 }
826
827 uintptr_t key = encode_pkt_type_key(pkt_type);
828 rwlock_rdlock(&g_named_registry.entries_lock);
829 named_entry_t *entry = NULL;
830 HASH_FIND(hh, g_named_registry.entries, &key, sizeof(uintptr_t), entry);
831 const char *result = entry ? entry->name : NULL;
832 rwlock_rdunlock(&g_named_registry.entries_lock);
833 return result;
834}

References named_entry::name.

◆ named_get_packet_type_format_spec()

const char * named_get_packet_type_format_spec ( int pkt_type)

#include <include/ascii-chat/debug/named.h>

Get the format specifier for a registered packet type.

Parameters
pkt_typePacket type value
Returns
Format specifier string (e.g., "%d"), or NULL if not registered

Definition at line 836 of file debug/named.c.

836 {
837 if (pkt_type < 0)
838 return NULL;
839
840 if (!lifecycle_is_initialized(&g_named_registry.lifecycle)) {
841 return NULL;
842 }
843
844 uintptr_t key = encode_pkt_type_key(pkt_type);
845 rwlock_rdlock(&g_named_registry.entries_lock);
846 named_entry_t *entry = NULL;
847 HASH_FIND(hh, g_named_registry.entries, &key, sizeof(uintptr_t), entry);
848 const char *result = entry ? entry->format_spec : NULL;
849 rwlock_rdunlock(&g_named_registry.entries_lock);
850 return result;
851}

References named_entry::format_spec.

◆ named_get_type()

const char * named_get_type ( uintptr_t key)

#include <include/ascii-chat/debug/named.h>

Look up the registered type for a resource.

Parameters
keyThe resource key
Returns
Registered type string, or NULL if not registered

Returns the type string registered with named_register() or named_register_fmt(), or NULL if the key is not in the registry.

In release builds (NDEBUG), this always returns NULL.

Definition at line 524 of file debug/named.c.

524 {
525 if (!lifecycle_is_initialized(&g_named_registry.lifecycle)) {
526 return NULL;
527 }
528
529 rwlock_rdlock(&g_named_registry.entries_lock);
530 named_entry_t *entry = NULL;
531 HASH_FIND(hh, g_named_registry.entries, &key, sizeof(uintptr_t), entry);
532 const char *result = entry ? entry->type : NULL;
533 rwlock_rdunlock(&g_named_registry.entries_lock);
534 return result;
535}

References named_entry::type.

◆ named_init()

asciichat_error_t named_init ( void )

#include <include/ascii-chat/debug/named.h>

Initialize the named object registry.

Returns
0 on success, non-zero on error

Must be called once at startup before any named_register() calls. Typically called from lock_debug_init().

Definition at line 236 of file debug/named.c.

236 {
237 // Idempotent: if already initialized, return success
238 if (lifecycle_is_initialized(&g_named_registry.lifecycle)) {
239 return ASCIICHAT_OK;
240 }
241
242 if (!lifecycle_init(&g_named_registry.lifecycle, "named_registry")) {
243 return ASCIICHAT_OK;
244 }
245
246 if (rwlock_init(&g_named_registry.entries_lock, "named_registry_lock") != 0) {
247 lifecycle_shutdown(&g_named_registry.lifecycle);
248 return ASCIICHAT_OK; // Continue even if rwlock init fails
249 }
250
251 g_metadata_tls_ready = platform_tls_key_create(&g_metadata_tls, metadata_cache_destroy) == 0;
252 atomic_fetch_add(&g_metadata_revision, 1);
253 lifecycle_init_commit(&g_named_registry.lifecycle);
254 return ASCIICHAT_OK;
255}

References ASCIICHAT_OK.

Referenced by asciichat_shared_init(), and main().

◆ named_metadata_copy()

bool named_metadata_copy ( uintptr_t key,
named_metadata_t * output )

#include <include/ascii-chat/debug/named.h>

Copy display metadata from a per-thread snapshot. Stable registrations need no registry lock, including misses. Registration/removal invalidates snapshots. Returns false if absent, busy, or the metadata exceeds the output buffers. These copies identify objects; they do not pin objects for dereferencing.

Definition at line 210 of file debug/named.c.

210 {
211 if (!output)
212 return false;
213 named_metadata_cache_t *cache = metadata_snapshot();
214 if (!cache) {
215 // Keep names available if TLS/allocation is unavailable. No borrowed
216 // strings escape this fallback either.
217 if (!lifecycle_is_initialized(&g_named_registry.lifecycle))
218 return false;
219 bool acquired = false;
220 if (rwlock_tryrdlock(&g_named_registry.entries_lock, &acquired) != ASCIICHAT_OK || !acquired)
221 return false;
222 named_entry_t *entry = NULL;
223 HASH_FIND(hh, g_named_registry.entries, &key, sizeof(key), entry);
224 bool copied = entry && metadata_copy_entry(entry, output);
225 rwlock_rdunlock(&g_named_registry.entries_lock);
226 return copied;
227 }
228 named_metadata_entry_t lookup = {.key = key};
229 const named_metadata_entry_t *entry = cache->count ? bsearch(&lookup, cache->entries, cache->count, sizeof(*cache->entries), metadata_compare) : NULL;
230 if (!entry || !entry->valid)
231 return false;
232 *output = entry->metadata;
233 return true;
234}
named_metadata_entry_t * entries
bool valid
named_metadata_t metadata

References ASCIICHAT_OK, named_metadata_cache_t::count, named_metadata_cache_t::entries, named_metadata_entry_t::metadata, and named_metadata_entry_t::valid.

Referenced by log_named_format_message(), log_template_apply(), named_fd_metadata_copy(), and named_packet_metadata_copy().

◆ named_packet_metadata_copy()

bool named_packet_metadata_copy ( int packet_type,
named_metadata_t * output )

#include <include/ascii-chat/debug/named.h>

Definition at line 715 of file debug/named.c.

715 {
716 return packet_type >= 0 && named_metadata_copy(encode_pkt_type_key(packet_type), output);
717}

References named_metadata_copy().

Referenced by log_named_format_message().

◆ named_print_hash_stats()

void named_print_hash_stats ( void )

#include <include/ascii-chat/debug/named.h>

Print a synchronized hash-table summary without logging under its lock.

Definition at line 857 of file debug/named.c.

857 {
858 if (!lifecycle_is_initialized(&g_named_registry.lifecycle))
859 return;
860 rwlock_rdlock(&g_named_registry.entries_lock);
861 size_t entries = HASH_COUNT(g_named_registry.entries);
862 size_t buckets = g_named_registry.entries ? g_named_registry.entries->hh.tbl->num_buckets : 0;
863 rwlock_rdunlock(&g_named_registry.entries_lock);
864 log_plain("Named registry: entries=%zu buckets=%zu", entries, buckets);
865}
#define log_plain(...)
Plain logging - writes to both log file and stderr without timestamps or log levels.
Definition log/log.h:659

References log_plain.

◆ named_register()

const char * named_register ( uintptr_t key,
const char * base_name,
const char * type,
const char * format_spec,
const char * file,
int line,
const char * func,
uintptr_t parent_key )

#include <include/ascii-chat/debug/named.h>

Register a resource with an auto-suffixed name, type, and location info.

Parameters
keyA uintptr_t representing the resource (pointer or integer handle)
base_nameThe base name (e.g., "recv"); suffix auto-generated
typeData type label (e.g., "mutex", "rwlock", "socket"); stored and printed
fileSource file where registration occurred (typically FILE)
lineSource line where registration occurred (typically LINE)
funcFunction where registration occurred (typically func)
Returns
Pointer to the full registered name (e.g., "recv.7"), valid until unregister

The returned name string is stored in the registry and remains valid until named_unregister(key) is called. Do not modify or free the returned pointer.

The type parameter is stored in the registry and used by named_describe() to format output as "type: name (0xKEY) @ file:line:func()" automatically, without needing a type_hint parameter.

Multiple registrations of the same key will overwrite the previous entry. In release builds (NDEBUG), this is a no-op and returns base_name.

Definition at line 326 of file debug/named.c.

326 {
327#ifdef NDEBUG
328 // In release builds, skip debug registry and return the base name
329 return base_name ? base_name : "?";
330#endif
331
332 if (!base_name || !type || !format_spec) {
333 return "?";
334 }
335
336 if (!lifecycle_is_initialized(&g_named_registry.lifecycle)) {
337 return base_name;
338 }
339
340 // If parent_key provided, look up parent name and create hierarchical name
341 char final_base_name[DEBUG_NAMED_FINAL_BASE_NAME_BUFFER_SIZE];
342 if (parent_key != 0) {
343 rwlock_rdlock(&g_named_registry.entries_lock);
344 const char *parent_name = named_lookup_name_unlocked(parent_key);
345 rwlock_rdunlock(&g_named_registry.entries_lock);
346
347 if (parent_name) {
348 snprintf(final_base_name, sizeof(final_base_name), "%s#%s", parent_name, base_name);
349 } else {
350 // Parent not found, fall back to base name
351 snprintf(final_base_name, sizeof(final_base_name), "%s", base_name);
352 }
353 } else {
354 snprintf(final_base_name, sizeof(final_base_name), "%s", base_name);
355 }
356
357 // Generate unique name using atomic counters (only for non-hierarchical names)
358 char name_buffer[DEBUG_NAMED_NAME_BUFFER_SIZE];
359 if (parent_key == 0) {
360 uint64_t counter = 0;
361 if (strcmp(type, "mutex") == 0) {
362 counter = __sync_fetch_and_add(&mutex_counter, 1);
363 } else if (strcmp(type, "rwlock") == 0) {
364 counter = __sync_fetch_and_add(&rwlock_counter, 1);
365 } else if (strcmp(type, "cond") == 0) {
366 counter = __sync_fetch_and_add(&cond_counter, 1);
367 } else if (strcmp(type, "atomic") == 0) {
368 counter = __sync_fetch_and_add(&atomic_counter, 1);
369 }
370 snprintf(name_buffer, sizeof(name_buffer), "%s.%" PRIu64, final_base_name, counter);
371 } else {
372 // Hierarchical names don't get counters - parent already has one
373 snprintf(name_buffer, sizeof(name_buffer), "%s", final_base_name);
374 }
375
376 // Allocate entry BEFORE acquiring lock (avoid long critical section)
377 named_entry_t *entry = malloc(sizeof(named_entry_t));
378 if (!entry)
379 return base_name;
380
381 entry->key = key;
382 entry->name = entry_strdup(name_buffer);
383 named_entry_init(entry, type, format_spec, file, line, func);
384
385 // Only hold lock for the hash table operation
386 log_dev("[NAMED_REGISTER_LOCK_1] About to acquire entries_lock for key=%p type=%s", (void *)key, type);
387 rwlock_wrlock(&g_named_registry.entries_lock);
388 HASH_ADD(hh, g_named_registry.entries, key, sizeof(uintptr_t), entry);
389 atomic_fetch_add(&g_metadata_revision, 1);
390 rwlock_wrunlock(&g_named_registry.entries_lock);
391 log_dev("[NAMED_REGISTER_LOCK_4] ✅ Released entries_lock");
392
393 return entry->name;
394}
#define DEBUG_NAMED_FINAL_BASE_NAME_BUFFER_SIZE
Definition debug/named.c:12
#define DEBUG_NAMED_NAME_BUFFER_SIZE
Definition debug/named.h:47
#define log_dev(...)
Log a DEV message (most verbose, development only).
Definition log/log.h:575
uintptr_t key
Definition debug/named.c:68

References DEBUG_NAMED_FINAL_BASE_NAME_BUFFER_SIZE, DEBUG_NAMED_NAME_BUFFER_SIZE, named_entry::key, log_dev, and named_entry::name.

◆ named_register_fd()

const char * named_register_fd ( int fd,
const char * name,
const char * file,
int line,
const char * func )

#include <include/ascii-chat/debug/named.h>

Register a file descriptor with namespace encoding.

Parameters
fdFile descriptor value
fileSource file where registration occurred
lineSource line where registration occurred
funcFunction where registration occurred
Returns
Registered name string

Registers an FD with a key that includes type namespace to avoid collisions with packet types or other numeric values. If name is non-NULL, uses "name (fd=N)" format; otherwise auto-generates as "fd=N". In release builds (NDEBUG), this is a no-op and returns "fd=%d" string.

Definition at line 719 of file debug/named.c.

719 {
720 if (fd < 0) {
721 return "?";
722 }
723
724 if (!lifecycle_is_initialized(&g_named_registry.lifecycle)) {
725 return "?";
726 }
727
728 char name_buffer[DEBUG_NAMED_NAME_BUFFER_SIZE];
729 if (name) {
730 snprintf(name_buffer, sizeof(name_buffer), "%s", name);
731 } else {
732 snprintf(name_buffer, sizeof(name_buffer), "fd=%d", fd);
733 }
734
735 // Allocate entry BEFORE acquiring lock
736 named_entry_t *entry = malloc(sizeof(named_entry_t));
737 if (!entry)
738 return "?";
739
740 uintptr_t key = encode_fd_key(fd);
741 entry->key = key;
742 entry->name = entry_strdup(name_buffer);
743 named_entry_init(entry, "fd", "%d", file, line, func);
744
745 // Only hold lock for the hash table operation
746 rwlock_wrlock(&g_named_registry.entries_lock);
747 HASH_ADD(hh, g_named_registry.entries, key, sizeof(uintptr_t), entry);
748 atomic_fetch_add(&g_metadata_revision, 1);
749 rwlock_wrunlock(&g_named_registry.entries_lock);
750
751 return entry->name;
752}

References DEBUG_NAMED_NAME_BUFFER_SIZE, named_entry::key, and named_entry::name.

◆ named_register_fmt()

const char * named_register_fmt ( uintptr_t key,
const char * type,
const char * format_spec,
const char * file,
int line,
const char * func,
const char * fmt,
... )

#include <include/ascii-chat/debug/named.h>

Register a resource with a formatted name, type, and location info (no auto-suffix).

Parameters
keyA uintptr_t representing the resource
typeData type label (e.g., "mutex", "socket"); stored and printed
fileSource file where registration occurred
lineSource line where registration occurred
funcFunction where registration occurred
fmtPrintf-style format string
...Format arguments
Returns
Pointer to the full registered name

Allows full control over the registered name. The format string and arguments are printed to create the name (e.g., "client.%u" with args "17" → "client.17"). No auto-suffix counter is applied.

The type parameter is stored in the registry and used by named_describe() for automatic formatting without needing type_hint.

In release builds (NDEBUG), this is a no-op and returns "?".

Definition at line 396 of file debug/named.c.

396 {
397 if (!type || !format_spec || !fmt) {
398 return "?";
399 }
400
401 if (!lifecycle_is_initialized(&g_named_registry.lifecycle)) {
402 return fmt;
403 }
404
405 // Format the name BEFORE acquiring lock
406 va_list args;
407 va_start(args, fmt);
408 char *full_name = NULL;
409 int ret = platform_vasprintf(&full_name, fmt, args);
410 va_end(args);
411
412 if (ret < 0) {
413 return "?";
414 }
415
416 // Allocate entry BEFORE acquiring lock
417 named_entry_t *entry = malloc(sizeof(named_entry_t));
418 if (!entry) {
419 free(full_name);
420 return "?";
421 }
422
423 // Initialize entry (name is pre-allocated as full_name)
424 entry->key = key;
425 entry->name = full_name;
426 named_entry_init(entry, type, format_spec, file, line, func);
427
428 // Only hold lock for the hash table operation
429 rwlock_wrlock(&g_named_registry.entries_lock);
430 HASH_ADD(hh, g_named_registry.entries, key, sizeof(uintptr_t), entry);
431 atomic_fetch_add(&g_metadata_revision, 1);
432 rwlock_wrunlock(&g_named_registry.entries_lock);
433
434 return entry->name;
435}
action_args_t args

References args, named_entry::key, and named_entry::name.

◆ named_register_packet_type()

const char * named_register_packet_type ( int pkt_type,
const char * file,
int line,
const char * func )

#include <include/ascii-chat/debug/named.h>

Register a packet type with namespace encoding.

Parameters
pkt_typePacket type value
fileSource file where registration occurred
lineSource line where registration occurred
funcFunction where registration occurred
Returns
Registered name string

Registers a packet type with a key that includes type namespace to avoid collisions with FDs or other numeric values. Name is auto-generated as "PACKET_TYPE=%d". In release builds (NDEBUG), this is a no-op and returns "PACKET_TYPE=%d" string.

Definition at line 788 of file debug/named.c.

788 {
789 if (pkt_type < 0) {
790 return "?";
791 }
792
793 if (!lifecycle_is_initialized(&g_named_registry.lifecycle)) {
794 return "?";
795 }
796
797 char name_buffer[DEBUG_NAMED_NAME_BUFFER_SIZE];
798 snprintf(name_buffer, sizeof(name_buffer), "PACKET_TYPE=%d", pkt_type);
799
800 // Allocate entry BEFORE acquiring lock
801 named_entry_t *entry = malloc(sizeof(named_entry_t));
802 if (!entry)
803 return "?";
804
805 uintptr_t key = encode_pkt_type_key(pkt_type);
806 entry->key = key;
807 entry->name = entry_strdup(name_buffer);
808 named_entry_init(entry, "packet_type", "%d", file, line, func);
809
810 // Only hold lock for the hash table operation
811 rwlock_wrlock(&g_named_registry.entries_lock);
812 HASH_ADD(hh, g_named_registry.entries, key, sizeof(uintptr_t), entry);
813 atomic_fetch_add(&g_metadata_revision, 1);
814 rwlock_wrunlock(&g_named_registry.entries_lock);
815
816 return entry->name;
817}

References DEBUG_NAMED_NAME_BUFFER_SIZE, named_entry::key, and named_entry::name.

◆ named_registry_for_each()

asciichat_error_t named_registry_for_each ( named_iter_callback_t callback,
void * user_data,
bool * completed )

#include <include/ascii-chat/debug/named.h>

Iterate through all registered entries.

Parameters
callbackFunction to call for each entry
user_dataOpaque context passed to callback

Copies all names and keys, then invokes callbacks outside the registry lock. Tries the registry lock without waiting. Sets *completed to false on contention or growth during allocation, and true after visiting every entry. No callbacks run on an incomplete attempt; callers may keep their previous snapshot and retry later. Actual errors are returned with SET_ERRNO. Keys do not pin objects: use named_registry_read() before accessing an object that can be destroyed. Callbacks can block and are outside this guarantee.

Definition at line 596 of file debug/named.c.

596 {
597 if (!callback || !completed)
598 return SET_ERRNO(ERROR_INVALID_PARAM, "Registry iteration requires a callback");
599 *completed = false;
600 // Logging also enumerates names during startup and teardown.
601 if (!lifecycle_is_initialized(&g_named_registry.lifecycle)) {
602 *completed = true;
603 return ASCIICHAT_OK;
604 }
605 bool acquired = false;
606 asciichat_error_t err = rwlock_tryrdlock(&g_named_registry.entries_lock, &acquired);
607 if (err != ASCIICHAT_OK || !acquired)
608 return err;
609 size_t capacity = HASH_COUNT(g_named_registry.entries);
610 rwlock_rdunlock(&g_named_registry.entries_lock);
611 if (!capacity) {
612 *completed = true;
613 return ASCIICHAT_OK;
614 }
615 if (capacity > SIZE_MAX / sizeof(named_iter_entry_t))
616 return SET_ERRNO(ERROR_MEMORY, "Named registry snapshot size overflow");
617 // Snapshot metadata must not re-enter the registry through memory tracking.
618 named_iter_entry_t *entries = UNTRACKED_MALLOC(capacity * sizeof(*entries), named_iter_entry_t *);
619 if (!entries)
620 return SET_ERRNO(ERROR_MEMORY, "Cannot allocate named registry snapshot");
621 err = rwlock_tryrdlock(&g_named_registry.entries_lock, &acquired);
622 if (err != ASCIICHAT_OK || !acquired) {
623 UNTRACKED_FREE(entries);
624 return err;
625 }
626 if (HASH_COUNT(g_named_registry.entries) > capacity) {
627 rwlock_rdunlock(&g_named_registry.entries_lock);
628 UNTRACKED_FREE(entries);
629 return ASCIICHAT_OK;
630 }
631 size_t count = 0;
632 for (named_entry_t *e = g_named_registry.entries; e != NULL; e = e->hh.next) {
633 entries[count].key = e->key;
634 const char *src = e->name ? e->name : "?";
635 size_t src_len = strlen(src);
636 if (src_len >= MAX_NAME_LEN)
637 src_len = MAX_NAME_LEN - 1;
638 memcpy(entries[count].name, src, src_len);
639 entries[count].name[src_len] = '\0';
640 count++;
641 }
642 rwlock_rdunlock(&g_named_registry.entries_lock);
643
644 // Call callback outside the lock
645 for (size_t i = 0; i < count; i++) {
646 callback(entries[i].key, entries[i].name, user_data);
647 }
648 UNTRACKED_FREE(entries);
649 *completed = true;
650 return ASCIICHAT_OK;
651}
#define MAX_NAME_LEN
Definition debug/named.c:37
@ ERROR_INVALID_PARAM
uintptr_t key
char name[256]

References ASCIICHAT_OK, ERROR_INVALID_PARAM, ERROR_MEMORY, named_iter_entry_t::key, MAX_NAME_LEN, named_iter_entry_t::name, SET_ERRNO, UNTRACKED_FREE, and UNTRACKED_MALLOC.

◆ named_registry_has_type()

bool named_registry_has_type ( const char * type,
size_t length )

#include <include/ascii-chat/debug/named.h>

Check a type prefix in copied metadata; false if absent, uninitialized or busy.

Definition at line 510 of file debug/named.c.

510 {
511 if (!type || !length)
512 return false;
513 named_metadata_cache_t *cache = metadata_snapshot();
514 if (!cache)
515 return false;
516 for (size_t i = 0; i < cache->count; ++i) {
517 const named_metadata_entry_t *entry = &cache->entries[i];
518 if (entry->valid && strlen(entry->metadata.type) == length && memcmp(entry->metadata.type, type, length) == 0)
519 return true;
520 }
521 return false;
522}

References named_metadata_cache_t::count, named_metadata_cache_t::entries, named_metadata_entry_t::metadata, named_metadata_t::type, and named_metadata_entry_t::valid.

◆ named_registry_read()

bool named_registry_read ( uintptr_t key,
const char * type,
void(* read_object )(uintptr_t, void *),
void * user_data )

#include <include/ascii-chat/debug/named.h>

Read a registered object while preventing concurrent unregistration. The callback must only copy data: no logging, allocation, or registry calls. Owners must unregister before freeing the object. Returns false if absent, if the registered type does not match, or if the registry is busy.

Definition at line 676 of file debug/named.c.

676 {
677 if (!type || !read_object || !lifecycle_is_initialized(&g_named_registry.lifecycle))
678 return false;
679 bool acquired = false;
680 if (rwlock_tryrdlock(&g_named_registry.entries_lock, &acquired) != ASCIICHAT_OK || !acquired)
681 return false;
682 named_entry_t *entry = NULL;
683 HASH_FIND(hh, g_named_registry.entries, &key, sizeof(key), entry);
684 bool found = entry && entry->type && strcmp(entry->type, type) == 0;
685 if (found)
686 read_object(key, user_data);
687 rwlock_rdunlock(&g_named_registry.entries_lock);
688 return found;
689}

References ASCIICHAT_OK, and named_entry::type.

◆ named_registry_register_packet_types()

void named_registry_register_packet_types ( void )

#include <include/ascii-chat/debug/named.h>

Register all packet types from packet_type_t enum.

Registers all packet type enum values in the named registry using keys in the format "PACKET_TYPE=%d" where d is the enum value. This should be called once during initialization to enable packet type identification in log message formatting.

Definition at line 853 of file debug/named.c.

853 {
854 // No-op
855}

Referenced by main().

◆ named_registry_try_snapshot()

asciichat_error_t named_registry_try_snapshot ( size_t capacity,
size_t * required,
bool * completed,
named_snapshot_fn copy,
void * data )

#include <include/ascii-chat/debug/named.h>

Definition at line 653 of file debug/named.c.

653 {
654 if (!required || !completed || !copy)
655 return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid protected registry snapshot");
656 *completed = false;
657 *required = 0;
658 if (!lifecycle_is_initialized(&g_named_registry.lifecycle)) {
659 *completed = true;
660 return ASCIICHAT_OK;
661 }
662 bool acquired = false;
663 asciichat_error_t result = rwlock_tryrdlock(&g_named_registry.entries_lock, &acquired);
664 if (result != ASCIICHAT_OK || !acquired)
665 return result;
666 *required = HASH_COUNT(g_named_registry.entries);
667 if (*required <= capacity) {
668 for (named_entry_t *e = g_named_registry.entries; e; e = e->hh.next)
669 copy(e->key, e->generation, e->name, e->type, e->file, e->line, data);
670 *completed = true;
671 }
672 rwlock_rdunlock(&g_named_registry.entries_lock);
673 return ASCIICHAT_OK;
674}

References ASCIICHAT_OK, ERROR_INVALID_PARAM, and SET_ERRNO.

Referenced by debug_sync_check_cond_deadlocks().

◆ named_unregister()

void named_unregister ( uintptr_t key)

#include <include/ascii-chat/debug/named.h>

Unregister a resource by key.

Parameters
keyThe same uintptr_t passed to named_register

Removes the resource from the registry. Safe to call multiple times for the same key (idempotent).

Definition at line 437 of file debug/named.c.

437 {
438 if (!lifecycle_is_initialized(&g_named_registry.lifecycle)) {
439 return;
440 }
441
442 rwlock_wrlock(&g_named_registry.entries_lock);
443 named_entry_t *entry = NULL;
444 HASH_FIND(hh, g_named_registry.entries, &key, sizeof(uintptr_t), entry);
445 bool changed = entry != NULL;
446 // A primitive may be registered again with a parent-qualified name. Retire
447 // every entry before its owner releases the object.
448 while (entry) {
449 HASH_DEL(g_named_registry.entries, entry);
450 free(entry->name);
451 if (entry->type)
452 free(entry->type);
453 if (entry->format_spec)
454 free(entry->format_spec);
455 if (entry->file)
456 free(entry->file);
457 if (entry->func)
458 free(entry->func);
459 free(entry);
460 HASH_FIND(hh, g_named_registry.entries, &key, sizeof(uintptr_t), entry);
461 }
462 if (changed)
463 atomic_fetch_add(&g_metadata_revision, 1);
464 rwlock_wrunlock(&g_named_registry.entries_lock);
465}

References named_entry::file, named_entry::format_spec, named_entry::func, named_entry::name, and named_entry::type.

◆ named_update_name()

const char * named_update_name ( uintptr_t key,
const char * new_base_name )

#include <include/ascii-chat/debug/named.h>

Update the registered name for a resource with a new base name.

Parameters
keyThe resource key
new_base_nameNew base name (will be auto-suffixed with counter)
Returns
Updated name string, or NULL if key not found

Updates an existing registration with a new base name. The new name will be auto-suffixed with a counter to make it unique (e.g., "client_123.0"). Useful when a resource gets an ID assigned after creation (e.g., client_id).

In release builds (NDEBUG), this is a no-op and returns NULL.

Definition at line 467 of file debug/named.c.

467 {
468#ifndef NDEBUG
469 if (!new_base_name || !lifecycle_is_initialized(&g_named_registry.lifecycle))
470 return NULL;
471 char name[MAX_NAME_LEN];
472 snprintf(name, sizeof(name), "%s.%" PRIu64, new_base_name, ++named_generation);
473 char *replacement = entry_strdup(name);
474 if (!replacement)
475 return NULL;
476 rwlock_wrlock(&g_named_registry.entries_lock);
477 named_entry_t *entry = NULL;
478 HASH_FIND(hh, g_named_registry.entries, &key, sizeof(key), entry);
479 const char *result = NULL;
480 if (entry) {
481 UNTRACKED_FREE(entry->name);
482 entry->name = replacement;
483 result = replacement;
484 atomic_fetch_add(&g_metadata_revision, 1);
485 } else {
486 UNTRACKED_FREE(replacement);
487 }
488 rwlock_wrunlock(&g_named_registry.entries_lock);
489 return result;
490#else
491 (void)key;
492 (void)new_base_name;
493 return NULL;
494#endif
495}

References MAX_NAME_LEN, named_entry::name, and UNTRACKED_FREE.

◆ thread_to_key()

uintptr_t thread_to_key ( platform_thread_t thread)

#include <include/ascii-chat/debug/named.h>

Convert a thread handle to a registry key.

Parameters
threadThread handle (platform_thread_t)
Returns
uintptr_t suitable for registry lookups

Platform-specific conversion. On POSIX, pthread_t is cast directly. On Windows, HANDLE is cast directly.

This function is defined in libplatform's POSIX or Windows thread implementation.

Referenced by named_describe_thread().