From 1315c6457e49595fdd3f91693c0506964416c9f0 Mon Sep 17 00:00:00 2001 From: Sverker Eriksson Date: Thu, 15 Nov 2018 15:24:32 +0100 Subject: erts: Add new module 'atomics' --- erts/doc/src/atomics.xml | 183 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 183 insertions(+) create mode 100644 erts/doc/src/atomics.xml (limited to 'erts/doc/src/atomics.xml') diff --git a/erts/doc/src/atomics.xml b/erts/doc/src/atomics.xml new file mode 100644 index 0000000000..3fca92fb97 --- /dev/null +++ b/erts/doc/src/atomics.xml @@ -0,0 +1,183 @@ + + + + +
+ + 2018 + Ericsson AB. All Rights Reserved. + + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + + + atomics +
+ atomics + Atomic Functions + +

This module provides a set of functions to do atomic operations towards + mutable atomic variables. The implementation utilizes only + atomic hardware instructions without any software level locking, which makes + it very efficient for concurrent access. The atomics are organized into + arrays with the follwing semantics:

+ + +

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 one-based. An atomic array of + arity N contains N atomics with index from 1 to N.

+ + + + + + + +

Identifies an atomic array returned from + new/2.

+ + + + + + + + Create atomic array + +

Create a new atomic array of Arity atomics.

+

Argument Opts is a list of the following possible + options:

+ + {signed, boolean()} +

Indicate if the elements of the array will be treated + as signed or unsigned integers. Default is true (signed).

+

The integer interval for signed atomics are from -(1 bsl 63) + to (1 bsl 63)-1 and for unsigned atomics from 0 to (1 + bsl 64)-1.

+ + + + + + + + Set atomic value + +

Set atomic to Value.

+ + + + + + Read atomic value + +

Read atomic value.

+ + + + + + Add to atomic + +

Add Incr to atomic.

+ + + + + + Atomic add and get + +

Atomic addition and return of the result.

+ + + + + + Subtract from atomic + +

Subtract Decr from atomic.

+ + + + + + Atomic sub and get + +

Atomic subtraction and return of the result.

+ + + + + + Atomic exchange. + +

Atomically replaces the value of the atomic with + Desired and returns the value it held + previously.

+ + + + + + Atomic compare and exchange. + +

Atomically compares the atomic with Expected, + and if those are equal, set atomic to Desired. + Returns ok if Desired was written. Returns + the actual atomic value if not equal to Expected.

+ + + + + + Get information about atomic array. + +

Return information about an atomic array in a map. The map + has the following keys:

+ + size +

The number of atomics in the array.

 + max +

The highest possible value an atomic in this array can + hold.

 + min +

The lowest possible value an atomic in this array can + hold.

 + memory +

Approximate memory consumption for the array in + bytes.

 + + + + + + -- cgit v1.2.3