Atomics¶

Atomic variables are variables that support atomic operations. Chapel currently supports atomic operations for bools, all supported sizes of signed and unsigned integers, as well as all supported sizes of reals.

Most atomic methods accept an optional argument named order of type memoryOrder. The order argument is used to specify the ordering constraints of atomic operations. The supported values are:

memoryOrder.relaxed

memoryOrder.acquire

memoryOrder.release

memoryOrder.acqRel

memoryOrder.seqCst

proc atomicFence(param order: memoryOrder = memoryOrder.seqCst)¶: An atomic fence that establishes an ordering of non-atomic and relaxed atomic operations.

atomic (bool)

proc read(param order: memoryOrder = memoryOrder.seqCst): bool¶

Returns:	The stored value.

proc write(value: bool, param order: memoryOrder = memoryOrder.seqCst): void¶: Stores value as the new value.

proc exchange(value: bool, param order: memoryOrder = memoryOrder.seqCst): bool¶: Stores value as the new value and returns the original value.

proc compareExchange(ref expected: bool, desired: bool, param order: memoryOrder = memoryOrder.seqCst): bool¶: Stores desired as the new value, if and only if the original value is equal to expected. Returns true if desired was stored, otherwise updates expected to the original value.

proc compareExchange(ref expected: bool, desired: bool, param success: memoryOrder, param failure: memoryOrder): bool

proc compareExchangeWeak(ref expected: bool, desired: bool, param order: memoryOrder = memoryOrder.seqCst): bool¶: Similar to compareExchange, except that this function may return false even if the original value was equal to expected. This may happen if the value could not be updated atomically.

proc compareExchangeWeak(ref expected: bool, desired: bool, param success: memoryOrder, param failure: memoryOrder)

proc compareAndSwap(expected: bool, desired: bool, param order: memoryOrder = memoryOrder.seqCst): bool¶: Stores desired as the new value, if and only if the original value is equal to expected. Returns true if desired was stored.

proc testAndSet(param order: memoryOrder = memoryOrder.seqCst): bool¶: Stores true as the new value and returns the old value.

proc clear(param order: memoryOrder = memoryOrder.seqCst): void¶: Stores false as the new value.

proc waitFor(value: bool, param order: memoryOrder = memoryOrder.seqCst): void¶

Arguments:	value – Value to compare against.

Waits until the stored value is equal to value. The implementation may yield the running task while waiting.

atomic (T)

proc read(param order: memoryOrder = memoryOrder.seqCst): T

Returns:	The stored value.

proc write(value: T, param order: memoryOrder = memoryOrder.seqCst): void: Stores value as the new value.

proc exchange(value: T, param order: memoryOrder = memoryOrder.seqCst): T: Stores value as the new value and returns the original value.

proc compareExchange(ref expected: T, desired: T, param order: memoryOrder = memoryOrder.seqCst): bool: Stores desired as the new value, if and only if the original value is equal to expected. Returns true if desired was stored, otherwise updates expected to the original value.

proc compareExchange(ref expected: T, desired: T, param success: memoryOrder, param failure: memoryOrder): bool

proc compareExchangeWeak(ref expected: T, desired: T, param order: memoryOrder = memoryOrder.seqCst): bool: Similar to compareExchange, except that this function may return false even if the original value was equal to expected. This may happen if the value could not be updated atomically.

proc compareExchangeWeak(ref expected: T, desired: T, param success: memoryOrder, param failure: memoryOrder): bool

proc compareAndSwap(expected: T, desired: T, param order: memoryOrder = memoryOrder.seqCst): bool: Stores desired as the new value, if and only if the original value is equal to expected. Returns true if desired was stored.

proc fetchAdd(value: T, param order: memoryOrder = memoryOrder.seqCst): T¶

Returns:	The original value.

Adds value to the original value and stores the result. Defined for integer and real atomic types.

proc add(value: T, param order: memoryOrder = memoryOrder.seqCst): void¶: Adds value to the original value and stores the result. Defined for integer and real atomic types.

proc fetchSub(value: T, param order: memoryOrder = memoryOrder.seqCst): T¶

Returns:	The original value.

Subtracts value from the original value and stores the result. Defined for integer and real atomic types.

proc sub(value: T, param order: memoryOrder = memoryOrder.seqCst): void¶: Subtracts value from the original value and stores the result. Defined for integer and real atomic types.

proc fetchOr(value: T, param order: memoryOrder = memoryOrder.seqCst): T¶

Returns:	The original value.

Applies the | operator to value and the original value, then stores the result.