# std/sysatomics

Theme:

- Manual
- Standard library
- Index
- Compiler docs
- Fusion docs
- devel, stable

Search:
Source Edit

Perform the operation return the new value, all memory models are validPerform the operation return the old value, all memory models are valid

# Types

    AtomMemModel = distinct cint

  Source Edit

    AtomType = SomeNumber | pointer | ptr | char | bool

  Type Class representing valid types for use with atomic procs Source Edit

# Vars

    ATOMIC_ACQ_REL {.importc: "__ATOMIC_ACQ_REL", nodecl.}: AtomMemModel

  Full barrier in both directions and synchronizes with acquire loads and release stores in another thread. Source Edit

    ATOMIC_ACQUIRE {.importc: "__ATOMIC_ACQUIRE", nodecl.}: AtomMemModel

  Barrier to hoisting of code and synchronizes with release (or stronger) semantic stores from another thread. Source Edit

    ATOMIC_CONSUME {.importc: "__ATOMIC_CONSUME", nodecl.}: AtomMemModel

  Data dependency only for both barrier and synchronization with another thread. Source Edit

    ATOMIC_RELAXED {.importc: "__ATOMIC_RELAXED", nodecl.}: AtomMemModel

  No barriers or synchronization. Source Edit

    ATOMIC_RELEASE {.importc: "__ATOMIC_RELEASE", nodecl.}: AtomMemModel

  Barrier to sinking of code and synchronizes with acquire (or stronger) semantic loads from another thread. Source Edit

    ATOMIC_SEQ_CST {.importc: "__ATOMIC_SEQ_CST", nodecl.}: AtomMemModel

  Full barrier in both directions and synchronizes with acquire loads and release stores in all threads. Source Edit

# Procs

    proc atomicAddFetch[T: AtomType](p: ptr T; val: T; mem: AtomMemModel): T {.
        importc: "__atomic_add_fetch", nodecl, ...raises: [], tags: [], forbids: [].}

  Source Edit

    proc atomicAlwaysLockFree(size: int; p: pointer): bool {.
        importc: "__atomic_always_lock_free", nodecl, ...raises: [], tags: [],
        forbids: [].}

  This built-in function returns true if objects of size bytes always generate lock free atomic instructions for the target architecture. size must resolve to a compile-time constant and the result also resolves to a compile-time constant. ptr is an optional pointer to the object that may be used to determine alignment. A value of 0 indicates typical alignment should be used. The compiler may also ignore this parameter. Source Edit

    proc atomicAndFetch[T: AtomType](p: ptr T; val: T; mem: AtomMemModel): T {.
        importc: "__atomic_and_fetch", nodecl, ...raises: [], tags: [], forbids: [].}

  Source Edit

    proc atomicClear(p: pointer; mem: AtomMemModel) {.importc: "__atomic_clear",
        nodecl, ...raises: [], tags: [], forbids: [].}

  This built-in function performs an atomic clear operation at p. After the operation, at p contains 0. ATOMIC_RELAXED, ATOMIC_SEQ_CST, ATOMIC_RELEASE Source Edit

    proc atomicCompareExchange[T: AtomType](p, expected, desired: ptr T; weak: bool;
                                            success_memmodel: AtomMemModel;
                                            failure_memmodel: AtomMemModel): bool {.
        importc: "__atomic_compare_exchange", nodecl, ...raises: [], tags: [],
        forbids: [].}

  This proc implements the generic version of atomic_compare_exchange. The proc is virtually identical to atomic_compare_exchange_n, except the desired value is also a pointer. Source Edit

    proc atomicCompareExchangeN[T: AtomType](p, expected: ptr T; desired: T;
        weak: bool; success_memmodel: AtomMemModel; failure_memmodel: AtomMemModel): bool {.
        importc: "__atomic_compare_exchange_n", nodecl, ...raises: [], tags: [],
        forbids: [].}

  This proc implements an atomic compare and exchange operation. This compares the contents at p with the contents at expected and if equal, writes desired at p. If they are not equal, the current contents at p is written into expected. Weak is true for weak compare_exchange, and false for the strong variation. Many targets only offer the strong variation and ignore the parameter. When in doubt, use the strong variation. True is returned if desired is written at p and the execution is considered to conform to the memory model specified by success_memmodel. There are no restrictions on what memory model can be used here. False is returned otherwise, and the execution is considered to conform to failure_memmodel. This memory model cannot be __ATOMIC_RELEASE nor __ATOMIC_ACQ_REL. It also cannot be a stronger model than that specified by success_memmodel. Source Edit

    proc atomicDec(memLoc: var int; x: int = 1): int {.inline, discardable,
        ...raises: [], tags: [], forbids: [].}

  Atomically decrements the integer by some `x`. It returns the new value. Source Edit

    proc atomicExchange[T: AtomType](p, val, ret: ptr T; mem: AtomMemModel) {.
        importc: "__atomic_exchange", nodecl, ...raises: [], tags: [], forbids: [].}

  This is the generic version of an atomic exchange. It stores the contents at val at p. The original value at p is copied into ret. Source Edit

    proc atomicExchangeN[T: AtomType](p: ptr T; val: T; mem: AtomMemModel): T {.
        importc: "__atomic_exchange_n", nodecl, ...raises: [], tags: [], forbids: [].}

  This proc implements an atomic exchange operation. It writes val at p, and returns the previous contents at p. ATOMIC_RELAXED, ATOMIC_SEQ_CST, ATOMIC_ACQUIRE, ATOMIC_RELEASE, ATOMIC_ACQ_REL Source Edit

    proc atomicFetchAdd[T: AtomType](p: ptr T; val: T; mem: AtomMemModel): T {.
        importc: "__atomic_fetch_add", nodecl, ...raises: [], tags: [], forbids: [].}

  Source Edit

    proc atomicFetchAnd[T: AtomType](p: ptr T; val: T; mem: AtomMemModel): T {.
        importc: "__atomic_fetch_and", nodecl, ...raises: [], tags: [], forbids: [].}

  Source Edit

    proc atomicFetchNand[T: AtomType](p: ptr T; val: T; mem: AtomMemModel): T {.
        importc: "__atomic_fetch_nand", nodecl, ...raises: [], tags: [], forbids: [].}

  Source Edit

    proc atomicFetchOr[T: AtomType](p: ptr T; val: T; mem: AtomMemModel): T {.
        importc: "__atomic_fetch_or", nodecl, ...raises: [], tags: [], forbids: [].}

  Source Edit

    proc atomicFetchSub[T: AtomType](p: ptr T; val: T; mem: AtomMemModel): T {.
        importc: "__atomic_fetch_sub", nodecl, ...raises: [], tags: [], forbids: [].}

  Source Edit

    proc atomicFetchXor[T: AtomType](p: ptr T; val: T; mem: AtomMemModel): T {.
        importc: "__atomic_fetch_xor", nodecl, ...raises: [], tags: [], forbids: [].}

  Source Edit

    proc atomicInc(memLoc: var int; x: int = 1): int {.inline, discardable,
        ...raises: [], tags: [], forbids: [].}

  Atomically increments the integer by some `x`. It returns the new value. Source Edit

    proc atomicIsLockFree(size: int; p: pointer): bool {.
        importc: "__atomic_is_lock_free", nodecl, ...raises: [], tags: [], forbids: [].}

  This built-in function returns true if objects of size bytes always generate lock free atomic instructions for the target architecture. If it is not known to be lock free a call is made to a runtime routine named __atomic_is_lock_free. ptr is an optional pointer to the object that may be used to determine alignment. A value of 0 indicates typical alignment should be used. The compiler may also ignore this parameter. Source Edit

    proc atomicLoad[T: AtomType](p, ret: ptr T; mem: AtomMemModel) {.
        importc: "__atomic_load", nodecl, ...raises: [], tags: [], forbids: [].}

  This is the generic version of an atomic load. It returns the contents at p in ret. Source Edit

    proc atomicLoadN[T: AtomType](p: ptr T; mem: AtomMemModel): T {.
        importc: "__atomic_load_n", nodecl, ...raises: [], tags: [], forbids: [].}

  This proc implements an atomic load operation. It returns the contents at p. ATOMIC_RELAXED, ATOMIC_SEQ_CST, ATOMIC_ACQUIRE, ATOMIC_CONSUME. Source Edit

    proc atomicNandFetch[T: AtomType](p: ptr T; val: T; mem: AtomMemModel): T {.
        importc: "__atomic_nand_fetch", nodecl, ...raises: [], tags: [], forbids: [].}

  Source Edit

    proc atomicOrFetch[T: AtomType](p: ptr T; val: T; mem: AtomMemModel): T {.
        importc: "__atomic_or_fetch", nodecl, ...raises: [], tags: [], forbids: [].}

  Source Edit

    proc atomicSignalFence(mem: AtomMemModel) {.importc: "__atomic_signal_fence",
        nodecl, ...raises: [], tags: [], forbids: [].}

  This built-in function acts as a synchronization fence between a thread and signal handlers based in the same thread. All memory orders are valid. Source Edit

    proc atomicStore[T: AtomType](p, val: ptr T; mem: AtomMemModel) {.
        importc: "__atomic_store", nodecl, ...raises: [], tags: [], forbids: [].}

  This is the generic version of an atomic store. It stores the value of val at p Source Edit

    proc atomicStoreN[T: AtomType](p: ptr T; val: T; mem: AtomMemModel) {.
        importc: "__atomic_store_n", nodecl, ...raises: [], tags: [], forbids: [].}

  This proc implements an atomic store operation. It writes val at p. ATOMIC_RELAXED, ATOMIC_SEQ_CST, and ATOMIC_RELEASE. Source Edit

    proc atomicSubFetch[T: AtomType](p: ptr T; val: T; mem: AtomMemModel): T {.
        importc: "__atomic_sub_fetch", nodecl, ...raises: [], tags: [], forbids: [].}

  Source Edit

    proc atomicTestAndSet(p: pointer; mem: AtomMemModel): bool {.
        importc: "__atomic_test_and_set", nodecl, ...raises: [], tags: [], forbids: [].}

  This built-in function performs an atomic test-and-set operation on the byte at p. The byte is set to some implementation defined nonzero "set" value and the return value is true if and only if the previous contents were "set". All memory models are valid. Source Edit

    proc atomicThreadFence(mem: AtomMemModel) {.importc: "__atomic_thread_fence",
        nodecl, ...raises: [], tags: [], forbids: [].}

  This built-in function acts as a synchronization fence between threads based on the specified memory model. All memory orders are valid. Source Edit

    proc atomicXorFetch[T: AtomType](p: ptr T; val: T; mem: AtomMemModel): T {.
        importc: "__atomic_xor_fetch", nodecl, ...raises: [], tags: [], forbids: [].}

  Source Edit

    proc cas[T: bool | int | ptr](p: ptr T; oldValue, newValue: T): bool

  Source Edit

    proc cpuRelax() {.inline, ...raises: [], tags: [], forbids: [].}

  Source Edit

# Templates

    template fence()

  Source Edit