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 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.

proc compareExchange(expected: bool, desired: bool, param order: memoryOrder = memoryOrder.seqCst): bool¶

Equivalent to compareExchangeStrong

Note

compareExchange() is deprecated (and will be repurposed in a future release), use compareAndSwap().

proc compareExchangeWeak(expected: bool, desired: bool, param order: memoryOrder = memoryOrder.seqCst): bool¶

Similar to compareExchangeStrong, 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.

Note

compareExchangeWeak() is deprecated (and will be repurposed in a future release), use compareAndSwap().

proc compareExchangeStrong(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.

Note

compareExchangeStrong() is deprecated (and will be repurposed in a future release), use compareAndSwap().

proc peek(): bool¶

Non-atomically reads the stored value.

Note

Default usage of peek() is deprecated, use PeekPoke.

proc poke(value: bool): void¶

Non-atomically writes value.

Note

Default usage of poke() is deprecated, use PeekPoke.

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 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.

Only defined for integer atomic types.

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

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

Only defined for integer atomic types.

proc fetchAnd(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.

Only defined for integer atomic types.

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

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

Only defined for integer atomic types.

proc fetchXor(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.

Only defined for integer atomic types.

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

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

Only defined for integer atomic types.

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

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

proc compareExchange(expected: T, desired: T, param order: memoryOrder = memoryOrder.seqCst): bool

Equivalent to compareExchangeStrong

Note

compareExchange() is deprecated (and will be repurposed in a future release), use compareAndSwap().

proc compareExchangeWeak(expected: T, desired: T, param order: memoryOrder = memoryOrder.seqCst): bool

Similar to compareExchangeStrong, 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.

Note

compareExchangeWeak() is deprecated (and will be repurposed in a future release), use compareAndSwap().

proc compareExchangeStrong(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.

Note

compareExchangeStrong() is deprecated (and will be repurposed in a future release), use compareAndSwap().

proc peek(): T

Non-atomically reads the stored value.

Note

Default usage of peek() is deprecated, use PeekPoke.

proc poke(value: T): void

Non-atomically writes value.

Note

Default usage of poke() is deprecated, use PeekPoke.