mutex.h

Go to the documentation of this file.

#pragma once

 
/* Storage capacities in elements; text buffers include the terminating NUL. */
#define DEBUG_MUTEX_SPAN_NAME_BUFFER_SIZE 224
#define DEBUG_MUTEX_ERROR_MESSAGE_BUFFER_SIZE 1024
 
/* Existing buffer budgets in bytes, including NUL for text storage. */
#define DEBUG_MUTEX_TRACE_ID_SIZE 16
#define DEBUG_MUTEX_SPAN_ID_SIZE 8
 
#include <stdint.h>
#include <stddef.h>
#include <stdbool.h>
 
#ifdef __cplusplus
extern "C" {
#endif

typedef enum {
  MUTEX_STACK_STATE_PENDING, // Attempting to acquire lock
  MUTEX_STACK_STATE_LOCKED,  // Lock successfully acquired
} mutex_stack_state_t;

typedef struct {
  uintptr_t mutex_key;       // Pointer to mutex_t (used as unique ID)
  const char *mutex_name;    // Human-readable mutex name
  mutex_stack_state_t state; // PENDING or LOCKED
  uint64_t timestamp_ns;     // When this lock was attempted/acquired
} mutex_stack_entry_t;

void mutex_stack_push_pending(uintptr_t mutex_key, const char *mutex_name);

void mutex_stack_push_locked(uintptr_t mutex_key, const char *mutex_name);

void mutex_stack_mark_locked(uintptr_t mutex_key);

void mutex_stack_pop(uintptr_t mutex_key);

int mutex_stack_get_current(mutex_stack_entry_t *out_entries, int max_entries);

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

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

void mutex_stack_detect_deadlocks(void);

typedef struct {
  uintptr_t mutex_key;
  uintptr_t thread_key;
  uint64_t since_ns;
  bool cycle;
  char span_name[DEBUG_MUTEX_SPAN_NAME_BUFFER_SIZE];
  int error_code;
  char error_message[DEBUG_MUTEX_ERROR_MESSAGE_BUFFER_SIZE];
  uint8_t trace_id[DEBUG_MUTEX_TRACE_ID_SIZE], span_id[DEBUG_MUTEX_SPAN_ID_SIZE];
  uint8_t parent_span_id[DEBUG_MUTEX_SPAN_ID_SIZE];
  uint64_t span_start_unix_ns;
  bool context_valid, context_sampled;
} mutex_wait_snapshot_t;
bool mutex_stack_try_snapshot(mutex_wait_snapshot_t *waits, size_t capacity, size_t *count, bool *limited);

int mutex_stack_init(void);

void mutex_stack_cleanup(void);

void mutex_stack_cleanup_current_thread(void);
 
#ifdef __cplusplus
}
#endif