Files
file	mutex.c
	Per-thread mutex lock stack for deadlock detection.

file	sync.c
	🔒 Synchronization primitive debugging with dynamic state inspection

file	mutex.h
	Per-thread mutex lock stack for deadlock detection.

file	sync.h
	🔒 Synchronization primitive debugging (mutexes, rwlocks, condition variables)

Functions
void	debug_sync_check_cond_deadlocks (void)
	Check all condition variables for deadlocks.

void	debug_sync_print_mutex_state (void)
	Print timing state for all named mutexes to stdout/log.

void	debug_sync_print_rwlock_state (void)
	Print timing state for all named read-write locks to stdout/log.

void	debug_sync_print_cond_state (void)
	Print timing state for all named condition variables to stdout/log.

void	debug_sync_print_state (void)
	Print all synchronization primitive states at once.

void	debug_sync_print_state_delayed (uint64_t delay_ns)
	Schedule delayed sync state printing on debug thread.

void	debug_sync_print_backtrace_delayed (uint64_t delay_ns)
	Schedule delayed backtrace printing on debug thread.

void	debug_sync_set_memory_report_interval (uint64_t interval_ns)
	Set periodic memory report interval.

void	debug_sync_set_main_thread_id (void)
	Initialize debug synchronization system.

uint64_t	debug_sync_get_main_thread_id (void)
	Get the main thread ID for memory reporting.

int	debug_sync_start_thread (void)
	Start background debug thread for scheduled operations.

void	debug_sync_destroy (void)
	Destroy debug synchronization system.

void	debug_sync_cleanup_thread (void)
	Stop and clean up background debug thread.

void	debug_sync_final_cleanup (void)
	Final cleanup of debug allocations at shutdown.

void	debug_sync_trigger_print (void)
	Trigger sync state print immediately (synchronous)

void	debug_sync_get_stats (uint64_t total_acquired, uint64_t total_released, uint32_t *currently_held)
	Get synchronization statistics.

Detailed Description

This module provides comprehensive synchronization state inspection and debugging:

Dynamic state inspection using named.c registry (see debug/named.h)
Timing information for all lock operations (last lock/unlock times)
Zero-copy iteration through all registered primitives
Scheduled delayed printing for capture during critical sections

No internal collection overhead - queries named.c directly for live state, making it safe to call even in tight loops without performance penalty.

Purpose

Synchronization debugging answers critical questions:

Development: Which locks are blocking? Which have stale holders?
Production: Is a deadlock happening? How long are acquisitions taking?
Testing: Are multiple threads contending properly? What's the lock order?

Useful for:

Detecting deadlocks and lock inversions
Identifying contention bottlenecks
Validating thread safety assumptions
Production debugging with minimal overhead

Key Features

Zero-overhead queries: No collection threads, direct state inspection
Named primitive support: Works with any primitive registered via named.h
Timing snapshots: Last lock/unlock times for contention analysis
Comprehensive views: Print all mutexes, rwlocks, and condition variables
Delayed reporting: Schedule state capture during specific execution phases
Thread-safe printing: Can be called from signal handlers or debug threads

Integration with Named Registry

Synchronization primitives are identified by their names in the named.c registry:

// In your code:
mutex_t recv_lock;
mutex_init(&recv_lock);
NAMED_REGISTER(&recv_lock, "recv", "mutex");  // See debug/named.h
 
// Later, in debug output:
debug_sync_print_state();  // Prints "recv.1 (mutex)" with timing

See also: debug/named.h - The registry that backs this module

Usage Examples

Development: Print Current Lock State

// When you suspect a deadlock or lock contention:

debug_sync_print_state(); // Prints all mutexes, rwlocks, conds with timing

Production: Periodic State Dumps

// In a signal handler (e.g., SIGUSR2):
void handle_debug_signal(int sig) {
    debug_sync_trigger_print();  // Schedules print on debug thread
}
 
// In main:
debug_sync_init();
debug_sync_start_thread();
signal(SIGUSR2, handle_debug_signal);  // SIGUSR2 is mapped to sync state printing
// Now: kill -USR2 <pid> triggers state dump in logs

Testing: Capture State at Specific Moments

// Schedule a state dump after 100ms (during critical section):
debug_sync_print_state_delayed(100 * 1000000);  // 100ms in nanoseconds
// State will print automatically on debug thread

Backtrace on Lock Contention

// Combined with backtrace:
debug_sync_print_state();         // See which locks are held
debug_sync_print_backtrace_delayed(50 * 1000000);  // Get stacks after 50ms

Output Format

Typical output:

=== Mutex State ===
recv.1 (mutex) @ lib/network/socket.c:42:socket_create()
  Last lock:   2026-02-23T17:45:23.123456789Z (123ms ago)
  Last unlock: 2026-02-23T17:45:23.200000000Z (45ms ago)
  Status: free
 
send.2 (mutex) @ lib/network/socket.c:89:socket_send()
  Last lock:   2026-02-23T17:45:23.195000000Z (50ms ago)
  Last unlock: (never)
  Status: HELD (potential deadlock!)

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

Date: February 2026

Function Documentation

◆ debug_sync_check_cond_deadlocks()

void debug_sync_check_cond_deadlocks ( void )

#include <mutex.c>

Check all condition variables for deadlocks.

Check all condition variables for potential deadlocks.

Scans all registered condition variables and logs warnings for any that have been waiting without signal for longer than COND_DEADLOCK_THRESHOLD_NS. Called periodically by the debug thread (every 100ms).

Skips checks during shutdown to avoid accessing freed memory.

Scans all registered condition variables and logs warnings for any that have threads waiting without being signaled for longer than 5 seconds.

For each stuck condition variable, logs:

Number of waiting threads and elapsed wait time
Callsite where wait was entered (file, line, function)
Associated mutex status (held by whom, or free)

Called periodically by the debug thread (every 100ms), so detection latency is at most 5 seconds + 100ms for stuck conditions.

Output Example

[WARN] Stuck cond 'audio_send_queue_cond.0': 1 thread(s) waiting 66s with no signal (most recent waiter:
audio_sender.0) [WARN]   wait entered at src/client/audio.c:291 audio_sender_thread_func() [WARN]   associated mutex
is FREE — producer is not calling cond_signal

Note: Thread-safe: can be called from any thread; No blocking: reads only, doesn't acquire locks; Called automatically by debug thread; only call manually for immediate checks

See also: debug_sync_start_thread() to ensure periodic checking

Definition at line 737 of file debug/mutex.c.

                                           {
  if (debug_sync_is_cleanup_in_progress()) {
    return;
  }
  named_registry_for_each(cond_deadlock_check_callback, NULL);
}

References debug_sync_is_cleanup_in_progress(), and named_registry_for_each().

◆ debug_sync_cleanup_thread()

void debug_sync_cleanup_thread ( void )

#include <sync.h>

Stop and clean up background debug thread.

Gracefully shuts down the background debug thread that was started by debug_sync_start_thread(). Processes any remaining queued jobs before exit.

Typical Shutdown Sequence

// At program shutdown:
debug_sync_cleanup_thread();  // Stop background thread
debug_sync_destroy();         // Destroy system

Note: Must be called before debug_sync_destroy(); Safe to call multiple times

Definition at line 674 of file sync.c.

                                     {
  log_debug("[DEBUG_SYNC_CLEANUP] Starting cleanup");
 
  // Only join if thread was actually created
  if (!g_debug_state_request.initialized) {
    log_debug("[DEBUG_SYNC_CLEANUP] Thread not initialized, returning");
    return;
  }
 
  // Set cleanup flag to prevent deadlock checks from accessing freed memory
  // Do this after checking initialization so we don't set it unnecessarily
  atomic_store_bool(&g_cleanup_in_progress, true);
  log_debug("[DEBUG_SYNC_CLEANUP] Thread was initialized, proceeding with cleanup");
 
  log_debug("[DEBUG_SYNC_CLEANUP] Setting initialized to false");
  g_debug_state_request.initialized = false; // Prevent double-join
 
  // Signal the thread to wake up immediately instead of waiting for 100ms timeout
  log_debug("[DEBUG_SYNC_CLEANUP] Signaling thread to exit");
  atomic_store_bool(&g_debug_state_request.should_exit, true);
  cond_signal(&g_debug_state_request.cond);
  log_debug("[DEBUG_SYNC_CLEANUP] Signal sent, about to join thread");
 
  // Use a timeout join to ensure we don't deadlock, but still unregister the thread
  // The debug thread should exit quickly after should_exit is set above
  int join_result = asciichat_thread_join_timeout(&g_debug_thread, NULL, 1000000000ULL); // 1 second timeout
  if (join_result == 0) {
    log_debug("[DEBUG_SYNC_CLEANUP] Thread joined successfully");
  } else if (join_result == -2) {
    log_debug("[DEBUG_SYNC_CLEANUP] Thread join timed out (thread may still be running)");
    // Don't unregister if timeout - thread is still alive
  } else {
    log_debug("[DEBUG_SYNC_CLEANUP] Thread join failed with error %d", join_result);
  }
}

References asciichat_thread_join_timeout(), atomic_store_bool(), debug_state_request_t::cond, cond_signal(), debug_state_request_t::initialized, log_debug, and debug_state_request_t::should_exit.

Referenced by asciichat_shared_destroy(), debug_sync_destroy(), and session_client_like_run().

◆ debug_sync_destroy()

void debug_sync_destroy ( void )

#include <sync.h>

Destroy debug synchronization system.

Cleans up internal structures. Should be called during shutdown, after debug_sync_cleanup_thread().

See also: debug_sync_cleanup_thread() should be called first

Definition at line 670 of file sync.c.

                              {
  debug_sync_cleanup_thread();
}

References debug_sync_cleanup_thread().

Referenced by asciichat_shared_destroy().

◆ debug_sync_final_cleanup()

void debug_sync_final_cleanup ( void )

#include <sync.h>

Final cleanup of debug allocations at shutdown.

Cleans up any remaining thread-local allocations (mutex stacks, etc) from the current thread. Must be called before debug_sync_destroy().

Final cleanup of debug allocations at shutdown.

Definition at line 595 of file sync.c.

                                    {
  // Clean up current thread's mutex stack explicitly
  mutex_stack_cleanup_current_thread();
}

References mutex_stack_cleanup_current_thread().

Referenced by asciichat_shared_destroy().

◆ debug_sync_get_main_thread_id()

uint64_t debug_sync_get_main_thread_id ( void )

#include <sync.h>

Get the main thread ID for memory reporting.

Returns: Main thread ID as uint64_t, or 0 if not initialized

Definition at line 649 of file sync.c.

                                             {
  return g_debug_main_thread_id;
}

◆ debug_sync_get_stats()

void debug_sync_get_stats	(	uint64_t *	total_acquired,
		uint64_t *	total_released,
		uint32_t *	currently_held
	)

#include <sync.h>

Get synchronization statistics.

Parameters

total_acquired	Pointer to store total lock acquisitions (can be NULL)
total_released	Pointer to store total lock releases (can be NULL)
currently_held	Pointer to store currently held locks (can be NULL)

Retrieves global statistics about synchronization primitive usage. Any parameter can be NULL if that statistic isn't needed.

Useful for:

Monitoring lock contention trends
Validating symmetric lock/unlock behavior
Detecting lock leaks (acquired != released)

Example Usage

uint64_t acquired, released;
uint32_t held;
 
debug_sync_get_stats(&acquired, &released, &held);
 
if (acquired == released && held == 0) {
    log_info("No lock leaks: %lu acquisitions, all released", acquired);
} else if (held > 0) {
    log_warn("Possible deadlock: %u locks currently held", held);
}

Note: Atomically reads global counters, no locking required; Statistics accumulate over program lifetime; Useful for periodic health checks or monitoring

Definition at line 722 of file sync.c.

                                                                                                        {
  if (total_acquired)
    *total_acquired = 0;
  if (total_released)
    *total_released = 0;
  if (currently_held)
    *currently_held = 0;
}

Referenced by stats_logger_thread().

◆ debug_sync_print_backtrace_delayed()

void debug_sync_print_backtrace_delayed ( uint64_t delay_ns )

#include <sync.h>

Schedule delayed backtrace printing on debug thread.

Parameters

delay_ns Delay in nanoseconds before printing

Schedules a full backtrace capture and print on the debug thread after the specified delay. Complements debug_sync_print_state_delayed() to capture both lock state AND stack traces at a specific moment.

The debug thread must be running (started via debug_sync_start_thread()).

Combined Usage

void suspect_deadlock_region(void) {
    // Capture both state and stacks after 100ms
    debug_sync_print_state_delayed(100 * 1000000);
    debug_sync_print_backtrace_delayed(100 * 1000000);
 
    // Execute potentially problematic code
    // After 100ms, both state and stacks will be printed
}

Note: Non-blocking: returns immediately; Useful with delayed state printing for comprehensive debugging; Complements backtrace_capture_and_symbolize() for manual backtraces

See also: debug_sync_print_state_delayed(); backtrace.h for manual backtrace capture

Parameters

delay_ns Nanoseconds to sleep before printing

Definition at line 617 of file sync.c.

                                                           {
  mutex_lock(&g_debug_state_request.mutex);
  g_debug_state_request.request_type = DEBUG_REQUEST_BACKTRACE;
  g_debug_state_request.delay_ns = delay_ns;
  atomic_store_bool(&g_debug_state_request.should_run, true);
  cond_signal(&g_debug_state_request.cond);
  mutex_unlock(&g_debug_state_request.mutex);
}

References atomic_store_bool(), debug_state_request_t::cond, cond_signal(), DEBUG_REQUEST_BACKTRACE, debug_state_request_t::delay_ns, debug_state_request_t::mutex, mutex_lock, mutex_unlock, debug_state_request_t::request_type, and debug_state_request_t::should_run.

◆ debug_sync_print_cond_state()

void debug_sync_print_cond_state ( void )

#include <sync.h>

Print timing state for all named condition variables to stdout/log.

Queries the named.c registry and prints a table of all registered condition variables with their timing information:

Name and registration location
Last wait time (with elapsed time)
Last signal time (with elapsed time)
Last broadcast time (with elapsed time)

Useful for detecting:

Condition variable deadlocks (waiters never signaled)
Signal storms (excessive signaling)
Lost wakeups (signals without corresponding waiters)

Note: Thread-safe: can be called from any thread or signal handler; No blocking: reads only, doesn't acquire locks

See also: NAMED_REGISTER() in debug/named.h to register condition variables

◆ debug_sync_print_mutex_state()

void debug_sync_print_mutex_state ( void )

#include <sync.h>

Print timing state for all named mutexes to stdout/log.

Queries the named.c registry and prints a table of all registered mutexes with their timing information:

Name and registration location
Last lock time (with elapsed time)
Last unlock time (with elapsed time)
Current status (held/free)

Useful for detecting:

Mutex deadlocks (HELD locks that should be released)
Lock starvation (locks never acquired)
Excessive lock contention (very frequent lock/unlock cycles)

Note: Thread-safe: can be called from any thread or signal handler; No blocking: reads only, doesn't acquire locks; Zero overhead in release builds if no mutexes are named

See also: NAMED_REGISTER() in debug/named.h to register mutexes for tracking

◆ debug_sync_print_rwlock_state()

void debug_sync_print_rwlock_state ( void )

#include <sync.h>

Print timing state for all named read-write locks to stdout/log.

Queries the named.c registry and prints a table of all registered rwlocks with their timing information:

Name and registration location
Last read-lock time (with elapsed time)
Last write-lock time (with elapsed time)
Last unlock time (with elapsed time)
Current status (read-held/write-held/free)

Useful for detecting:

RWlock writer starvation (reads blocking writers)
Asymmetric lock patterns (only readers or only writers)
Writer lock deadlocks (HELD write locks)

Note: Thread-safe: can be called from any thread or signal handler; No blocking: reads only, doesn't acquire locks

See also: NAMED_REGISTER() in debug/named.h to register rwlocks for tracking

◆ debug_sync_print_state()

void debug_sync_print_state ( void )

#include <sync.h>

Print all synchronization primitive states at once.

Comprehensive debugging view that combines output from:

This is the starting point for understanding overall lock contention and state. Use individual print*_state() functions if you only need specific primitive types.

Typical Workflow

// In debugger or signal handler:
debug_sync_print_state();  // See all sync primitives at once
// Then examine the output for:
// - Any HELD locks that should be free
// - Asymmetric patterns (locks acquired but never released)
// - Timestamps that suggest contention or deadlock

Note: Thread-safe: can be called from any thread or signal handler; Useful in production with signal handlers for "give me the state now"

See also: debug_sync_print_mutex_state(); debug_sync_print_rwlock_state(); debug_sync_print_cond_state()

Definition at line 387 of file sync.c.

                                  {
// Use a single large buffer for all sync state output
#define SYNC_BUFFER_SIZE 65536 // Increased from 8192 to handle many syncs
  log_debug("[debug_sync_print_state] ENTRY");
 
  char *buffer = SAFE_MALLOC(SYNC_BUFFER_SIZE, char *);
  if (!buffer) {
    log_debug("[debug_sync_print_state] Failed to allocate buffer");
    return;
  }
 
  sync_buffer_t buf = {.buffer = buffer, .buffer_size = SYNC_BUFFER_SIZE, .offset = 0};
 
  // Iterate through all registered syncs
  log_debug("[debug_sync_print_state] Iterating mutexes");
  named_registry_for_each(mutex_iter_callback, &buf);
  log_debug("[debug_sync_print_state] Iterating rwlocks");
  named_registry_for_each(rwlock_iter_callback, &buf);
  log_debug("[debug_sync_print_state] Iterating conds");
  named_registry_for_each(cond_iter_callback, &buf);
 
  named_registry_for_each(atomic_t_iter_callback, &buf);
  named_registry_for_each(atomic_ptr_iter_callback, &buf);
 
  // Print lock stacks for deadlock analysis
  log_debug("[debug_sync_print_state] Getting lock stacks");
  debug_sync_print_lock_stacks(buf.buffer, buf.buffer_size, &buf.offset);
 
  // Log everything in one call
  log_debug("[debug_sync_print_state] Buffer size: %zu bytes", buf.offset);
  if (buf.offset > 0) {
    log_info("SYNC_STATE:\n%s", buf.buffer);
  } else {
    log_info("SYNC_STATE: (empty)");
  }
 
  SAFE_FREE(buffer);
#undef SYNC_BUFFER_SIZE
}

References sync_buffer_t::buffer, sync_buffer_t::buffer_size, log_debug, log_info, named_registry_for_each(), sync_buffer_t::offset, SAFE_FREE, SAFE_MALLOC, and SYNC_BUFFER_SIZE.

Referenced by crypto_handshake_init().

◆ debug_sync_print_state_delayed()

void debug_sync_print_state_delayed ( uint64_t delay_ns )

#include <sync.h>

Schedule delayed sync state printing on debug thread.

Parameters

delay_ns Delay in nanoseconds before printing (e.g., 100 * 1000000 for 100ms)

Schedules debug_sync_print_state() to execute on the debug thread after the specified delay. Useful for capturing state snapshots at specific moments in execution (e.g., "print state 50ms from now, during this critical section").

The debug thread must be running (started via debug_sync_start_thread()).

Use Cases

// Capture state during a suspected deadlock region
void critical_section(void) {
    // Schedule state dump 50ms from now (during execution)
    debug_sync_print_state_delayed(50 * 1000000);
 
    // Do work...
    work_that_might_deadlock();
 
    // By the time this returns, state was dumped if deadlock happened
}

Note: Non-blocking: returns immediately, print happens on debug thread; Useful for production debugging with minimal impact; If multiple calls are made, they queue and execute sequentially

See also: debug_sync_start_thread() to ensure Debug thread is running

Schedule delayed sync state printing on debug thread.

Parameters

delay_ns Nanoseconds to sleep before printing

Definition at line 604 of file sync.c.

                                                       {
  mutex_lock(&g_debug_state_request.mutex);
  g_debug_state_request.request_type = DEBUG_REQUEST_STATE;
  g_debug_state_request.delay_ns = delay_ns;
  atomic_store_bool(&g_debug_state_request.should_run, true);
  cond_signal(&g_debug_state_request.cond);
  mutex_unlock(&g_debug_state_request.mutex);
}

References atomic_store_bool(), debug_state_request_t::cond, cond_signal(), DEBUG_REQUEST_STATE, debug_state_request_t::delay_ns, debug_state_request_t::mutex, mutex_lock, mutex_unlock, debug_state_request_t::request_type, and debug_state_request_t::should_run.

◆ debug_sync_set_main_thread_id()

void debug_sync_set_main_thread_id ( void )

#include <sync.h>

Initialize debug synchronization system.

Returns: 0 on success, non-zero on error

Called at startup to initialize internal structures for sync debugging. Must be called before debug_sync_start_thread().

Safe to call multiple times (idempotent).

See also: debug_sync_start_thread() to start the background Debug thread

Definition at line 639 of file sync.c.

                                         {
  // Save main thread ID for memory reporting (call very early)
  g_debug_main_thread_id = asciichat_thread_current_id();
}

References asciichat_thread_current_id().

Referenced by main().

◆ debug_sync_set_memory_report_interval()

void debug_sync_set_memory_report_interval ( uint64_t interval_ns )

#include <sync.h>

Set periodic memory report interval.

Parameters

interval_ns Interval in nanoseconds (0 to disable)

Configures the debug sync thread to print memory reports at the specified interval. The first report will be printed after interval_ns nanoseconds, subsequent reports will follow at that interval.

Parameters

interval_ns Nanoseconds between reports (0 disables periodic reporting)

Example:

// Print memory report every 5 seconds

debug_sync_set_memory_report_interval(5 * 1000000000ULL);

debug_sync_set_memory_report_interval

void debug_sync_set_memory_report_interval(uint64_t interval_ns)

Set periodic memory report interval.

Definition sync.c:630

See also: debug_memory_report() for the memory report function being called

Parameters

interval_ns Interval in nanoseconds (0 to disable)

Definition at line 630 of file sync.c.

                                                                 {
  g_debug_state_request.memory_report_interval_ns = interval_ns;
  g_debug_state_request.last_memory_report_time_ns = 0; // Reset timer
}

References debug_state_request_t::last_memory_report_time_ns, and debug_state_request_t::memory_report_interval_ns.

◆ debug_sync_start_thread()

int debug_sync_start_thread ( void )

#include <sync.h>

Start background debug thread for scheduled operations.

Returns: 0 on success, non-zero on error

Spawns a background thread that handles scheduled delayed printing operations from debug_sync_print_state_delayed() and debug_sync_print_backtrace_delayed().

Must call debug_sync_init() first.

Typical Initialization

// In main():
debug_sync_init();
debug_sync_start_thread();
 
// Now safe to use delayed printing:
debug_sync_print_state_delayed(100 * 1000000);
 
// At shutdown:
debug_sync_cleanup_thread();
debug_sync_destroy();

Note: Thread will block until first scheduled job arrives; No overhead if no delayed jobs are scheduled; Call debug_sync_cleanup_thread() during shutdown

See also: debug_sync_cleanup_thread() for Shutdown System

Definition at line 657 of file sync.c.

                                  {
  // Initialize mutex and condition variable for signal wakeup
  if (!g_debug_state_request.initialized) {
    mutex_init(&g_debug_state_request.mutex, "debug_sync_state");
    cond_init(&g_debug_state_request.cond, "debug_sync_signal");
    g_debug_state_request.initialized = true;
  }
 
  atomic_store_bool(&g_debug_state_request.should_exit, false);
  int err = asciichat_thread_create(&g_debug_thread, "debug_sync", debug_print_thread_fn, NULL);
  return err;
}

References asciichat_thread_create, atomic_store_bool(), debug_state_request_t::cond, cond_init(), debug_state_request_t::initialized, debug_state_request_t::mutex, mutex_init(), and debug_state_request_t::should_exit.

Referenced by main().

◆ debug_sync_trigger_print()

void debug_sync_trigger_print ( void )

#include <sync.h>

Trigger sync state print immediately (synchronous)

Immediately calls debug_sync_print_state() on the current thread. Unlike debug_sync_print_state_delayed(), this is synchronous and blocking.

Useful for:

Debugging code (breakpoint followed by print)
Signal handlers that need instant output
Testing and validation

Example: Signal Handler

void handle_debug_signal(int sig) {
    // Print state immediately in signal handler
    debug_sync_trigger_print();
}
 
signal(SIGUSR2, handle_debug_signal);  // SIGUSR2 is mapped to sync state printing
// Now: kill -USR2 <pid> triggers immediate state print

Note: Blocks until print is complete; Can be called from signal handlers safely

See also: debug_sync_print_state() for the underlying function; debug_sync_print_state_delayed() for scheduled printing

Definition at line 710 of file sync.c.

                                    {
  // Set flag to trigger printing on debug thread (from SIGUSR1 handler).
  // We don't call debug_sync_print_state() directly here to avoid logging
  // in signal handler context, which could deadlock with logging mutexes.
  // Uses atomic_store for thread-safe flag setting from signal handler.
  //
  // Signal the condition variable to wake up the debug thread immediately
  // (without waiting for the 100ms timeout).
  atomic_store_bool(&g_debug_state_request.signal_triggered, true);
  cond_signal(&g_debug_state_request.cond);
}

References atomic_store_bool(), debug_state_request_t::cond, cond_signal(), and debug_state_request_t::signal_triggered.

Referenced by session_handle_keyboard_input().

Files

Functions

Detailed Description

Purpose

Key Features

Integration with Named Registry

Usage Examples

Development: Print Current Lock State

Production: Periodic State Dumps

Testing: Capture State at Specific Moments

Backtrace on Lock Contention

Output Format

Function Documentation

◆ debug_sync_check_cond_deadlocks()

Output Example

◆ debug_sync_cleanup_thread()

Typical Shutdown Sequence

◆ debug_sync_destroy()

◆ debug_sync_final_cleanup()

◆ debug_sync_get_main_thread_id()

◆ debug_sync_get_stats()

Example Usage

◆ debug_sync_print_backtrace_delayed()

Combined Usage

◆ debug_sync_print_cond_state()

◆ debug_sync_print_mutex_state()

◆ debug_sync_print_rwlock_state()

◆ debug_sync_print_state()

Typical Workflow

◆ debug_sync_print_state_delayed()

Use Cases

◆ debug_sync_set_main_thread_id()

◆ debug_sync_set_memory_report_interval()

◆ debug_sync_start_thread()

Typical Initialization

◆ debug_sync_trigger_print()

Example: Signal Handler