core.h.md

vsync / atomic / core.h

Atomic types, core atomic operations and fences.

This file is the main entry point of VSync atomics. You can include it with:

#include <vsync/atomic/core.h>

The declaration and documentation of most atomic operations is split into files based on the atomic type operated by the function as follows:

File	Type
core_u8.h	vatomic8_t and vuint8_t
core_u16.h	vatomic16_t and vuint16_t
core_u32.h	vatomic32_t and vuint32_t
core_u64.h	vatomic64_t and vuint64_t
core_sz.h	vatomicsz_t and vsize_t
core_ptr.h	vatomicptr_t and void *

Major configuration options are described in config.h.

---

Macros

Macro	Description
VATOMIC_INIT	Initializes an atomic variable with value v.
vatomicptr	Declares an atomic pointer type.
vatomic_cpu_pause	Calls CPU pause instruction if available, e.g., PAUSE in x86.
VATOMIC_DISABLE_MACRO_UNDEF	Disables undefines of non-exported macros.

Macro VATOMIC_INIT

VATOMIC_INIT(v)

Initializes an atomic variable with value v.

Macro vatomicptr

vatomicptr(T)

Declares an atomic pointer type.

When declaring an atomic pointer it may be useful to annotate it with the original type. Use vatomicptr(T) macro for that.

Example:

typedef struct mcs_node_s {
   vatomicptr(struct mcs_node_s*) next;
} mcs_node_t;

Macro vatomic_cpu_pause

vatomic_cpu_pause()

Calls CPU pause instruction if available, e.g., PAUSE in x86.

Tight spinloops often overuse the memory subsytem. This macro calls an architecture-dependent instruction to slowdown spinloops (PAUSE in x86 and YIELD in aarch64). Define VSYNC_DISABLE_POLITE_AWAIT to disable the effect of this macro.

Example:

while (!vatomic_read(&flag)) vatomic_cpu_pause();

Macro VATOMIC_DISABLE_MACRO_UNDEF

Disables undefines of non-exported macros.

By default, all non-exported macros are undefined at the end of atomic.h. When VATOMIC_DISABLE_MACRO_UNDEF, no macro is undefined. This is useful for testing.

---

Functions

Function	Description
vatomic_fence	Executes an atomic fence with seq_cst memory order.
vatomic_fence_acq	Executes an atomic fence with acquire memory order.
vatomic_fence_rel	Executes an atomic fence with release memory order.
vatomic_fence_rlx	Executes an atomic fence with relaxed memory order.

Function vatomic_fence

static void vatomic_fence(void)

Executes an atomic fence with seq_cst memory order.

Function vatomic_fence_acq

static void vatomic_fence_acq(void)

Executes an atomic fence with acquire memory order.

Function vatomic_fence_rel

static void vatomic_fence_rel(void)

Executes an atomic fence with release memory order.

Function vatomic_fence_rlx

static void vatomic_fence_rlx(void)

Executes an atomic fence with relaxed memory order.

Note: Technically, there no fence_rlx, it compiles to a NOP.

---