# atomics

Dark Mode

- Manual
- Standard library
- Index
- devel, stable

Search:
Group by:

Types and operations for atomic operations and lockless algorithms.

Unstable API.

# Imports

macros

# Types

    MemoryOrder {...}{.importcpp: "std::memory_order".} = enum
      moRelaxed, ## No ordering constraints. Only the atomicity and ordering against
                  ## other atomic operations is guaranteed.
      moConsume, ## This ordering is currently discouraged as it's semantics are
                  ## being revised. Acquire operations should be preferred.
      moAcquire, ## When applied to a load operation, no reads or writes in the
                  ## current thread can be reordered before this operation.
      moRelease, ## When applied to a store operation, no reads or writes in the
                  ## current thread can be reorderd after this operation.
      moAcquireRelease, ## When applied to a read-modify-write operation, this behaves like
                         ## both an acquire and a release operation.
      moSequentiallyConsistent ## Behaves like Acquire when applied to load, like Release when
                               ## applied to a store and like AcquireRelease when applied to a
                               ## read-modify-write operation.
                               ## Also guarantees that all threads observe the same total ordering
                               ## with other moSequentiallyConsistent operations.

  Specifies how non-atomic operations can be reordered around atomic operations. Source Edit

    Atomic[T] {...}{.importcpp: "std::atomic".} = object

  An atomic object with underlying type `T`. Source Edit

    AtomicFlag {...}{.importcpp: "std::atomic_flag".} = object

  An atomic boolean state. Source Edit

# Procs

    proc load[T](location: var Atomic[T];
                 order: MemoryOrder = moSequentiallyConsistent): T {...}{.
        importcpp: "#.load(@)", header: "<atomic>".}

  Atomically obtains the value of the atomic object. Source Edit

    proc store[T](location: var Atomic[T]; desired: T;
                  order: MemoryOrder = moSequentiallyConsistent) {...}{.
        importcpp: "#.store(@)", header: "<atomic>".}

  Atomically replaces the value of the atomic object with the `desired` value. Source Edit

    proc exchange[T](location: var Atomic[T]; desired: T;
                     order: MemoryOrder = moSequentiallyConsistent): T {...}{.
        importcpp: "#.exchange(@)", header: "<atomic>".}

  Atomically replaces the value of the atomic object with the `desired` value and returns the old value. Source Edit

    proc compareExchange[T](location: var Atomic[T]; expected: var T; desired: T;
                            order: MemoryOrder = moSequentiallyConsistent): bool {...}{.
        importcpp: "#.compare_exchange_strong(@)", header: "<atomic>".}

  Atomically compares the value of the atomic object with the `expected` value and performs exchange with the `desired` one if equal or load if not. Returns true if the exchange was successful. Source Edit

    proc compareExchange[T](location: var Atomic[T]; expected: var T; desired: T;
                            success, failure: MemoryOrder): bool {...}{.
        importcpp: "#.compare_exchange_strong(@)", header: "<atomic>".}

  Same as above, but allows for different memory orders for success and failure. Source Edit

    proc compareExchangeWeak[T](location: var Atomic[T]; expected: var T;
                                desired: T;
                                order: MemoryOrder = moSequentiallyConsistent): bool {...}{.
        importcpp: "#.compare_exchange_weak(@)", header: "<atomic>".}

  Same as above, but is allowed to fail spuriously. Source Edit

    proc compareExchangeWeak[T](location: var Atomic[T]; expected: var T;
                                desired: T; success, failure: MemoryOrder): bool {...}{.
        importcpp: "#.compare_exchange_weak(@)", header: "<atomic>".}

  Same as above, but allows for different memory orders for success and failure. Source Edit

    proc fetchAdd[T: SomeInteger](location: var Atomic[T]; value: T;
                                  order: MemoryOrder = moSequentiallyConsistent): T {...}{.
        importcpp: "#.fetch_add(@)", header: "<atomic>".}

  Atomically adds a `value` to the atomic integer and returns the original value. Source Edit

    proc fetchSub[T: SomeInteger](location: var Atomic[T]; value: T;
                                  order: MemoryOrder = moSequentiallyConsistent): T {...}{.
        importcpp: "#.fetch_sub(@)", header: "<atomic>".}

  Atomically subtracts a `value` to the atomic integer and returns the original value. Source Edit

    proc fetchAnd[T: SomeInteger](location: var Atomic[T]; value: T;
                                  order: MemoryOrder = moSequentiallyConsistent): T {...}{.
        importcpp: "#.fetch_and(@)", header: "<atomic>".}

  Atomically replaces the atomic integer with it's bitwise AND with the specified `value` and returns the original value. Source Edit

    proc fetchOr[T: SomeInteger](location: var Atomic[T]; value: T;
                                 order: MemoryOrder = moSequentiallyConsistent): T {...}{.
        importcpp: "#.fetch_or(@)", header: "<atomic>".}

  Atomically replaces the atomic integer with it's bitwise OR with the specified `value` and returns the original value. Source Edit

    proc fetchXor[T: SomeInteger](location: var Atomic[T]; value: T;
                                  order: MemoryOrder = moSequentiallyConsistent): T {...}{.
        importcpp: "#.fetch_xor(@)", header: "<atomic>".}

  Atomically replaces the atomic integer with it's bitwise XOR with the specified `value` and returns the original value. Source Edit

    proc testAndSet(location: var AtomicFlag;
                    order: MemoryOrder = moSequentiallyConsistent): bool {...}{.
        importcpp: "#.test_and_set(@)", header: "<atomic>".}

  Atomically sets the atomic flag to true and returns the original value. Source Edit

    proc clear(location: var AtomicFlag;
               order: MemoryOrder = moSequentiallyConsistent) {...}{.
        importcpp: "#.clear(@)", header: "<atomic>".}

  Atomically sets the value of the atomic flag to false. Source Edit

    proc fence(order: MemoryOrder) {...}{.importcpp: "std::atomic_thread_fence(@)",
                                     header: "<atomic>".}

  Ensures memory ordering without using atomic operations. Source Edit

    proc signalFence(order: MemoryOrder) {...}{.importcpp: "std::atomic_signal_fence(@)",
                                           header: "<atomic>".}

  Prevents reordering of accesses by the compiler as would fence, but inserts no CPU instructions for memory ordering. Source Edit

    proc atomicInc[T: SomeInteger](location: var Atomic[T]; value: T = 1) {...}{.inline.}

  Atomically increments the atomic integer by some `value`. Source Edit

    proc atomicDec[T: SomeInteger](location: var Atomic[T]; value: T = 1) {...}{.inline.}

  Atomically decrements the atomic integer by some `value`. Source Edit

    proc `+=`[T: SomeInteger](location: var Atomic[T]; value: T) {...}{.inline.}

  Atomically increments the atomic integer by some `value`. Source Edit

    proc `-=`[T: SomeInteger](location: var Atomic[T]; value: T) {...}{.inline.}

  Atomically decrements the atomic integer by some `value`. Source Edit