lock.h

Go to the documentation of this file.

#pragma once
 
// C11 stdatomic.h conflicts with MSVC's C++ <atomic> header on Windows.
#if defined(__cplusplus) && defined(_WIN32)
#include <atomic>
using std::atomic_bool;
using std::atomic_uint_fast32_t;
using std::atomic_uint_fast64_t;
#else
#include <stdatomic.h>
#endif
#include <stdbool.h>
#include <stdint.h>
#include <time.h>
#include "platform/thread.h"
#include "platform/mutex.h"
#include "platform/rwlock.h"
 
// Forward declarations for functions used in inline functions below
uint64_t asciichat_thread_current_id(void);
 
#ifdef DEBUG_LOCKS
// Lock debugging is enabled when DEBUG_LOCKS is defined
#include "util/uthash.h"
#include "util/fnv1a.h"
 
#ifdef __cplusplus
extern "C" {
#endif
 
// ============================================================================
// Constants and Limits
// ============================================================================
 
#define MAX_LOCK_RECORDS 1024     
#define MAX_BACKTRACE_FRAMES 32   
#define MAX_FUNCTION_NAME_LEN 256 
#define MAX_FILE_NAME_LEN 256     
 
// ============================================================================
// Lock Types
// ============================================================================
 
typedef enum {
  LOCK_TYPE_MUTEX = 0,   
  LOCK_TYPE_RWLOCK_READ, 
  LOCK_TYPE_RWLOCK_WRITE 
} lock_type_t;
 
// ============================================================================
// Forward Declarations
// ============================================================================
 
typedef struct lock_record lock_record_t;
 
// ============================================================================
// Lock Record Structure
// ============================================================================
 
struct lock_record {
  uint32_t key;                     
  void *lock_address;               
  lock_type_t lock_type;            
  uint64_t thread_id;               
  struct timespec acquisition_time; 
  const char *file_name;            
  int line_number;                  
  const char *function_name;        
 
  // Backtrace information
  void *backtrace_buffer[MAX_BACKTRACE_FRAMES]; 
  int backtrace_size;                           
  char **backtrace_symbols;                     
 
  UT_hash_handle hash_handle; 
};
 
// ============================================================================
// Lock Usage Statistics Structure
// ============================================================================
 
typedef struct lock_usage_stats {
  uint32_t key;                      
  const char *file_name;             
  int line_number;                   
  const char *function_name;         
  lock_type_t lock_type;             
  uint64_t total_acquisitions;       
  uint64_t total_hold_time_ns;       
  uint64_t max_hold_time_ns;         
  uint64_t min_hold_time_ns;         
  struct timespec first_acquisition; 
  struct timespec last_acquisition;  
  UT_hash_handle hash_handle;        
} lock_usage_stats_t;
 
// ============================================================================
// Lock Debug Manager
// ============================================================================
 
typedef struct lock_debug_manager {
  // Uthash hash tables (head pointers, NULL-initialized)
  lock_record_t *lock_records;      
  lock_usage_stats_t *usage_stats;  
  lock_record_t *orphaned_releases; 
 
  // External rwlocks for thread safety (uthash requires external locking)
  rwlock_t lock_records_lock;      
  rwlock_t usage_stats_lock;       
  rwlock_t orphaned_releases_lock; 
 
  // Statistics (atomic for thread safety)
  atomic_uint_fast64_t total_locks_acquired; 
  atomic_uint_fast64_t total_locks_released; 
  atomic_uint_fast32_t current_locks_held;   
 
  // Debug thread management
  asciichat_thread_t debug_thread;  
  atomic_bool debug_thread_running; 
  atomic_bool debug_thread_created; 
  atomic_bool should_print_locks;   
 
  // Initialization state
  atomic_bool initialized; 
} lock_debug_manager_t;
 
extern lock_debug_manager_t g_lock_debug_manager;
extern atomic_bool g_initializing;
 
// ============================================================================
// Helper Functions
// ============================================================================
 
static inline uint32_t lock_record_key(void *lock_address, lock_type_t lock_type) {
  // Combine lock address, type, and thread ID into a unique key using FNV-1a
  // This prevents key collisions when the same lock is used by different threads
  // Hash all components together using FNV-1a for consistent hashing
  struct {
    uintptr_t addr;
    lock_type_t lock_type;
    uint64_t thread_id;
  } key_data = {.addr = (uintptr_t)lock_address, .lock_type = lock_type, .thread_id = asciichat_thread_current_id()};
  return fnv1a_hash_bytes(&key_data, sizeof(key_data));
}
 
static inline uint32_t usage_stats_key(const char *file_name, int line_number, const char *function_name,
                                       lock_type_t lock_type) {
  // Create a hash from file name, line number, function name, and lock type
  uint32_t hash = fnv1a_hash_string(file_name);
  hash = fnv1a_hash_bytes(&line_number, sizeof(line_number)) ^ hash;
  hash = fnv1a_hash_string(function_name) ^ hash;
  hash = fnv1a_hash_bytes(&lock_type, sizeof(lock_type)) ^ hash;
  return hash;
}
 
// ============================================================================
// Public API Functions
// ============================================================================
 
int lock_debug_init(void);
 
int lock_debug_start_thread(void);
 
void lock_debug_cleanup(void);
 
void lock_debug_cleanup_thread(void);
 
void lock_debug_trigger_print(void);
 
// ============================================================================
// Tracked Lock Functions
// ============================================================================
 
int debug_mutex_lock(mutex_t *mutex, const char *file_name, int line_number, const char *function_name);
 
int debug_mutex_unlock(mutex_t *mutex, const char *file_name, int line_number, const char *function_name);
 
int debug_rwlock_rdlock(rwlock_t *rwlock, const char *file_name, int line_number, const char *function_name);
 
int debug_rwlock_wrlock(rwlock_t *rwlock, const char *file_name, int line_number, const char *function_name);
 
int debug_rwlock_rdunlock(rwlock_t *rwlock, const char *file_name, int line_number, const char *function_name);
 
int debug_rwlock_wrunlock(rwlock_t *rwlock, const char *file_name, int line_number, const char *function_name);
 
// ============================================================================
// Convenience Macros
// ============================================================================
 
#ifdef DEBUG_LOCKS
#define DEBUG_MUTEX_LOCK(mutex) debug_mutex_lock(mutex, __FILE__, __LINE__, __func__)
#define DEBUG_MUTEX_UNLOCK(mutex) debug_mutex_unlock(mutex, __FILE__, __LINE__, __func__)
#define DEBUG_RWLOCK_RDLOCK(rwlock) debug_rwlock_rdlock(rwlock, __FILE__, __LINE__, __func__)
#define DEBUG_RWLOCK_WRLOCK(rwlock) debug_rwlock_wrlock(rwlock, __FILE__, __LINE__, __func__)
#else
#define DEBUG_MUTEX_LOCK(mutex) debug_mutex_lock(mutex, NULL, 0, NULL)
#define DEBUG_MUTEX_UNLOCK(mutex) debug_mutex_unlock(mutex, NULL, 0, NULL)
#define DEBUG_RWLOCK_RDLOCK(rwlock) debug_rwlock_rdlock(rwlock, NULL, 0, NULL)
#define DEBUG_RWLOCK_WRLOCK(rwlock) debug_rwlock_wrlock(rwlock, NULL, 0, NULL)
#endif
 
// ============================================================================
// Statistics and Information Functions
// ============================================================================
 
void lock_debug_get_stats(uint64_t *total_acquired, uint64_t *total_released, uint32_t *currently_held);
 
bool lock_debug_is_initialized(void);
 
void lock_debug_print_state(void);
 
void print_orphaned_release_callback(lock_record_t *record, void *user_data);
 
#ifdef __cplusplus
}
#endif
 
#endif // DEBUG_LOCKS