Menu

- Learn
- Documentation
  - Language Reference
  - Library Reference
  - Command-line Reference
  - Feature Overview
  - Articles
- Downloads
- Packages
- Community
  - Blog
  - Orgs using D
  - Twitter
  - Forums
  - IRC
  - Community Discord
  - Wiki
  - GitHub
  - Issues
  - Get involved
  - Contributors
  - Foundation
  - Security Team
  - Donate
  - Sponsors
- Resources
  - Tour
  - Books
  - Tutorials
  - Tools
  - Editors
  - IDEs
  - run.dlang.io
  - Visual D
  - Acknowledgments
  - D Style
  - Glossary
  - Sitemap

Search
Report a bug
If you spot a problem with this page, click here to create a Bugzilla issue.
Improve this page
Quickly fork, edit online, and submit a pull request for this page. Requires a signed-in GitHub account. This works well for small changes. If you'd like to make larger changes you may want to consider using a local clone.

# core.atomic

The atomic module provides basic support for lock-free concurrent programming.
Note: Use the -preview=nosharedaccess compiler flag to detect unsafe individual read or write operations on shared data.
License:
Boost License 1.0
Authors:
Sean Kelly, Alex Rønne Petersen, Manu Evans

Source core/atomic.d

Examples:

    int y = 2;
    shared int x = y; // OK

    //x++; // read modify write error
    x.atomicOp!"+="(1); // OK
    //y = x; // read error with preview flag
    y = x.atomicLoad(); // OK
    assert(y == 3);
    //x = 5; // write error with preview flag
    x.atomicStore(5); // OK
    assert(x.atomicLoad() == 5);

enum `MemoryOrder`: int;
  Specifies the memory ordering semantics of an atomic operation.
  See Also:
  en.cppreference.com/w/cpp/atomic/memory_order
  `raw`
    Not sequenced. Corresponds to LLVM AtomicOrdering.Monotonic and C++11/C11 memory_order_relaxed.
  `acq`
    Hoist-load + hoist-store barrier. Corresponds to LLVM AtomicOrdering.Acquire and C++11/C11 memory_order_acquire.
  `rel`
    Sink-load + sink-store barrier. Corresponds to LLVM AtomicOrdering.Release and C++11/C11 memory_order_release.
  `acq_rel`
    Acquire + release barrier. Corresponds to LLVM AtomicOrdering.AcquireRelease and C++11/C11 memory_order_acq_rel.
  `seq`
    Fully sequenced (acquire + release). Corresponds to LLVM AtomicOrdering.SequentiallyConsistent and C++11/C11 memory_order_seq_cst.
pure nothrow @nogc @trusted T `atomicLoad`(MemoryOrder ms = MemoryOrder.seq, T)(auto ref return scope const T `val`)
if (!is(T == shared(U), U) && !is(T == shared(inout(U)), U) && !is(T == shared(const(U)), U));
pure nothrow @nogc @trusted T `atomicLoad`(MemoryOrder ms = MemoryOrder.seq, T)(auto ref return scope const shared T `val`)
if (!hasUnsharedIndirections!T);
pure nothrow @nogc @trusted TailShared!T `atomicLoad`(MemoryOrder ms = MemoryOrder.seq, T)(auto const shared ref T `val`)
if (hasUnsharedIndirections!T);
  Loads 'val' from memory and returns it. The memory barrier specified by 'ms' is applied to the operation, which is fully sequenced by default. Valid memory orders are MemoryOrder.raw, MemoryOrder.acq, and MemoryOrder.seq.
  Parameters:

  T `val` | The target variable.

  Returns:
  The value of 'val'.
pure nothrow @nogc @trusted void `atomicStore`(MemoryOrder ms = MemoryOrder.seq, T, V)(ref T `val`, V `newval`)
if (!is(T == shared) && !is(V == shared));
pure nothrow @nogc @trusted void `atomicStore`(MemoryOrder ms = MemoryOrder.seq, T, V)(shared ref T `val`, V `newval`)
if (!is(T == class));
pure nothrow @nogc @trusted void `atomicStore`(MemoryOrder ms = MemoryOrder.seq, T, V)(shared ref T `val`, auto shared ref V `newval`)
if (is(T == class));
  Writes 'newval' into 'val'. The memory barrier specified by 'ms' is applied to the operation, which is fully sequenced by default. Valid memory orders are MemoryOrder.raw, MemoryOrder.rel, and MemoryOrder.seq.
  Parameters:

  T `val` | The target variable.
  V `newval` | The value to store.

pure nothrow @nogc @trusted T `atomicFetchAdd`(MemoryOrder ms = MemoryOrder.seq, T)(ref return scope T `val`, size_t `mod`)
if ((__traits(isIntegral, T) || is(T == U*, U)) && !is(T == shared));
pure nothrow @nogc @trusted T `atomicFetchAdd`(MemoryOrder ms = MemoryOrder.seq, T)(ref return scope shared T `val`, size_t `mod`)
if (__traits(isIntegral, T) || is(T == U*, U));
  Atomically adds `mod` to the value referenced by `val` and returns the value `val` held previously. This operation is both lock-free and atomic.
  Parameters:

  T `val` | Reference to the value to modify.
  size_t `mod` | The value to add.

  Returns:
  The value held previously by `val`.
pure nothrow @nogc @trusted T `atomicFetchSub`(MemoryOrder ms = MemoryOrder.seq, T)(ref return scope T `val`, size_t `mod`)
if ((__traits(isIntegral, T) || is(T == U*, U)) && !is(T == shared));
pure nothrow @nogc @trusted T `atomicFetchSub`(MemoryOrder ms = MemoryOrder.seq, T)(ref return scope shared T `val`, size_t `mod`)
if (__traits(isIntegral, T) || is(T == U*, U));
  Atomically subtracts `mod` from the value referenced by `val` and returns the value `val` held previously. This operation is both lock-free and atomic.
  Parameters:

  T `val` | Reference to the value to modify.
  size_t `mod` | The value to subtract.

  Returns:
  The value held previously by `val`.
pure nothrow @nogc @trusted T `atomicExchange`(MemoryOrder ms = MemoryOrder.seq, T, V)(T* `here`, V `exchangeWith`)
if (!is(T == shared) && !is(V == shared));
pure nothrow @nogc @trusted TailShared!T `atomicExchange`(MemoryOrder ms = MemoryOrder.seq, T, V)(shared(T)* `here`, V `exchangeWith`)
if (!is(T == class) && !is(T == interface));
pure nothrow @nogc @trusted shared(T) `atomicExchange`(MemoryOrder ms = MemoryOrder.seq, T, V)(shared(T)* `here`, shared(V) `exchangeWith`)
if (is(T == class) || is(T == interface));
  Exchange `exchangeWith` with the memory referenced by `here`. This operation is both lock-free and atomic.
  Parameters:

  T* `here` | The address of the destination variable.
  V `exchangeWith` | The value to exchange.

  Returns:
  The value held previously by `here`.
template `cas`(MemoryOrder succ = MemoryOrder.seq, MemoryOrder fail = MemoryOrder.seq)
  Performs either compare-and-set or compare-and-swap (or exchange).
  There are two categories of overloads in this template: The first category does a simple compare-and-set. The comparison value (ifThis) is treated as an rvalue.
  The second category does a compare-and-swap (a.k.a. compare-and-exchange), and expects ifThis to be a pointer type, where the previous value of here will be written.
  This operation is both lock-free and atomic.
  Parameters:

  T* here | The address of the destination variable.
  V2 writeThis | The value to store.
  V1 ifThis | The comparison value.

  Returns:
  true if the store occurred, false if not.
  pure nothrow @nogc @trusted bool `cas`(T, V1, V2)(T* `here`, V1 `ifThis`, V2 `writeThis`)
  if (!is(T == shared) && is(T : V1));
    Compare-and-set for non-shared values
  pure nothrow @nogc @trusted bool `cas`(T, V1, V2)(shared(T)* `here`, V1 `ifThis`, V2 `writeThis`)
  if (!is(T == class) && (is(T : V1) || is(shared(T) : V1)));
    Compare-and-set for shared value type
  pure nothrow @nogc @trusted bool `cas`(T, V1, V2)(shared(T)* `here`, shared(V1) `ifThis`, shared(V2) `writeThis`)
  if (is(T == class));
    Compare-and-set for shared reference type (class)
  pure nothrow @nogc @trusted bool `cas`(T, V)(T* `here`, T* `ifThis`, V `writeThis`)
  if (!is(T == shared) && !is(V == shared));
    Compare-and-exchange for non-shared types
  pure nothrow @nogc @trusted bool `cas`(T, V1, V2)(shared(T)* `here`, V1* `ifThis`, V2 `writeThis`)
  if (!is(T == class) && (is(T : V1) || is(shared(T) : V1)));
    Compare and exchange for mixed-sharedness types
  pure nothrow @nogc @trusted bool `cas`(T, V)(shared(T)* `here`, shared(T)* `ifThis`, shared(V) `writeThis`)
  if (is(T == class));
    Compare-and-exchange for class
pure nothrow @nogc @trusted bool `casWeak`(MemoryOrder succ = MemoryOrder.seq, MemoryOrder fail = MemoryOrder.seq, T, V1, V2)(T* `here`, V1 `ifThis`, V2 `writeThis`)
if (!is(T == shared) && is(T : V1));
pure nothrow @nogc @trusted bool `casWeak`(MemoryOrder succ = MemoryOrder.seq, MemoryOrder fail = MemoryOrder.seq, T, V1, V2)(shared(T)* `here`, V1 `ifThis`, V2 `writeThis`)
if (!is(T == class) && (is(T : V1) || is(shared(T) : V1)));
pure nothrow @nogc @trusted bool `casWeak`(MemoryOrder succ = MemoryOrder.seq, MemoryOrder fail = MemoryOrder.seq, T, V1, V2)(shared(T)* `here`, shared(V1) `ifThis`, shared(V2) `writeThis`)
if (is(T == class));
  Stores 'writeThis' to the memory referenced by 'here' if the value referenced by 'here' is equal to 'ifThis'. The 'weak' version of cas may spuriously fail. It is recommended to use `casWeak` only when cas would be used in a loop. This operation is both lock-free and atomic.
  Parameters:

  T* `here` | The address of the destination variable.
  V2 `writeThis` | The value to store.
  V1 `ifThis` | The comparison value.

  Returns:
  true if the store occurred, false if not.
pure nothrow @nogc @trusted bool `casWeak`(MemoryOrder succ = MemoryOrder.seq, MemoryOrder fail = MemoryOrder.seq, T, V)(T* `here`, T* `ifThis`, V `writeThis`)
if (!is(T == shared(S), S) && !is(V == shared(U), U));
pure nothrow @nogc @trusted bool `casWeak`(MemoryOrder succ = MemoryOrder.seq, MemoryOrder fail = MemoryOrder.seq, T, V1, V2)(shared(T)* `here`, V1* `ifThis`, V2 `writeThis`)
if (!is(T == class) && (is(T : V1) || is(shared(T) : V1)));
pure nothrow @nogc @trusted bool `casWeak`(MemoryOrder succ = MemoryOrder.seq, MemoryOrder fail = MemoryOrder.seq, T, V)(shared(T)* `here`, shared(T)* `ifThis`, shared(V) `writeThis`)
if (is(T == class));
  Stores 'writeThis' to the memory referenced by 'here' if the value referenced by 'here' is equal to the value referenced by 'ifThis'. The prior value referenced by 'here' is written to `ifThis` and returned to the user. The 'weak' version of cas may spuriously fail. It is recommended to use `casWeak` only when cas would be used in a loop. This operation is both lock-free and atomic.
  Parameters:

  T* `here` | The address of the destination variable.
  V `writeThis` | The value to store.
  T* `ifThis` | The address of the value to compare, and receives the prior value of `here` as output.

  Returns:
  true if the store occurred, false if not.
pure nothrow @nogc @safe void `atomicFence`(MemoryOrder order = MemoryOrder.seq)();
  Inserts a full load/store memory fence (on platforms that need it). This ensures that all loads and stores before a call to this function are executed before any loads and stores after the call.
pure nothrow @nogc @safe void `pause`();
  Gives a hint to the processor that the calling thread is in a 'spin-wait' loop, allowing to more efficiently allocate resources.
pure nothrow @nogc @safe TailShared!T `atomicOp`(string op, T, V1)(shared ref T `val`, V1 `mod`)
if (__traits(compiles, mixin("*cast(T*)&`val`" ~ op ~ "`mod`")));
  Performs the binary operation 'op' on val using 'mod' as the modifier.
  Parameters:

  T `val` | The target variable.
  V1 `mod` | The modifier to apply.

  Returns:
  The result of the operation.

Copyright © 1999-2023 by the D Language Foundation | Page generated by Ddoc on Tue Aug 1 20:57:20 2023