symbols.c File Reference

🔍 Symbol resolution cache: llvm-symbolizer/addr2line wrapper with hashtable-backed caching More...

Go to the source code of this file.

Data Structures
struct	symbol_entry_t
	Symbol cache entry structure for address-to-symbol mapping. More...

Macros
#define	LLVM_SYMBOLIZER_BIN   "llvm-symbolizer"
#define	ADDR2LINE_BIN   "addr2line"
#define	NULL_SENTINEL   "[NULL]"

Enumerations
enum	symbolizer_type_t { SYMBOLIZER_NONE = 0 , SYMBOLIZER_LLVM = 1 , SYMBOLIZER_ADDR2LINE = 2 }

Functions
asciichat_error_t	symbol_cache_init (void)
void	symbol_cache_destroy (void)
const char *	symbol_cache_lookup (void *addr)
bool	symbol_cache_insert (void *addr, const char *symbol)
void	symbol_cache_get_stats (uint64_t *hits_out, uint64_t *misses_out, size_t *entries_out)
void	symbol_cache_print_stats (void)
char **	symbol_cache_resolve_batch (void *const *buffer, int size)
void	symbol_cache_free_symbols (char **symbols)

Detailed Description

🔍 Symbol resolution cache: llvm-symbolizer/addr2line wrapper with hashtable-backed caching

Definition in file symbols.c.

Macro Definition Documentation

ADDR2LINE_BIN

#define ADDR2LINE_BIN   "addr2line"

Definition at line 15 of file symbols.c.

LLVM_SYMBOLIZER_BIN

#define LLVM_SYMBOLIZER_BIN   "llvm-symbolizer"

Definition at line 14 of file symbols.c.

NULL_SENTINEL

#define NULL_SENTINEL   "[NULL]"

Definition at line 43 of file symbols.c.

Enumeration Type Documentation

symbolizer_type_t

enum symbolizer_type_t

Enumerator
SYMBOLIZER_NONE
SYMBOLIZER_LLVM
SYMBOLIZER_ADDR2LINE

Definition at line 49 of file symbols.c.

             {
  SYMBOLIZER_NONE = 0,      // No symbolizer available, use raw addresses
  SYMBOLIZER_LLVM = 1,      // llvm-symbolizer (preferred on all platforms)
  SYMBOLIZER_ADDR2LINE = 2, // addr2line (fallback)
} symbolizer_type_t;

Function Documentation

symbol_cache_destroy()

void symbol_cache_destroy

(

void

)

Definition at line 292 of file symbols.c.

                                {
  if (!atomic_load(&g_symbol_cache_initialized)) {
    return;
  }
 
  // Mark as uninitialized FIRST to prevent new inserts during cleanup
  atomic_store(&g_symbol_cache_initialized, false);
 
  // Acquire write lock to prevent any concurrent operations
  rwlock_wrlock(&g_symbol_cache_lock);
 
  // Count entries before freeing for debugging
  size_t entry_count = HASH_COUNT(g_symbol_cache);
 
  // Free all symbol entries using HASH_ITER
  symbol_entry_t *entry = NULL, *tmp = NULL;
  size_t freed_count = 0;
  HASH_ITER(hh, g_symbol_cache, entry, tmp) {
    if (entry) {
      HASH_DEL(g_symbol_cache, entry);
      if (entry->symbol) {
        free(entry->symbol);
      }
      free(entry);
      freed_count++;
    }
  }
 
  // Release lock and destroy rwlock
  rwlock_wrunlock(&g_symbol_cache_lock);
  rwlock_destroy(&g_symbol_cache_lock);
 
  g_symbol_cache = NULL;
 
  log_dev("Symbol cache cleaned up: %zu entries counted, %zu entries freed (hits=%llu, misses=%llu)", entry_count,
          freed_count, (unsigned long long)atomic_load(&g_cache_hits),
          (unsigned long long)atomic_load(&g_cache_misses));
}

References symbol_entry_t::symbol.

Referenced by server_main().

symbol_cache_free_symbols()

void symbol_cache_free_symbols

(

char **

symbols

)

Definition at line 921 of file symbols.c.

                                               {
  if (!symbols) {
    return;
  }
 
  // The array is NULL-terminated (allocated with size+1, with result[size] = NULL)
  // The terminator is a SINGLE NULL at index 'size'
  // Failed allocations use the NULL_SENTINEL string "[NULL]" instead of NULL,
  // so there are no NULL entries in the middle - only at the terminator
  // This makes iteration safe: we can iterate until we find the first NULL (the terminator)
 
  // Iterate through entries, freeing all non-NULL entries until we hit the NULL terminator
  for (int i = 0; i < 64; i++) { // Reasonable limit to prevent infinite loop
    if (symbols[i] == NULL) {
      // Found NULL - this is the terminator, stop here
      break;
    }
 
    // Found a non-NULL entry - check if it's the sentinel string
    // Both regular strings and sentinel strings are allocated (with strdup),
    // so we free them all
    SAFE_FREE(symbols[i]);
    symbols[i] = NULL; // Clear pointer after freeing
  }
 
  // Free the array itself
  SAFE_FREE(symbols);
}

symbol_cache_get_stats()

void symbol_cache_get_stats	(	uint64_t *	hits_out,
		uint64_t *	misses_out,
		size_t *	entries_out
	)

Definition at line 412 of file symbols.c.

                                                                                           {
  if (hits_out) {
    *hits_out = atomic_load(&g_cache_hits);
  }
  if (misses_out) {
    *misses_out = atomic_load(&g_cache_misses);
  }
  if (entries_out) {
    rwlock_rdlock(&g_symbol_cache_lock);
    *entries_out = HASH_COUNT(g_symbol_cache);
    rwlock_rdunlock(&g_symbol_cache_lock);
  }
}

symbol_cache_init()

asciichat_error_t symbol_cache_init

(

void

)

Definition at line 264 of file symbols.c.

                                          {
  bool expected = false;
  if (!atomic_compare_exchange_strong(&g_symbol_cache_initialized, &expected, true)) {
    return 0; // Already initialized
  }
 
  // Detect which symbolizer is available (once at init)
  expected = false;
  if (atomic_compare_exchange_strong(&g_symbolizer_detected, &expected, true)) {
    g_symbolizer_type = detect_symbolizer();
  }
 
  // Initialize rwlock for thread safety (uthash requires external locking)
  if (rwlock_init(&g_symbol_cache_lock) != 0) {
    atomic_store(&g_symbol_cache_initialized, false);
    return SET_ERRNO(ERROR_THREAD, "Failed to initialize symbol cache rwlock");
  }
 
  // Initialize uthash head to NULL (required)
  g_symbol_cache = NULL;
 
  atomic_store(&g_cache_hits, 0);
  atomic_store(&g_cache_misses, 0);
 
  log_dev("Symbol cache initialized");
  return 0;
}

References rwlock_init().

symbol_cache_insert()

bool symbol_cache_insert	(	void *	addr,
		const char *	symbol
	)

Definition at line 354 of file symbols.c.

                                                         {
  if (!atomic_load(&g_symbol_cache_initialized) || !addr || !symbol) {
    return false;
  }
 
  // Acquire write lock to make the entire operation atomic
  rwlock_wrlock(&g_symbol_cache_lock);
 
  // Double-check cache is still initialized after acquiring lock
  // (cleanup might have marked it uninitialized between our check and lock acquisition)
  if (!atomic_load(&g_symbol_cache_initialized)) {
    rwlock_wrunlock(&g_symbol_cache_lock);
    return false;
  }
 
  // Check if entry already exists
  symbol_entry_t *existing = NULL;
  HASH_FIND_PTR(g_symbol_cache, &addr, existing);
 
  if (existing) {
    // Entry exists - update symbol if different
    if (existing->symbol && strcmp(existing->symbol, symbol) != 0) {
      // Free old symbol and allocate new one
      free(existing->symbol);
      existing->symbol = platform_strdup(symbol);
      if (!existing->symbol) {
        rwlock_wrunlock(&g_symbol_cache_lock);
        return false;
      }
    }
    rwlock_wrunlock(&g_symbol_cache_lock);
    return true;
  }
 
  // Create new entry
  symbol_entry_t *entry = (symbol_entry_t *)malloc(sizeof(symbol_entry_t));
  if (!entry) {
    rwlock_wrunlock(&g_symbol_cache_lock);
    return false;
  }
 
  entry->addr = addr;
  entry->symbol = platform_strdup(symbol);
  if (!entry->symbol) {
    free(entry);
    rwlock_wrunlock(&g_symbol_cache_lock);
    return false;
  }
 
  // Add to hash table
  HASH_ADD_PTR(g_symbol_cache, addr, entry);
 
  // Release lock
  rwlock_wrunlock(&g_symbol_cache_lock);
 
  return true;
}

References symbol_entry_t::addr, platform_strdup(), and symbol_entry_t::symbol.

Referenced by symbol_cache_resolve_batch().

symbol_cache_lookup()

const char * symbol_cache_lookup

(

void *

addr

)

Definition at line 331 of file symbols.c.

                                            {
  if (!atomic_load(&g_symbol_cache_initialized) || !addr) {
    return NULL;
  }
 
  rwlock_rdlock(&g_symbol_cache_lock);
 
  symbol_entry_t *entry = NULL;
  HASH_FIND_PTR(g_symbol_cache, &addr, entry);
 
  const char *result = NULL;
  if (entry) {
    // Copy string while holding lock to prevent use-after-free
    result = platform_strdup(entry->symbol);
    atomic_fetch_add(&g_cache_hits, 1);
  } else {
    atomic_fetch_add(&g_cache_misses, 1);
  }
 
  rwlock_rdunlock(&g_symbol_cache_lock);
  return result;
}

References platform_strdup(), and symbol_entry_t::symbol.

Referenced by symbol_cache_resolve_batch().

symbol_cache_print_stats()

void symbol_cache_print_stats

(

void

)

Definition at line 426 of file symbols.c.

                                    {
  uint64_t hits = atomic_load(&g_cache_hits);
  uint64_t misses = atomic_load(&g_cache_misses);
 
  rwlock_rdlock(&g_symbol_cache_lock);
  size_t entries = HASH_COUNT(g_symbol_cache);
  rwlock_rdunlock(&g_symbol_cache_lock);
 
  uint64_t total = hits + misses;
  double hit_rate = total > 0 ? (100.0 * (double)hits / (double)total) : 0.0;
 
  log_debug("Symbol Cache Stats: %zu entries, %llu hits, %llu misses (%.1f%% hit rate)", entries,
            (unsigned long long)hits, (unsigned long long)misses, hit_rate);
}

symbol_cache_resolve_batch()

char ** symbol_cache_resolve_batch	(	void *const *	buffer,
		int	size
	)

Definition at line 804 of file symbols.c.

                                                                 {
  if (size <= 0 || !buffer) {
    log_error("Invalid parameters: buffer=%p, size=%d", (void *)buffer, size);
    return NULL;
  }
 
  // DO NOT auto-initialize here - causes circular dependency during lock_debug_init()
  // The cache must be initialized explicitly by platform_init() before use
  if (!atomic_load(&g_symbol_cache_initialized)) {
    // Cache not initialized - fall back to uncached resolution
    // This happens during early initialization before platform_init() completes
    char **result = run_llvm_symbolizer_batch(buffer, size);
    if (!result) {
      result = run_addr2line_batch(buffer, size);
    }
    return result;
  }
 
  // Allocate result array (size + 1 for NULL terminator)
  // CALLOC zeros the memory, so result[size] is already NULL
  char **result = SAFE_CALLOC((size_t)(size + 1), sizeof(char *), char **);
  if (!result) {
    return NULL;
  }
 
  // Ensure NULL terminator is explicitly set (CALLOC already did this, but be explicit)
  result[size] = NULL;
 
  // First pass: check cache for all addresses
  int uncached_count = 0;
  void *uncached_addrs[size];
  int uncached_indices[size];
 
  for (int i = 0; i < size; i++) {
    const char *cached = symbol_cache_lookup(buffer[i]);
    if (cached) {
      // Cache hit - symbol_cache_lookup already duplicated the string
      result[i] = (char *)cached;
    } else {
      // Cache miss - track for batch resolution
      uncached_addrs[uncached_count] = buffer[i];
      uncached_indices[uncached_count] = i;
      uncached_count++;
    }
  }
 
  // Second pass: resolve uncached addresses with selected symbolizer
  if (uncached_count > 0) {
    char **resolved = NULL;
 
    // Use the detected symbolizer type
    switch (g_symbolizer_type) {
    case SYMBOLIZER_LLVM:
      resolved = run_llvm_symbolizer_batch(uncached_addrs, uncached_count);
      break;
    case SYMBOLIZER_ADDR2LINE:
      resolved = run_addr2line_batch(uncached_addrs, uncached_count);
      break;
    case SYMBOLIZER_NONE:
    default:
      // No symbolizer available - will fall through to raw address handling
      resolved = NULL;
      break;
    }
 
    if (resolved) {
      for (int i = 0; i < uncached_count; i++) {
        int orig_idx = uncached_indices[i];
        if (resolved[i]) {
          result[orig_idx] = platform_strdup(resolved[i]);
          // If strdup failed, use sentinel string instead of NULL
          if (!result[orig_idx]) {
            log_error("Failed to duplicate string for result[%d]", orig_idx);
            result[orig_idx] = platform_strdup(NULL_SENTINEL);
          }
          // Only insert into cache if strdup succeeded (and it's not the sentinel)
          if (result[orig_idx] && strcmp(result[orig_idx], NULL_SENTINEL) != 0) {
            if (!symbol_cache_insert(uncached_addrs[i], resolved[i])) {
              log_error("Failed to insert symbol into cache for result[%d]", orig_idx);
            }
          }
          SAFE_FREE(resolved[i]);
        } else {
          // resolved[i] is NULL - use sentinel string
          if (!result[orig_idx]) {
            result[orig_idx] = platform_strdup(NULL_SENTINEL);
          }
        }
        if (!result[orig_idx]) {
          log_error("Failed to allocate memory for result[%d]", orig_idx);
        }
      }
 
      SAFE_FREE(resolved);
 
    } else {
      // addr2line failed - fill uncached entries with raw addresses or sentinel
      for (int i = 0; i < uncached_count; i++) {
        int orig_idx = uncached_indices[i];
        if (!result[orig_idx]) {
          result[orig_idx] = SAFE_MALLOC(32, char *);
          if (result[orig_idx]) {
            SAFE_SNPRINTF(result[orig_idx], 32, "%p", uncached_addrs[i]);
          } else {
            result[orig_idx] = platform_strdup(NULL_SENTINEL);
          }
        }
        if (!result[orig_idx]) {
          log_error("Failed to allocate memory for result[%d]", orig_idx);
        }
      }
    }
  }
 
  return result;
}

References NULL_SENTINEL, platform_strdup(), symbol_cache_insert(), symbol_cache_lookup(), SYMBOLIZER_ADDR2LINE, SYMBOLIZER_LLVM, and SYMBOLIZER_NONE.