std/atomics

Типы и операции для атомарных операций и алгоритмов без блокировок.

Нестабильный API.

По умолчанию, C++ использует атомарные примитивы C11. Для использования C++ std::atomic, -d:nimUseCppAtomics можно определить.

Пример:

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

Типы

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

Атомарный объект с базовым типом T. Source Edit

AtomicFlag {.importcpp: "std::atomic_flag", size: 1.} = object

Атомарное булево состояние. 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.

Определяет, как неатомарные операции могут быть переупорядочены вокруг атомарных операций. Source Edit

Процедуры

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

Атомарно увеличивает атомарное целое число на некоторое value. Исходный код Редактировать

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

Атомарно уменьшает атомарное целое число на некоторое value. Исходный код Редактировать

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

Атомарно уменьшает атомарное целое число на некоторое value. Исходный код Редактировать

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

Атомарно увеличивает атомарное целое число на некоторое value. Исходный код Редактировать

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

Атомарно устанавливает значение атомарного флага в false. Исходный код Редактировать

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: [].}

Атомарно сравнивает значение атомарного объекта с expected значением и выполняет обмен со desired значением, если они равны, или загружает, если нет. Возвращает true, если обмен был успешным. Исходный код Редактировать

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: [].}

То же самое, но допускает разные порядки памяти для успеха и неудачи. Исходный код Редактировать

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: [].}

То же самое, но допускается случайная неудача. Исходный код Редактировать

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: [].}

То же самое, но допускает разные порядки памяти для успеха и неудачи. Исходный код Редактировать

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

Атомарно заменяет значение атомарного объекта на desired значение и возвращает старое значение. Исходный код Редактировать

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

Обеспечивает порядок памяти без использования атомарных операций. Исходный код Редактировать

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

Атомарно добавляет value к атомарному целому числу и возвращает исходное значение. Исходный код Редактировать

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

Атомарно заменяет атомарное целое число его побитовым И с указанным value и возвращает исходное значение. Источник Изменить

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

Атомарно заменяет атомарное целое число его побитовым ИЛИ с указанным value и возвращает исходное значение. Источник Изменить

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

Атомарно вычитает value из атомарного целого числа и возвращает исходное значение. Источник Изменить

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

Атомарно заменяет атомарное целое число его побитовым ИСКЛЮЧАЮЩИМ ИЛИ с указанным value и возвращает исходное значение. Источник Изменить

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

Атомарно получает значение атомарного объекта. Источник Изменить

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

Предотвращает переупорядочение обращений компилятором, как бы фенс, но не вставляет никаких инструкций процессора для упорядочивания памяти. Источник Изменить

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

Атомарно заменяет значение атомарного объекта на desired значение. Источник Изменить

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

Атомарно устанавливает атомарный флаг в true и возвращает исходное значение. Источник Изменить