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 memory_order. The order argument is used to specify the ordering constraints of atomic operations. The supported values are:

• memory_order_relaxed
• memory_order_acquire
• memory_order_release
• memory_order_acq_rel
• memory_order_seq_cst

atomic (bool)

proc read(order: memory_order = memory_order_seq_cst): bool¶

Returns:	The stored value.

proc write(value: bool, order: memory_order = memory_order_seq_cst): void¶

Stores value as the new value.

proc exchange(value: bool, order: memory_order = memory_order_seq_cst): bool¶

Stores value as the new value and returns the original value.

proc compareExchange(expected: bool, desired: bool, order: memory_order = memory_order_seq_cst): bool¶

Equivalent to compareExchangeStrong

proc compareExchangeWeak(expected: bool, desired: bool, order: memory_order = memory_order_seq_cst): 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.

proc compareExchangeStrong(expected: bool, desired: bool, order: memory_order = memory_order_seq_cst): 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(order: memory_order = memory_order_seq_cst): bool¶

Stores true as the new value and returns the old value.

proc clear(order: memory_order = memory_order_seq_cst): void¶

Stores false as the new value.

proc waitFor(value: bool, order: memory_order = memory_order_seq_cst): 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 peek(): bool¶

Returns:	Stored value using memory_order_relaxed.

proc poke(value: bool): void¶

Stores value as the new value using memory_order_relaxed.

atomic (T)

proc read(order: memory_order = memory_order_seq_cst): T

Returns:	The stored value.

proc write(value: T, order: memory_order = memory_order_seq_cst): void

Stores value as the new value.

proc exchange(value: T, order: memory_order = memory_order_seq_cst): T

Stores value as the new value and returns the original value.

proc compareExchange(expected: T, desired: T, order: memory_order = memory_order_seq_cst): bool

Equivalent to compareExchangeStrong

proc compareExchangeWeak(expected: T, desired: T, order: memory_order = memory_order_seq_cst): 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.

proc compareExchangeStrong(expected: T, desired: T, order: memory_order = memory_order_seq_cst): 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, order: memory_order = memory_order_seq_cst): 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, order: memory_order = memory_order_seq_cst): void¶

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

proc fetchSub(value: T, order: memory_order = memory_order_seq_cst): 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, order: memory_order = memory_order_seq_cst): void¶

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

proc fetchOr(value: T, order: memory_order = memory_order_seq_cst): 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, order: memory_order = memory_order_seq_cst): void¶

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

Only defined for integer atomic types.

proc fetchAnd(value: T, order: memory_order = memory_order_seq_cst): 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, order: memory_order = memory_order_seq_cst): void¶

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

Only defined for integer atomic types.

proc fetchXor(value: T, order: memory_order = memory_order_seq_cst): 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, order: memory_order = memory_order_seq_cst): void¶

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

Only defined for integer atomic types.

proc waitFor(value: T, order: memory_order = memory_order_seq_cst): void

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

proc peek(): T

Returns:	Stored value using memory_order_relaxed.

proc poke(value: T): void

Stores value as the new value using memory_order_relaxed.