Atomics¶
ATOMIC#T provides atomic storage for integer, BYTE, BOOL, and pointer
payloads. Reference payloads and floating-point payloads are not supported.
Each access names its memory order through a member template argument.
Atomic values expose access and mutation through named member functions.
Assignment, swap, arithmetic, bitwise, increment, decrement, and comparison
operators are unavailable on atomic values. LOAD obtains a payload for
ordinary value operations. Declaration initialization from a payload remains
available; initialization does not publish the object to other threads.
Load, store, and exchange¶
VAR state ATOMIC#I32;
state.STORE#ATOMIC_RELEASE(7);
VAR observed I32 := state.LOAD#ATOMIC_ACQUIRE();
VAR previous I32 := state.EXCHANGE#ATOMIC_ACQREL(9);
LOAD#mode() returns the stored payload. STORE#mode(value) stores a payload
and returns VOID. EXCHANGE#mode(value) replaces the payload and returns the
previous payload. These members are available for every supported payload type.
| Operation | Accepted modes |
|---|---|
LOAD |
NONATOMIC, ATOMIC_RELAXED, ATOMIC_ACQUIRE, ATOMIC_SEQCST |
STORE |
NONATOMIC, ATOMIC_RELAXED, ATOMIC_RELEASE, ATOMIC_SEQCST |
EXCHANGE and integer read-modify-write members |
NONATOMIC, ATOMIC_RELAXED, ATOMIC_RELEASE, ATOMIC_ACQUIRE, ATOMIC_ACQREL, ATOMIC_SEQCST |
NONATOMIC requests ordinary accesses through the atomic storage interface.
Concurrent conflicting accesses require external synchronization when an access
uses this mode.
Integer read-modify-write operations¶
Integer and BYTE atomics provide the following members. Each member has the
form operation#mode(operand) and returns VOID. Each corresponding
FETCH_operation#mode(operand) returns the payload immediately before its
successful update. The operand has type T, except that shift and rotation
amounts have type SZ.
| Member | Updated payload, with prior value x and operand y |
|---|---|
ADD |
x + y |
SUBTRACT |
x - y |
MULTIPLY |
x * y |
DIVIDE |
Integer quotient of x / y |
MODULO |
Integer remainder of x / y |
BIT_AND |
Bitwise AND of x and y |
BIT_OR |
Bitwise OR of x and y |
BIT_XOR |
Bitwise exclusive OR of x and y |
BIT_NAND |
Bitwise complement of AND |
BIT_NOR |
Bitwise complement of OR |
BIT_NXOR |
Bitwise complement of exclusive OR |
BIT_IMPLIES |
Bitwise OR of the complement of x and y |
BIT_IMPLIED |
Bitwise OR of x and the complement of y |
BIT_SHIFT_UP |
Logical shift of x by y bits toward higher bit positions |
BIT_SHIFT_DOWN |
Logical shift of x by y bits toward lower bit positions |
BIT_ROTATE_UP |
Rotation of x by y bits toward higher bit positions |
BIT_ROTATE_DOWN |
Rotation of x by y bits toward lower bit positions |
VAR state ATOMIC#I32 := 12;
VAR previous I32 := state.FETCH_MULTIPLY#ATOMIC_ACQREL(3);
state.DIVIDE#ATOMIC_RELEASE(2);
state.BIT_OR#ATOMIC_RELAXED(1);
Addition, subtraction, and multiplication wrap at the payload bit width. Division truncates toward zero, and a signed remainder has the dividend's sign. Division or remainder by zero, and division or remainder of a signed minimum value by negative one, produce undefined behavior. Bitwise complements are limited to the payload bit width. Shifts at or beyond that width produce zero. Rotation amounts are reduced modulo that width.
These members are unavailable for BOOL and pointer payloads. An atomic
read-modify-write operation uses a native LLVM atomic operation when available,
or a compare-exchange retry loop. Every retry computes a replacement from a
newly observed value. The returned fetch value belongs to the successful
update. Contention can cause repeated retries.
The LLVM backend supports these operations when the atomic storage width fits the target's supported atomic storage limit. Payload widths that require padded atomic storage retain their logical arithmetic and bitwise width. The JVM backend does not currently support atomic read-modify-write lowering.
Compare and exchange¶
Compare-exchange names success and failure orders independently:
VAR expected I32 := 4;
VAR exchanged BOOL := state.COMPARE_EXCHANGE#(
@SUCCESS ATOMIC_ACQREL,
@FAILURE ATOMIC_ACQUIRE
)(@EXPECTED expected, @DESIRED 9);
EXPECTED is a mutable payload reference, and DESIRED is a replacement
payload. Both operand names are required. On success, the operation stores the
desired value, preserves expected, and returns TRUE. On failure, the
operation returns FALSE and writes the observed payload to expected.
| Success mode | Accepted failure modes |
|---|---|
NONATOMIC |
NONATOMIC |
ATOMIC_RELAXED |
ATOMIC_RELAXED |
ATOMIC_RELEASE |
ATOMIC_RELAXED |
ATOMIC_ACQUIRE |
ATOMIC_RELAXED, ATOMIC_ACQUIRE |
ATOMIC_ACQREL |
ATOMIC_RELAXED, ATOMIC_ACQUIRE |
ATOMIC_SEQCST |
ATOMIC_RELAXED, ATOMIC_ACQUIRE, ATOMIC_SEQCST |
The runtime module serializes atomic operations wider than the target's native
atomic width through a shared lock. RV32 uses this path for 64-bit atomics.
These operations preserve their synchronization contract and are not lock-free.
For each member operation OP, the compiler resolves the runtime function
ATOMIC_OP#T. Its named THIS argument refers to the atomic storage; its
remaining arguments and return type match the corresponding member operation.
These runtime declarations are restricted to MODULE(RUNTIME). The standard
runtime uses sequentially consistent locking and bypasses locking during
compile-time evaluation.
The synchronization types in std provide higher-level ownership models.
Related language features are described in
Thread-Local Variables and
Templates and value parameters.