Atomic<T> structv0.1.0
pub struct Atomic<T> {
// private fields
}
T must be an integer of 8 to 64 bits, bool or a pointer; any other type is refused where the methods are used.
Shared by reference between threads; the value lives inside, so it must outlive every thread that reaches it.
Copying an Atomic copies its current value into a new, unrelated one.
Type parameters
| Name | Description |
|---|---|
T | the value's type: an integer of 8 to 64 bits, bool, or a pointer |
Constructors
Atomic
pub func Atomic(value: T) -> Atomic<T>
An atomic value holding value.
Making one is not itself atomic: it must be finished before another thread can reach it, as any value must be.
| Name | Type | Description |
|---|---|---|
value | T | the initial value |
Returns: an atomic holding value
Methods
Load
pub func Load(&self) -> T
The current value, read with sequential consistency.
Returns: the value
LoadWith
pub func LoadWith(&self, order: MemoryOrder) -> T
The current value, read with order, which must be Relaxed, Acquire or SequentiallyConsistent.
Release and AcquireRelease read as Acquire and SequentiallyConsistent respectively, the nearest orders a
load can have.
| Name | Type | Description |
|---|---|---|
order | MemoryOrder | which other operations may move across this one |
Returns: the value
Store
pub func Store(&self, value: T)
Replaces the value, with sequential consistency.
| Name | Type | Description |
|---|---|---|
value | T | the new value |
StoreWith
pub func StoreWith(&self, value: T, order: MemoryOrder)
Replaces the value with order, which must be Relaxed, Release or SequentiallyConsistent.
Acquire and AcquireRelease store as Release and SequentiallyConsistent respectively, the nearest orders
a store can have.
| Name | Type | Description |
|---|---|---|
value | T | the new value |
order | MemoryOrder | which other operations may move across this one |
Exchange
pub func Exchange(&self, value: T) -> T
Replaces the value and returns the one replaced, as one step, with sequential consistency.
| Name | Type | Description |
|---|---|---|
value | T | the new value |
Returns: the value before
CompareExchange
pub func CompareExchange(
&self,
expected: T,
desired: T
) -> T throws T
Replaces the value with desired if it is expected, as one step, with sequential consistency.
Succeeds with the value before, which is expected, when it replaced it, and fails with the value it found
otherwise, so a loop can retry from what is really there. Never fails spuriously.
| Name | Type | Description |
|---|---|---|
expected | T | the value that must be there |
desired | T | the value to put there |
Returns: the value before, as success when it was replaced and as failure when it was not
CompareExchangeWith
pub func CompareExchangeWith(
&self,
expected: T,
desired: T,
success: MemoryOrder,
failure: MemoryOrder
) -> T throws T
Replaces the value with desired if it is expected, with success when it does and failure when it does
not.
Orders a failure cannot have are strengthened to the nearest it can: Release reads as Relaxed,
AcquireRelease as Acquire, and a failure order stronger than the success order as the success order's
acquire part.
| Name | Type | Description |
|---|---|---|
expected | T | the value that must be there |
desired | T | the value to put there |
success | MemoryOrder | the order when the value is replaced |
failure | MemoryOrder | the order when it is not |
Returns: the value before, as success when it was replaced and as failure when it was not
FetchAdd
pub func FetchAdd(&self, value: T) -> T
Adds value, wrapping on overflow, and returns the value before, as one step, with sequential consistency.
Only for integer T.
| Name | Type | Description |
|---|---|---|
value | T | what to add |
Returns: the value before the addition
FetchSub
pub func FetchSub(&self, value: T) -> T
Subtracts value, wrapping on overflow, and returns the value before, as one step, with sequential
consistency.
Only for integer T.
| Name | Type | Description |
|---|---|---|
value | T | what to subtract |
Returns: the value before the subtraction
FetchAddWith
pub func FetchAddWith(
&self,
value: T,
order: MemoryOrder
) -> T
Adds value with order, wrapping on overflow, and returns the value before.
The relaxed form is what a counter whose value nothing else depends on needs. Only for integer T.
| Name | Type | Description |
|---|---|---|
value | T | what to add |
order | MemoryOrder | which other operations may move across this one |
Returns: the value before the addition
FetchSubWith
pub func FetchSubWith(
&self,
value: T,
order: MemoryOrder
) -> T
Subtracts value with order, wrapping on overflow, and returns the value before.
The release form is what dropping one reference to shared data needs, so that the last one sees every write
the others made. Only for integer T.
| Name | Type | Description |
|---|---|---|
value | T | what to subtract |
order | MemoryOrder | which other operations may move across this one |
Returns: the value before the subtraction
FetchAnd
pub func FetchAnd(&self, value: T) -> T
Combines the value with value by bitwise and, and returns the value before, with sequential consistency.
Only for integer or bool T.
| Name | Type | Description |
|---|---|---|
value | T | the bits to keep |
Returns: the value before
FetchOr
pub func FetchOr(&self, value: T) -> T
Combines the value with value by bitwise or, and returns the value before, with sequential consistency.
Only for integer or bool T.
| Name | Type | Description |
|---|---|---|
value | T | the bits to set |
Returns: the value before
FetchXor
pub func FetchXor(&self, value: T) -> T
Combines the value with value by bitwise exclusive or, and returns the value before, with sequential
consistency.
Only for integer or bool T.
| Name | Type | Description |
|---|---|---|
value | T | the bits to flip |
Returns: the value before
Constants
Zero
pub const Zero: Atomic<int8> = Self { value: 0i8 };
An atomic int8 holding zero, as a constant, so a module variable can start as one through an alias of
Atomic<int8>.
Zero
pub const Zero: Atomic<int16> = Self { value: 0i16 };
An atomic int16 holding zero, as a constant, so a module variable can start as one through an alias of
Atomic<int16>.
Zero
pub const Zero: Atomic<int32> = Self { value: 0i32 };
An atomic int32 holding zero, as a constant, so a module variable can start as one through an alias of
Atomic<int32>.
Zero
pub const Zero: Atomic<int64> = Self { value: 0i64 };
An atomic int64 holding zero, as a constant, so a module variable can start as one through an alias of
Atomic<int64>.
Zero
pub const Zero: Atomic<int> = Self { value: 0 };
An atomic int holding zero, as a constant, so a module variable can start as one through an alias of
Atomic<int>.
Zero
pub const Zero: Atomic<uint8> = Self { value: 0u8 };
An atomic uint8 holding zero, as a constant, so a module variable can start as one through an alias of
Atomic<uint8>.
Zero
pub const Zero: Atomic<uint16> = Self { value: 0u16 };
An atomic uint16 holding zero, as a constant, so a module variable can start as one through an alias of
Atomic<uint16>.
Zero
pub const Zero: Atomic<uint32> = Self { value: 0u32 };
An atomic uint32 holding zero, as a constant, so a module variable can start as one through an alias of
Atomic<uint32>.
Zero
pub const Zero: Atomic<uint64> = Self { value: 0u64 };
An atomic uint64 holding zero, as a constant, so a module variable can start as one through an alias of
Atomic<uint64>.
Zero
pub const Zero: Atomic<uint> = Self { value: 0u };
An atomic uint holding zero, as a constant, so a module variable can start as one through an alias of
Atomic<uint>.
False
pub const False: Atomic<bool> = Self { value: false };
An atomic bool holding false, as a constant, so a module variable can start as one through an alias of
Atomic<bool>.