std/atomics

Search:
Source   Edit  

Types and operations for atomic operations and lockless algorithms.

Unstable API.

By default, C++ uses C11 atomic primitives. To use C++ std::atomic, -d:nimUseCppAtomics can be defined.

Example:

import std/atomics
# Atomic
var loc: Atomic[int]
loc.store(4)
assert loc.load == 4
loc.store(2)
assert loc.load(moRelaxed) == 2
loc.store(9)
assert loc.load(moAcquire) == 9
loc.store(0, moRelease)
assert loc.load == 0

assert loc.exchange(7) == 0
assert loc.load == 7

var expected = 7
assert loc.compareExchange(expected, 5, moRelaxed, moRelaxed)
assert expected == 7
assert loc.load == 5

assert not loc.compareExchange(expected, 12, moRelaxed, moRelaxed)
assert expected == 5
assert loc.load == 5

assert loc.fetchAdd(1) == 5
assert loc.fetchAdd(2) == 6
assert loc.fetchSub(3) == 8

loc.atomicInc(1)
assert loc.load == 6

# AtomicFlag
var flag: AtomicFlag

assert not flag.testAndSet
assert flag.testAndSet
flag.clear(moRelaxed)
assert not flag.testAndSet

Types

Atomic[T] {.importcpp: "std::atomic", completeStruct.} = object
An atomic object with underlying type T. Source   Edit   
AtomicFlag {.importcpp: "std::atomic_flag", size: 1.} = object
An atomic boolean state. Source   Edit   
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  

Procs

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   
proc atomicDec[T: SomeInteger](location: var Atomic[T]; value: T = 1) {.inline.}
Atomically decrements the atomic integer by some value. 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 clear(location: var AtomicFlag;
           order: MemoryOrder = moSequentiallyConsistent) {.
    importcpp: "#.clear(@)", header: "<atomic>", ...raises: [], tags: [],
    forbids: [].}
Atomically sets the value of the atomic flag to false. Source   Edit   
proc compareExchange[T](location: var Atomic[T]; expected: var T; desired: T;
                        order: MemoryOrder = moSequentiallyConsistent): bool {.
    importcpp: "#.compare_exchange_strong(@)", header: "<atomic>", ...raises: [],
    tags: [], forbids: [].}
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>", ...raises: [],
    tags: [], forbids: [].}
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>", ...raises: [],
    tags: [], forbids: [].}
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>", ...raises: [],
    tags: [], forbids: [].}
Same as above, but allows for different memory orders for success and failure. Source   Edit   
proc exchange[T](location: var Atomic[T]; desired: T;
                 order: MemoryOrder = moSequentiallyConsistent): T {.
    importcpp: "#.exchange(@)", header: "<atomic>", ...raises: [], tags: [],
    forbids: [].}
Atomically replaces the value of the atomic object with the desired value and returns the old value. Source   Edit   
proc fence(order: MemoryOrder) {.importcpp: "std::atomic_thread_fence(@)",
                                 header: "<atomic>", ...raises: [], tags: [],
                                 forbids: [].}
Ensures memory ordering without using atomic operations. Source   Edit   
proc fetchAdd[T: SomeInteger](location: var Atomic[T]; value: T;
                              order: MemoryOrder = moSequentiallyConsistent): T {.
    importcpp: "#.fetch_add(@)", header: "<atomic>", ...raises: [], tags: [],
    forbids: [].}
Atomically adds 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>", ...raises: [], tags: [],
    forbids: [].}
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>", ...raises: [], tags: [],
    forbids: [].}
Atomically replaces the atomic integer with it's bitwise OR with the specified value 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>", ...raises: [], tags: [],
    forbids: [].}
Atomically subtracts a value to the atomic integer 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>", ...raises: [], tags: [],
    forbids: [].}
Atomically replaces the atomic integer with it's bitwise XOR with the specified value and returns the original value. Source   Edit   
proc load[T](location: var Atomic[T];
             order: MemoryOrder = moSequentiallyConsistent): T {.
    importcpp: "#.load(@)", header: "<atomic>", ...raises: [], tags: [],
    forbids: [].}
Atomically obtains the value of the atomic object. Source   Edit   
proc signalFence(order: MemoryOrder) {.importcpp: "std::atomic_signal_fence(@)",
                                       header: "<atomic>", ...raises: [], tags: [],
                                       forbids: [].}
Prevents reordering of accesses by the compiler as would fence, but inserts no CPU instructions for memory ordering. Source   Edit   
proc store[T](location: var Atomic[T]; desired: T;
              order: MemoryOrder = moSequentiallyConsistent) {.
    importcpp: "#.store(@)", header: "<atomic>", ...raises: [], tags: [],
    forbids: [].}
Atomically replaces the value of the atomic object with the desired value. Source   Edit   
proc testAndSet(location: var AtomicFlag;
                order: MemoryOrder = moSequentiallyConsistent): bool {.
    importcpp: "#.test_and_set(@)", header: "<atomic>", ...raises: [], tags: [],
    forbids: [].}
Atomically sets the atomic flag to true and returns the original value. Source   Edit  

Made with Nim. Generated: 2024-10-02 02:15:04 UTC