Atomic

Owns inline scalar storage accessed atomically after publication. Atomic operations synchronize only their documented publication; they do not make unrelated payload races safe. No allocation or native runtime is required. Noncopy; move only before publication or under external synchronization. Every operation on moved storage traps. Fetch integer arithmetic wraps modulo width. Sequential consistency is default; explicit orders are validated per operation.

Module std.sync

import std.sync;

Public declaration contracts and authored examples. A page can document several related symbols. Implementation bodies are excluded.

pub final class Atomic<T> where T: AtomicValue, Copyable

Example

module example.atomic;
from std.sync import Atomic, MemoryOrder;
fn Main() -> i32 {
    let Count = Atomic<i32>(40);
    if Count.FetchAdd(2) != 40 || Count.Load() != 42 { return 1; }
    var Expected: i32 = 41;
    if Count.CompareExchange(Expected, 50) || Expected != 42 { return 2; }
    if !Count.CompareExchange(Expected, 50, .AcqRel, .Acquire) { return 3; }
    if Count.Exchange(42) != 50 { return 4; }
    let Ready = Atomic<bool>(false);
    Ready.Store(true, .Release);
    if !Ready.Load(.Acquire) { return 5; }
    // Fetch operations return the preceding value. Exercise both explicit
    // ordering and the sequentially consistent convenience overloads.
    let Bits = Atomic<u32>(15_u32);
    if Bits.FetchAnd(10_u32, .AcqRel) != 15_u32 || Bits.FetchAnd(15_u32) != 10_u32 { return 6; }
    if Bits.FetchOr(4_u32, .AcqRel) != 10_u32 || Bits.FetchOr(1_u32) != 14_u32 { return 7; }
    if Bits.FetchXor(12_u32, .Relaxed) != 15_u32 || Bits.FetchXor(2_u32) != 3_u32 { return 8; }
    if Bits.FetchSubtract(1_u32, .AcqRel) != 1_u32 || Bits.Load() != 0_u32 { return 9; }
    Bits.Store(2_u32);
    if Bits.FetchSubtract(1_u32) != 2_u32 || Bits.Load() != 1_u32 { return 10; }
    // Capability observation does not require a particular lock-free result.
    let Capability = Ready.IsLockFree;
    return Count.Load(.Relaxed) - 42;
}

Atomic.init

pub init(mut Value: T)

Initializes unpublished atomic storage without allocation. Value: Initial scalar value.

Atomic.init

pub init(Source: readonly Self&) = delete;

Rejects accidental duplication of published atomic identity. Source: Existing atomic owner.

Atomic.init

pub init(Source: mut Self&&)

Transfers unpublished/externally synchronized identity and recomputes address. Source: Owner left inert. Warning: No concurrent operation may race this move.

Atomic.operator

pub fn operator =(Source: readonly Self&) -> void = delete;

Rejects accidental duplication. Source: Existing owner. Return: No runtime result; this assignment is deleted and cannot be invoked.

Atomic.operator

pub fn operator =(Source: mut Self&&) -> void = delete;

Rejects replacing potentially published identity. Source: Existing owner. Return: No runtime result; this assignment is deleted and cannot be invoked.

Atomic.IsEmpty

pub IsEmpty: bool;

Observes moved/inert authority; moving requires external synchronization.

Atomic.IsLockFree

pub IsLockFree: bool;

Observes lock-free capability for this target and actual storage alignment. Return: Target capability, with no guarantee that every supported scalar is lock-free.

Atomic.Load

pub readonly fn Load(Order: MemoryOrder) -> T

Atomically observes value with operation-valid ordering. Order: Relaxed/Acquire/SeqCst. Return: Observed scalar copy.

Atomic.Load

pub readonly fn Load() -> T

Supplies the omitted arguments to Load. Note: Defaults: Order = .SeqCst. Return: Observed scalar copy with sequentially consistent ordering.

Atomic.Store

pub readonly fn Store(mut Value: T, Order: MemoryOrder) -> void

Atomically publishes replacement value. Value: Replacement scalar. Order: Relaxed/Release/SeqCst. Return: No value.

Atomic.Store

pub readonly fn Store(mut Value: T) -> void

Supplies the omitted arguments to Store. Note: Defaults: Order = .SeqCst. Value: Same input, ownership and lifetime contract as the full operation. Return: No value; publishes through the sequentially consistent operation.

Atomic.Exchange

pub readonly fn Exchange(mut Value: T, Order: MemoryOrder) -> T

Atomically replaces value and returns the preceding scalar. Value: Replacement scalar. Order: Any valid atomic order. Return: Previous scalar copy.

Atomic.Exchange

pub readonly fn Exchange(mut Value: T) -> T

Supplies the omitted arguments to Exchange. Note: Defaults: Order = .SeqCst. Value: Same input, ownership and lifetime contract as the full operation. Return: Previous scalar copy with sequentially consistent ordering.

Atomic.CompareExchange

pub readonly fn CompareExchange(Expected: mut T&, mut Desired: T, Order: MemoryOrder) -> bool

Performs strong CAS, deriving failure observation ordering from Order. Expected: Compared scalar, replaced with observed storage on failure. Desired: Replacement on success. Order: Any valid atomic order. Return: True on replacement; false updates Expected without changing storage.

Atomic.CompareExchange

pub readonly fn CompareExchange(Expected: mut T&, mut Desired: T) -> bool

Supplies the omitted arguments to CompareExchange. Note: Defaults: Order = .SeqCst. Expected: Same input, ownership and lifetime contract as the full operation. Desired: Same input, ownership and lifetime contract as the full operation. Return: True on replacement; otherwise false with Expected updated to the observed scalar.

Atomic.CompareExchange

pub readonly fn CompareExchange(Expected: mut T&, mut Desired: T, Success: MemoryOrder, Failure: MemoryOrder) -> bool

Performs strong CAS with explicit operation-valid success/failure orders. Expected: Compared scalar, updated only on failure. Desired: Replacement. Success: Success ordering. Failure: Observation-only ordering no stronger than Success. Return: True on replacement, otherwise false with observed value in Expected.

Atomic.FetchAdd

pub readonly fn FetchAdd(mut Value: T, Order: MemoryOrder) -> T where T: AtomicInteger

Atomically adds modulo integer width and returns the preceding integer. Value: Integer operand. Order: Any valid atomic order. Return: Previous integer copy.

Atomic.FetchAdd

pub readonly fn FetchAdd(mut Value: T) -> T where T: AtomicInteger

Supplies the omitted arguments to FetchAdd. Note: Defaults: Order = .SeqCst. Value: Same input, ownership and lifetime contract as the full operation. Return: Previous integer copy before sequentially consistent wrapping addition.

Atomic.FetchSubtract

pub readonly fn FetchSubtract(mut Value: T, Order: MemoryOrder) -> T where T: AtomicInteger

Atomically subtracts modulo integer width and returns the preceding integer. Value: Integer operand. Order: Any valid atomic order. Return: Previous integer copy.

Atomic.FetchSubtract

pub readonly fn FetchSubtract(mut Value: T) -> T where T: AtomicInteger

Supplies the omitted arguments to FetchSubtract. Note: Defaults: Order = .SeqCst. Value: Same input, ownership and lifetime contract as the full operation. Return: Previous integer copy before sequentially consistent wrapping subtraction.

Atomic.FetchAnd

pub readonly fn FetchAnd(mut Value: T, Order: MemoryOrder) -> T where T: AtomicInteger

Atomically intersects bit masks and returns the preceding integer. Value: Integer operand. Order: Any valid atomic order. Return: Previous integer copy.

Atomic.FetchAnd

pub readonly fn FetchAnd(mut Value: T) -> T where T: AtomicInteger

Supplies the omitted arguments to FetchAnd. Note: Defaults: Order = .SeqCst. Value: Same input, ownership and lifetime contract as the full operation. Return: Previous integer copy before the sequentially consistent mask intersection.

Atomic.FetchOr

pub readonly fn FetchOr(mut Value: T, Order: MemoryOrder) -> T where T: AtomicInteger

Atomically combines bit masks and returns the preceding integer. Value: Integer operand. Order: Any valid atomic order. Return: Previous integer copy.

Atomic.FetchOr

pub readonly fn FetchOr(mut Value: T) -> T where T: AtomicInteger

Supplies the omitted arguments to FetchOr. Note: Defaults: Order = .SeqCst. Value: Same input, ownership and lifetime contract as the full operation. Return: Previous integer copy before the sequentially consistent mask union.

Atomic.FetchXor

pub readonly fn FetchXor(mut Value: T, Order: MemoryOrder) -> T where T: AtomicInteger

Atomically toggles selected bits and returns the preceding integer. Value: Integer operand. Order: Any valid atomic order. Return: Previous integer copy.

Atomic.FetchXor

pub readonly fn FetchXor(mut Value: T) -> T where T: AtomicInteger

Supplies the omitted arguments to FetchXor. Note: Defaults: Order = .SeqCst. Value: Same input, ownership and lifetime contract as the full operation. Return: Previous integer copy before the sequentially consistent bit toggle.