atomic.h File Reference

Debug tracking for atomic operations. More...

Go to the source code of this file.

Functions
void	debug_atomic_register (atomic_t *a, const char *name)
	Register an atomic_t in the debug named registry.
void	debug_atomic_unregister (atomic_t *a)
	Unregister an atomic_t from the debug named registry.
void	debug_atomic_ptr_register (_Atomic(void *) *a, const char *name)
	Register an _Atomic(void *) in the debug named registry.
void	debug_atomic_ptr_unregister (_Atomic(void *) *a)
	Unregister an _Atomic(void *) from the debug named registry.
int	debug_atomic_format_timing (const atomic_t *atomic, char *buffer, size_t size)
	Format timing info for an atomic_t to a buffer.
int	debug_atomic_ptr_format_timing (const atomic_ptr_t *atomic, char *buffer, size_t size)
	Format timing info for an atomic_ptr_t to a buffer.
void	debug_atomic_init (void)
	Lifecycle initialization for debug atomic tracking.
void	debug_atomic_shutdown (void)
	Lifecycle shutdown for debug atomic tracking.
bool	debug_atomic_is_initialized (void)
	Check if debug atomic tracking is initialized.
void	debug_atomic_print_state (void)
	Print all named atomic operations state (integration with –sync-state)

Detailed Description

Debug tracking for atomic operations.

Date

March 2026

Provides debug-only tracking for named atomics via the named.c registry. Integrates with –sync-state output to display atomic timing and counts.

Definition in file debug/atomic.h.

Function Documentation

debug_atomic_format_timing()

int debug_atomic_format_timing	(	const atomic_t *	atomic,
		char *	buffer,
		size_t	size
	)

Format timing info for an atomic_t to a buffer.

Parameters

atomic	Pointer to atomic_t
buffer	Output buffer for formatted timing info
size	Buffer size

Returns

Number of bytes written (0 if never accessed)

Used by –sync-state to display atomic operation timing and counts. Only formats output if the atomic has been accessed.

Format timing info for an atomic_t to a buffer.

Parameters

atomic	Pointer to atomic_t
buffer	Output buffer
size	Buffer size

Returns

Number of bytes written to buffer

Definition at line 53 of file debug/atomic.c.

                                                                                  {
  if (!atomic || !buffer || size == 0)
    return 0;
 
  // If never accessed, return empty (so caller can skip output)
  if (atomic->last_load_time_ns == 0 && atomic->last_store_time_ns == 0) {
    return 0;
  }
 
  int offset = 0;
  uint64_t now_ns = time_get_ns();
 
  char load_str[64] = "";
  char store_str[64] = "";
  char count_str[128] = "";
 
  if (atomic->last_load_time_ns > 0 && atomic->last_load_time_ns <= now_ns) {
    char elapsed_str[64];
    time_pretty(now_ns - atomic->last_load_time_ns, -1, elapsed_str, sizeof(elapsed_str));
    snprintf(load_str, sizeof(load_str), "load=%s", elapsed_str);
  }
 
  if (atomic->last_store_time_ns > 0 && atomic->last_store_time_ns <= now_ns) {
    char elapsed_str[64];
    time_pretty(now_ns - atomic->last_store_time_ns, -1, elapsed_str, sizeof(elapsed_str));
    snprintf(store_str, sizeof(store_str), "store=%s", elapsed_str);
  }
 
  if (atomic->load_count > 0 || atomic->store_count > 0 || atomic->cas_count > 0 || atomic->fetch_count > 0) {
    snprintf(count_str, sizeof(count_str), "[ops: load=%llu store=%llu cas=%llu/%llu fetch=%llu]",
             (unsigned long long)atomic->load_count, (unsigned long long)atomic->store_count,
             (unsigned long long)atomic->cas_success_count, (unsigned long long)atomic->cas_count,
             (unsigned long long)atomic->fetch_count);
  }
 
  offset += snprintf(buffer + offset, size - offset, "%s %s %s", load_str, store_str, count_str);
  return offset;
}

References atomic_t::cas_count, atomic_t::cas_success_count, atomic_t::fetch_count, atomic_t::last_load_time_ns, atomic_t::last_store_time_ns, atomic_t::load_count, atomic_t::store_count, time_get_ns(), and time_pretty().

debug_atomic_init()

void debug_atomic_init

(

void

)

Lifecycle initialization for debug atomic tracking.

In release builds (NDEBUG), this is a no-op macro. In debug builds, this initializes atomic operation tracking.

Definition at line 30 of file debug/atomic.c.

                             {
  g_atomic_debug_initialized = true;
}

Referenced by main().

debug_atomic_is_initialized()

bool debug_atomic_is_initialized

(

void

)

Check if debug atomic tracking is initialized.

In release builds (NDEBUG), returns true. In debug builds, returns actual initialization state.

Definition at line 38 of file debug/atomic.c.

                                       {
  return g_atomic_debug_initialized;
}

debug_atomic_print_state()

void debug_atomic_print_state

(

void

)

Print all named atomic operations state (integration with –sync-state)

Called by debug_sync_print_state() to include atomic operations in sync state output. In release builds (NDEBUG), this is a no-op macro. In debug builds, this prints detailed atomic operation statistics.

Definition at line 138 of file debug/atomic.c.

                                    {
  if (!g_atomic_debug_initialized)
    return;
 
  // Iterate named registry for atomic entries
  // Note: this is now kept for backward compatibility
  // The preferred method is to use sync.c's atomic_iter_callback
  // which integrates atomics into the synchronized output buffer
}

debug_atomic_ptr_format_timing()

int debug_atomic_ptr_format_timing	(	const atomic_ptr_t *	atomic,
		char *	buffer,
		size_t	size
	)

Format timing info for an atomic_ptr_t to a buffer.

Parameters

atomic	Pointer to atomic_ptr_t
buffer	Output buffer for formatted timing info
size	Buffer size

Returns

Number of bytes written (0 if never accessed)

Used by –sync-state to display atomic operation timing and counts. Only formats output if the atomic has been accessed.

Format timing info for an atomic_ptr_t to a buffer.

Parameters

atomic	Pointer to atomic_ptr_t
buffer	Output buffer
size	Buffer size

Returns

Number of bytes written to buffer

Definition at line 99 of file debug/atomic.c.

                                                                                          {
  if (!atomic || !buffer || size == 0)
    return 0;
 
  // If never accessed, return empty (so caller can skip output)
  if (atomic->last_load_time_ns == 0 && atomic->last_store_time_ns == 0) {
    return 0;
  }
 
  int offset = 0;
  uint64_t now_ns = time_get_ns();
 
  char load_str[64] = "";
  char store_str[64] = "";
  char count_str[128] = "";
 
  if (atomic->last_load_time_ns > 0 && atomic->last_load_time_ns <= now_ns) {
    char elapsed_str[64];
    time_pretty(now_ns - atomic->last_load_time_ns, -1, elapsed_str, sizeof(elapsed_str));
    snprintf(load_str, sizeof(load_str), "load=%s", elapsed_str);
  }
 
  if (atomic->last_store_time_ns > 0 && atomic->last_store_time_ns <= now_ns) {
    char elapsed_str[64];
    time_pretty(now_ns - atomic->last_store_time_ns, -1, elapsed_str, sizeof(elapsed_str));
    snprintf(store_str, sizeof(store_str), "store=%s", elapsed_str);
  }
 
  if (atomic->load_count > 0 || atomic->store_count > 0 || atomic->cas_count > 0 || atomic->exchange_count > 0) {
    snprintf(count_str, sizeof(count_str), "[ops: load=%llu store=%llu cas=%llu/%llu exchange=%llu]",
             (unsigned long long)atomic->load_count, (unsigned long long)atomic->store_count,
             (unsigned long long)atomic->cas_success_count, (unsigned long long)atomic->cas_count,
             (unsigned long long)atomic->exchange_count);
  }
 
  offset += snprintf(buffer + offset, size - offset, "%s %s %s", load_str, store_str, count_str);
  return offset;
}

References atomic_ptr_t::cas_count, atomic_ptr_t::cas_success_count, atomic_ptr_t::exchange_count, atomic_ptr_t::last_load_time_ns, atomic_ptr_t::last_store_time_ns, atomic_ptr_t::load_count, atomic_ptr_t::store_count, time_get_ns(), and time_pretty().

debug_atomic_ptr_register()

void debug_atomic_ptr_register	(	_Atomic(void *) *	a,
		const char *	name
	)

Register an _Atomic(void *) in the debug named registry.

Parameters

a	Pointer to _Atomic(void *) to register
name	Human-readable name

debug_atomic_ptr_unregister()

void debug_atomic_ptr_unregister

(

_Atomic(void *) *

a

)

Unregister an _Atomic(void *) from the debug named registry.

Parameters

a	Pointer to _Atomic(void *) to unregister

debug_atomic_register()

void debug_atomic_register	(	atomic_t *	a,
		const char *	name
	)

Register an atomic_t in the debug named registry.

Parameters

a	Pointer to atomic_t to register
name	Human-readable name

Called automatically by atomic_init_impl() in debug builds. Registers the atomic's address as a uintptr_t with the named registry.

debug_atomic_shutdown()

void debug_atomic_shutdown

(

void

)

Lifecycle shutdown for debug atomic tracking.

In release builds (NDEBUG), this is a no-op macro. In debug builds, this cleans up atomic operation tracking.

Definition at line 34 of file debug/atomic.c.

                                 {
  g_atomic_debug_initialized = false;
}

Referenced by asciichat_shared_destroy().

debug_atomic_unregister()

void debug_atomic_unregister

(

atomic_t *

a

)

Unregister an atomic_t from the debug named registry.

Parameters

a	Pointer to atomic_t to unregister

Called automatically by atomic_destroy() in debug builds.