atomic_array
Atomic mutable arrays with these properties:
- Atomics are 64 bit integers.
- Atomics can be represented as either signed or unsigned.
- Atomics wrap around at overflow and underflow operations.
- All operations guarantee atomicity. No intermediate results can be seen. The result of one mutation can only be the input to one following mutation.
- All atomic operations are mutually ordered. If atomic B is updated after atomic A, then that is how it will appear to any concurrent readers. No one can read the new value of B and then read the old value of A.
- Indexes into atomic arrays are zero-based. An atomic array of arity N contains N atomics with index from 0 to N-1.
Be aware that JavaScript numbers (and so Gleam Ints) cannot represent
all 64bit ints, so the larger and smaller values that can be contained
within array will lose precision when converted to a Gleam int with
functions such as get and to_list.
Types
A mutable atomic array of 64bit ints, either signed or unsigned depending
on whether it was created with the new_unsigned or new_signed function.
pub type AtomicArraypub type CompareError {
ComparisonOutOfBounds
ComparisonFailed(actual: Int)
}Constructors
-
ComparisonOutOfBounds -
ComparisonFailed(actual: Int)
Functions
pub fn add(
array: AtomicArray,
index: Int,
amount: Int,
) -> Result(Nil, Nil)Add an amount to an int at the given index in the array.
Returns an error if the index is out of bounds.
Will overflow or underflow if the resulting value does not fit in the int size for the array.
pub fn compare_exchange(
in array: AtomicArray,
at index: Int,
expect expected: Int,
replace_with value: Int,
) -> Result(Nil, CompareError)Replace an int in the array with a new one, providing that the int in the array has some expected value.
Returns an error if the index is out of bounds.
pub fn exchange(
in array: AtomicArray,
at index: Int,
replace_with value: Int,
) -> Result(Int, Nil)Replace an int in the array with a new one.
Returns an error if the index is out of bounds.
pub fn get(array: AtomicArray, index: Int) -> Result(Int, Nil)Read an int from the array.
Returns an error if the index is out of bounds.
pub fn new_signed(size size: Int) -> AtomicArrayCreate a new signed 64bit int array.
pub fn new_unsigned(size size: Int) -> AtomicArrayCreate a new unsigned 64bit int array.
pub fn set(
array: AtomicArray,
index: Int,
value: Int,
) -> Result(Nil, Nil)Set the int at the given index to a new value.
Returns an error if the index is out of bounds.
If the new value does not fit for the size of int that the array contains then it will overflow on JavaScript, but an error will be returned on Erlang. If you want to make a pull request to make this consistent then we will accept your changes!
pub fn size(array: AtomicArray) -> IntGet the number of ints in the array.
Atomic arrays cannot be grown or shunk, they always have the same number of elements as they were created with.