mutex.c File Reference

Per-thread mutex lock stack for deadlock detection. More...

Go to the source code of this file.

Data Structures
struct	thread_lock_stack_t
struct	thread_registry_entry_t
struct	deadlock_state_t

Macros
#define	MUTEX_STACK_MAX_DEPTH   64
#define	MAX_THREADS   256
#define	MAX_CYCLE_MUTEXES   16
#define	MAX_CYCLE_LEN   64
	DFS-based cycle detection in the waits-for graph Returns cycle start index if found, -1 otherwise Fills cycle_path with indices of threads in the cycle (if found)
#define	COND_DEADLOCK_THRESHOLD_NS   (5ULL * 1000000000ULL)

Functions
void	mutex_stack_push_pending (uintptr_t mutex_key, const char *mutex_name)
	Push a mutex onto the current thread's lock stack (PENDING state)
void	mutex_stack_mark_locked (uintptr_t mutex_key)
	Mark the top of the current thread's lock stack as LOCKED (transitions PENDING -> LOCKED)
void	mutex_stack_pop (uintptr_t mutex_key)
	Pop the top mutex from the current thread's lock stack (unlock)
int	mutex_stack_get_current (mutex_stack_entry_t *out_entries, int max_entries)
	Get the current thread's lock stack.
int	mutex_stack_get_all_threads (mutex_stack_entry_t ***out_stacks, int **out_stack_counts, int *out_thread_count)
	Get all threads' lock stacks for deadlock analysis.
void	mutex_stack_free_all_threads (mutex_stack_entry_t **stacks, int *stack_counts, int thread_count)
	Free memory allocated by mutex_stack_get_all_threads()
void	mutex_stack_detect_deadlocks (void)
	Detect circular wait deadlocks using DFS-based cycle detection.
bool	debug_sync_is_cleanup_in_progress (void)
void	debug_sync_check_cond_deadlocks (void)
	Check all condition variables for deadlocks.
int	mutex_stack_init (void)
	Initialize mutex stack system.
void	mutex_stack_cleanup_current_thread (void)
	Cleanup TLS stack for current thread Explicitly frees the thread-local mutex stack. Used to prevent leaks when TLS destructors might not run reliably (e.g., before TLS key deletion).
void	mutex_stack_cleanup (void)
	Cleanup mutex stack system.

Detailed Description

Per-thread mutex lock stack for deadlock detection.

Date

February 2026

Tracks which mutexes are held and pending per thread. Detects circular wait patterns (classic deadlock condition).

Definition in file debug/mutex.c.

Macro Definition Documentation

COND_DEADLOCK_THRESHOLD_NS

#define COND_DEADLOCK_THRESHOLD_NS   (5ULL * 1000000000ULL)

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

MAX_CYCLE_LEN

#define MAX_CYCLE_LEN   64

DFS-based cycle detection in the waits-for graph Returns cycle start index if found, -1 otherwise Fills cycle_path with indices of threads in the cycle (if found)

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

MAX_CYCLE_MUTEXES

#define MAX_CYCLE_MUTEXES   16

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

MAX_THREADS

#define MAX_THREADS   256

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

MUTEX_STACK_MAX_DEPTH

#define MUTEX_STACK_MAX_DEPTH   64

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

Function Documentation

debug_sync_is_cleanup_in_progress()

bool debug_sync_is_cleanup_in_progress ( void  )

extern

Definition at line 653 of file sync.c.

                                             {
  return atomic_load_bool(&g_cleanup_in_progress);
}

References atomic_load_bool().

Referenced by debug_sync_check_cond_deadlocks().

mutex_stack_cleanup()

void mutex_stack_cleanup

(

void

)

Cleanup mutex stack system.

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

                               {
  // Signal shutdown to prevent new allocations from threads still running
  atomic_store_bool(&g_shutting_down, true);
 
  // Manually free all stacks in the registry
  // This must happen BEFORE deleting the TLS key to avoid double-free
  // (destructor won't run on still-running threads until they exit, by which time
  // these stacks will already be freed)
  int count = atomic_load_int(&g_thread_registry_count);
  for (int i = 0; i < count; i++) {
    if (g_thread_registry[i].stack) {
      // Use raw free() - stacks are allocated with raw malloc(), not SAFE_CALLOC()
      free(g_thread_registry[i].stack);
      g_thread_registry[i].stack = NULL;
    }
  }
 
  // Now delete the TLS key - destructors will see NULL in registry and skip freeing
  // For any threads that haven't been registered yet, destructor will free directly
  if (atomic_load_bool(&g_tls_initialized)) {
    ascii_tls_key_delete(g_tls_mutex_stack);
    atomic_store_bool(&g_tls_initialized, false);
  }
 
  // Clear registry on cleanup using atomic operations
  atomic_store_int(&g_thread_registry_count, 0);
}

References ascii_tls_key_delete(), atomic_load_bool(), atomic_load_int(), atomic_store_bool(), atomic_store_int(), and thread_registry_entry_t::stack.

Referenced by asciichat_shared_destroy().

mutex_stack_cleanup_current_thread()

void mutex_stack_cleanup_current_thread

(

void

)

Cleanup TLS stack for current thread Explicitly frees the thread-local mutex stack. Used to prevent leaks when TLS destructors might not run reliably (e.g., before TLS key deletion).

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

                                              {
  // Explicitly free the current thread's TLS stack
  // This is used to prevent leaks when TLS destructors might not run reliably
  // (e.g., debug threads exiting before mutex_stack_cleanup() deletes the TLS key)
 
  if (!atomic_load_bool(&g_tls_initialized)) {
    return; // TLS not initialized, nothing to clean up
  }
 
  thread_lock_stack_t *stack = (thread_lock_stack_t *)ascii_tls_get(g_tls_mutex_stack);
  if (!stack) {
    return; // No stack allocated for this thread
  }
 
  // Clear from TLS
  ascii_tls_set(g_tls_mutex_stack, NULL);
 
  // Update registry if this thread is registered
  thread_id_t current_thread = asciichat_thread_self();
  registry_lock();
  int count = atomic_load_int(&g_thread_registry_count);
  for (int i = 0; i < count; i++) {
    if (asciichat_thread_equal(g_thread_registry[i].thread_id, current_thread) && g_thread_registry[i].stack == stack) {
      g_thread_registry[i].stack = NULL; // Mark as freed in registry
      break;
    }
  }
 
  // Free the stack (raw free to match raw malloc above)
  free(stack);
  registry_unlock();
}

References ascii_tls_get(), ascii_tls_set(), asciichat_thread_equal, asciichat_thread_self, atomic_load_bool(), atomic_load_int(), thread_registry_entry_t::stack, and thread_id.

Referenced by debug_sync_final_cleanup().

mutex_stack_detect_deadlocks()

void mutex_stack_detect_deadlocks

(

void

)

Detect circular wait deadlocks using DFS-based cycle detection.

Detect and log circular wait deadlocks.

Detects both same-thread and multi-thread deadlock patterns of any length:

Same-thread deadlock:

• Thread tries to acquire a mutex it already holds (recursive lock on non-recursive mutex)

Multi-thread circular wait (2-way, 3-way, N-way):

• Uses DFS to detect cycles in the "waits-for" graph
• Reports all threads involved in the cycle

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

                                        {
  mutex_stack_entry_t **all_stacks = NULL;
  int *stack_counts = NULL;
  int thread_count = 0;
 
  if (mutex_stack_get_all_threads(&all_stacks, &stack_counts, &thread_count) != 0) {
    return;
  }
 
  // Analyze copies instead of stacks changing concurrently on other threads.
  thread_lock_stack_t *snapshots = SAFE_CALLOC(thread_count, sizeof(thread_lock_stack_t), thread_lock_stack_t *);
  for (int i = 0; i < thread_count; i++) {
    snapshots[i].depth = stack_counts[i];
    if (stack_counts[i] > 0)
      memcpy(snapshots[i].stack, all_stacks[i], stack_counts[i] * sizeof(mutex_stack_entry_t));
  }
 
  // Check each thread for deadlock conditions
  for (int i = 0; i < thread_count; i++) {
    thread_lock_stack_t *stack_a = &snapshots[i];
    uintptr_t waiting_for = thread_waiting_for_mutex(stack_a);
 
    if (waiting_for == 0)
      continue; // Thread not waiting
 
    // Same-thread deadlock: thread trying to acquire a mutex it already holds
    if (thread_holds_mutex(stack_a, waiting_for)) {
      log_error("%s", colored_string(LOG_COLOR_ERROR, "╔═══════════════════════════════════════════════════════════╗"));
      log_error("%s", colored_string(LOG_COLOR_ERROR, "║  ⚠️  DEADLOCK DETECTED: Same-thread Recursive Lock  ⚠️  ║"));
      log_error("%s", colored_string(LOG_COLOR_ERROR, "╚═══════════════════════════════════════════════════════════╝"));
      log_error("  Thread Address:        0x%lx", (unsigned long)g_thread_registry[i].thread_id);
      log_error("  Mutex:                 0x%lx", waiting_for);
      log_error("  Issue:                 Thread attempts recursive lock on non-recursive mutex");
      continue;
    }
 
    // Multi-thread circular wait: use DFS to detect cycles
    int cycle_path[MAX_CYCLE_LEN];
    int cycle_len = 0;
    int cycle_start = detect_cycle_dfs(snapshots, thread_count, i, cycle_path, &cycle_len);
 
    if (cycle_start >= 0 && cycle_len > 1) {
      // Collect mutexes involved in this deadlock
      uintptr_t cycle_mutexes[MAX_CYCLE_MUTEXES];
      int mutex_count = 0;
      for (int k = 0; k < cycle_len && mutex_count < MAX_CYCLE_MUTEXES; k++) {
        int thread_idx = cycle_path[k];
        thread_lock_stack_t *stack = &snapshots[thread_idx];
        uintptr_t waiting_for = thread_waiting_for_mutex(stack);
        if (waiting_for != 0) {
          cycle_mutexes[mutex_count++] = waiting_for;
        }
      }
 
      // Check if mutexes are different from last deadlock
      bool is_new_deadlock = deadlock_mutexes_changed(cycle_mutexes, mutex_count);
      if (is_new_deadlock) {
        update_deadlock_state(cycle_mutexes, mutex_count);
      }
 
      // Cycle detected! Build complete message in one string
      char cycle_msg[4096];
      int msg_len = 0;
 
      // Leading newline and header box
      msg_len += snprintf(cycle_msg + msg_len, sizeof(cycle_msg) - msg_len, "\n%s\n",
                          colored_string(LOG_COLOR_ERROR, "╔═════════════════════════════════╗"));
      msg_len += snprintf(cycle_msg + msg_len, sizeof(cycle_msg) - msg_len, "%s\n",
                          colored_string(LOG_COLOR_ERROR, "║  DEADLOCK: Circular Wait Cycle  ║"));
      msg_len += snprintf(cycle_msg + msg_len, sizeof(cycle_msg) - msg_len, "%s\n",
                          colored_string(LOG_COLOR_ERROR, "╚═════════════════════════════════╝"));
 
      // Print each thread in the cycle
      for (int k = 0; k < cycle_len; k++) {
        int thread_idx = cycle_path[k];
        int next_thread_idx = cycle_path[(k + 1) % cycle_len];
 
        thread_lock_stack_t *current_stack = &snapshots[thread_idx];
        uintptr_t current_waiting = thread_waiting_for_mutex(current_stack);
 
        char thread_name[256], mutex_name[256], held_by_name[256];
        NAMED_GET_BY_PTR((uintptr_t)g_thread_registry[thread_idx].thread_id, thread_name, sizeof(thread_name));
        NAMED_GET_BY_PTR((uintptr_t)current_waiting, mutex_name, sizeof(mutex_name));
        NAMED_GET_BY_PTR((uintptr_t)g_thread_registry[next_thread_idx].thread_id, held_by_name, sizeof(held_by_name));
 
        msg_len += snprintf(cycle_msg + msg_len, sizeof(cycle_msg) - msg_len, "  T%d: %s waits for %s (held by %s)%s",
                            k + 1, thread_name, mutex_name, held_by_name, k < cycle_len - 1 ? "\n" : "");
      }
 
      // Log repeated deadlock detections (skip first call, throttle subsequent ones)
      if (!is_new_deadlock) {
        log_error_every(1000000, "%s", cycle_msg); // 1000000 µs = 1 second
      }
    }
  }
 
  SAFE_FREE(snapshots);
  mutex_stack_free_all_threads(all_stacks, stack_counts, thread_count);
}

References colored_string(), thread_lock_stack_t::depth, LOG_COLOR_ERROR, log_error, log_error_every, MAX_CYCLE_LEN, MAX_CYCLE_MUTEXES, mutex_stack_free_all_threads(), mutex_stack_get_all_threads(), NAMED_GET_BY_PTR, SAFE_CALLOC, SAFE_FREE, and thread_id.

mutex_stack_free_all_threads()

void mutex_stack_free_all_threads	(	mutex_stack_entry_t **	stacks,
		int *	stack_counts,
		int	thread_count
	)

Free memory allocated by mutex_stack_get_all_threads()

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

                                                                                                     {
 
  if (!stacks || !stack_counts)
    return;
 
  for (int i = 0; i < thread_count; i++) {
    SAFE_FREE(stacks[i]);
  }
 
  SAFE_FREE(stacks);
  SAFE_FREE(stack_counts);
}

References SAFE_FREE.

Referenced by mutex_stack_detect_deadlocks().

mutex_stack_get_all_threads()

int mutex_stack_get_all_threads	(	mutex_stack_entry_t ***	out_stacks,
		int **	out_stack_counts,
		int *	out_thread_count
	)

Get all threads' lock stacks for deadlock analysis.

Allocates memory for all thread stacks. Caller must free with mutex_stack_free_all_threads().

Parameters

out_stacks	Pointer to array of stacks (one per thread)
out_stack_counts	Array of stack sizes corresponding to out_stacks
out_thread_count	Number of threads with lock stacks

Returns

0 on success, -1 on error

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

                                                                                                                  {
 
  if (!out_stacks || !out_stack_counts || !out_thread_count) {
    return -1;
  }
 
  // Read the thread count with acquire semantics (lock-free, no mutex needed)
  // Use memory_order_seq_cst to ensure we get a consistent snapshot
  int thread_count = atomic_load_int(&g_thread_registry_count);
 
  // Allocate arrays for threads in the registry
  // Note: SAFE_MALLOC takes bytes as first parameter, not count
  *out_stacks = SAFE_CALLOC(thread_count, sizeof(mutex_stack_entry_t *), mutex_stack_entry_t **);
  *out_stack_counts = SAFE_CALLOC(thread_count, sizeof(int), int *);
 
  if (!*out_stacks || !*out_stack_counts) {
    SAFE_FREE(*out_stacks);
    SAFE_FREE(*out_stack_counts);
    return -1;
  }
 
  // Copy each thread's stack from the registry
  // Note: the thread count can change concurrently, so we re-read it in the loop
  // to avoid accessing out-of-bounds memory if threads exit during iteration
  for (int i = 0; i < thread_count; i++) {
    // Re-check thread count in case registry shrank
    int current_registry_count = atomic_load_int(&g_thread_registry_count);
    if (i >= current_registry_count) {
      break;
    }
 
    // Allocate before locking because tracked allocation updates the lock stack.
    (*out_stacks)[i] = SAFE_MALLOC(MUTEX_STACK_MAX_DEPTH * sizeof(mutex_stack_entry_t), mutex_stack_entry_t *);
    (*out_stack_counts)[i] = 0;
    registry_lock();
    thread_lock_stack_t *src = g_thread_registry[i].stack;
    if (src) {
      stack_lock(src);
      int depth = src->depth;
      (*out_stack_counts)[i] = depth;
      memcpy((*out_stacks)[i], src->stack, depth * sizeof(mutex_stack_entry_t));
      stack_unlock(src);
    }
    registry_unlock();
  }
 
  *out_thread_count = thread_count;
  return 0;
}

References atomic_load_int(), thread_lock_stack_t::depth, MUTEX_STACK_MAX_DEPTH, SAFE_CALLOC, SAFE_FREE, SAFE_MALLOC, thread_lock_stack_t::stack, and thread_registry_entry_t::stack.

Referenced by mutex_stack_detect_deadlocks().

mutex_stack_get_current()

int mutex_stack_get_current	(	mutex_stack_entry_t *	out_entries,
		int	max_entries
	)

Get the current thread's lock stack.

Parameters

out_entries	Pointer to array where entries will be stored
max_entries	Maximum number of entries to return

Returns

Number of entries in the stack (may be > max_entries if truncated)

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

                                                                               {
  thread_lock_stack_t *stack = get_thread_local_stack();
  if (!stack || !out_entries) {
    return 0;
  }
 
  stack_lock(stack);
  int depth = stack->depth;
  int count = (depth < max_entries) ? depth : max_entries;
  memcpy(out_entries, stack->stack, count * sizeof(mutex_stack_entry_t));
  stack_unlock(stack);
  return depth; // Return actual depth even if truncated
}

References thread_lock_stack_t::depth, and thread_lock_stack_t::stack.

mutex_stack_init()

int mutex_stack_init

(

void

)

Initialize mutex stack system.

Returns

0 on success, -1 on error

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

                           {
  // No initialization needed - registry uses lock-free atomic operations
  return 0;
}

mutex_stack_mark_locked()

void mutex_stack_mark_locked

(

uintptr_t

mutex_key

)

Mark the top of the current thread's lock stack as LOCKED (transitions PENDING -> LOCKED)

Parameters

mutex_key

Pointer to mutex (must match most recent pending push)

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

                                                  {
  thread_lock_stack_t *stack = get_thread_local_stack();
  if (!stack) {
    return;
  }
 
  // Mark the top of the stack as locked
  stack_lock(stack);
  if (stack->depth == 0) {
    stack_unlock(stack);
    return;
  }
  int top = stack->depth - 1;
  if (stack->stack[top].mutex_key == mutex_key) {
    stack->stack[top].state = MUTEX_STACK_STATE_LOCKED;
    stack->stack[top].timestamp_ns = time_get_ns();
  }
  stack_unlock(stack);
 
  // Thread-local only. Registry is populated on-demand by mutex_stack_get_all_threads()
}

References thread_lock_stack_t::depth, mutex_stack_entry_t::mutex_key, MUTEX_STACK_STATE_LOCKED, thread_lock_stack_t::stack, mutex_stack_entry_t::state, time_get_ns(), and mutex_stack_entry_t::timestamp_ns.

mutex_stack_pop()

void mutex_stack_pop

(

uintptr_t

mutex_key

)

Pop the top mutex from the current thread's lock stack (unlock)

Parameters

mutex_key

Pointer to mutex (used for validation)

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

                                          {
  thread_lock_stack_t *stack = get_thread_local_stack();
  if (!stack) {
    return;
  }
 
  // Validate top matches
  stack_lock(stack);
  if (stack->depth == 0) {
    stack_unlock(stack);
    return;
  }
  int top = stack->depth - 1;
  if (stack->stack[top].mutex_key == mutex_key) {
    stack->depth--;
  }
  stack_unlock(stack);
 
  // Thread-local only. Registry is populated on-demand by mutex_stack_get_all_threads()
}

References thread_lock_stack_t::depth, mutex_stack_entry_t::mutex_key, and thread_lock_stack_t::stack.

mutex_stack_push_pending()

void mutex_stack_push_pending	(	uintptr_t	mutex_key,
		const char *	mutex_name
	)

Push a mutex onto the current thread's lock stack (PENDING state)

Parameters

mutex_key	Pointer to mutex (used as unique ID)
mutex_name	Human-readable name of mutex

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

                                                                           {
  thread_lock_stack_t *stack = get_thread_local_stack();
  if (!stack) {
    return;
  }
 
  // Register this thread in the global registry on first mutex use
  register_thread_if_needed();
 
  stack_lock(stack);
  if (stack->depth >= MUTEX_STACK_MAX_DEPTH) {
    stack_unlock(stack);
    return;
  }
  stack->stack[stack->depth].mutex_key = mutex_key;
  stack->stack[stack->depth].mutex_name = mutex_name;
  stack->stack[stack->depth].state = MUTEX_STACK_STATE_PENDING;
  stack->stack[stack->depth].timestamp_ns = time_get_ns();
  stack->depth++;
  stack_unlock(stack);
}

References thread_lock_stack_t::depth, mutex_stack_entry_t::mutex_key, mutex_stack_entry_t::mutex_name, MUTEX_STACK_MAX_DEPTH, MUTEX_STACK_STATE_PENDING, thread_lock_stack_t::stack, mutex_stack_entry_t::state, time_get_ns(), and mutex_stack_entry_t::timestamp_ns.