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/Makefile | 10 +-- erts/doc/src/atomics.xml | 183 +++++++++++++++++++++++++++++++++++++++++++++++ erts/doc/src/ref_man.xml | 1 + erts/doc/src/specs.xml | 1 + 4 files changed, 188 insertions(+), 7 deletions(-) create mode 100644 erts/doc/src/atomics.xml (limited to 'erts/doc') diff --git a/erts/doc/src/Makefile b/erts/doc/src/Makefile index fccdd744f3..56f8f40069 100644 --- a/erts/doc/src/Makefile +++ b/erts/doc/src/Makefile @@ -53,19 +53,15 @@ XML_REF3_EFILES = \ erl_tracer.xml \ init.xml \ persistent_term.xml \ + atomics.xml \ zlib.xml XML_REF3_FILES = \ + $(XML_REF3_EFILES) \ driver_entry.xml \ erl_nif.xml \ - erl_tracer.xml \ erl_driver.xml \ - erl_prim_loader.xml \ - erlang.xml \ - erts_alloc.xml \ - init.xml \ - persistent_term.xml \ - zlib.xml + erts_alloc.xml XML_PART_FILES = \ part.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.

 + + + + + + diff --git a/erts/doc/src/ref_man.xml b/erts/doc/src/ref_man.xml index ff64aa86b8..98f7bbbb8b 100644 --- a/erts/doc/src/ref_man.xml +++ b/erts/doc/src/ref_man.xml @@ -50,5 +50,6 @@ + diff --git a/erts/doc/src/specs.xml b/erts/doc/src/specs.xml index 1ab6cdc19e..784212dfa0 100644 --- a/erts/doc/src/specs.xml +++ b/erts/doc/src/specs.xml @@ -6,4 +6,5 @@ + -- cgit v1.2.3 From fefb5d039e87ff7137e78b3d5f2eaf01e498ec4d Mon Sep 17 00:00:00 2001 From: Sverker Eriksson Date: Tue, 25 Sep 2018 13:34:52 +0200 Subject: erts: Add new module 'counters' --- erts/doc/src/Makefile | 1 + erts/doc/src/counters.xml | 142 ++++++++++++++++++++++++++++++++++++++++++++++ erts/doc/src/ref_man.xml | 1 + erts/doc/src/specs.xml | 1 + 4 files changed, 145 insertions(+) create mode 100644 erts/doc/src/counters.xml (limited to 'erts/doc') diff --git a/erts/doc/src/Makefile b/erts/doc/src/Makefile index 56f8f40069..40f74b78ff 100644 --- a/erts/doc/src/Makefile +++ b/erts/doc/src/Makefile @@ -54,6 +54,7 @@ XML_REF3_EFILES = \ init.xml \ persistent_term.xml \ atomics.xml \ + counters.xml \ zlib.xml XML_REF3_FILES = \ diff --git a/erts/doc/src/counters.xml b/erts/doc/src/counters.xml new file mode 100644 index 0000000000..85eedfdadc --- /dev/null +++ b/erts/doc/src/counters.xml @@ -0,0 +1,142 @@ + + + + +
+ + 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. + + + counters +
+ counters + Counter Functions + +

This module provides a set of functions to do operations towards + shared mutable counter variables. The implementation does not utilize any + software level locking, which makes it very efficient for concurrent + access. The counters are organized into arrays with the follwing + semantics:

+ + +

Counters are 64 bit signed integers.

+ + +

Counters wrap around at overflow and underflow operations.

+ +

Counters are initialized to zero and can then only be written to + by adding or subtracting.

+ + +

Write operations guarantee atomicity. No intermediate results can be + seen from a single write operation.

+ + +

Two types of counter arrays can be created with options atomics or + write_concurrency. The atomics counters have good allround + performance with nice consistent semantics while + write_concurrency counters offers even better concurrent + write performance at the expense of some potential read + inconsistencies. See new/2.

+ + +

Indexes into counter arrays are one-based. A counter array of + size N contains N counters with index from 1 to N.

+ + + + + + + +

Identifies a counter array returned from + new/2.

+ + + + + + + + Create counter array + +

Create a new counter array of Size counters.

+

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

+ + atomics (Default) +

Counters will be sequentially consistent. If write + operation A is done sequencially before write operation B, then a concurrent reader + may see none of them, only A, or both A and B. It cannot see only B.

+ + write_concurrency +

This is an optimization to achieve very efficient concurrent + write operations at the expense of potential read inconsistency and memory + consumption per counter.

+

Read operations may see sequentially inconsistent results with + regard to concurrent write operations. Even if write operation A is done + sequencially before write operation B, a concurrent reader may see any + combination of A and B, including only B. A read operation is only + guaranteed to see all writes done sequentially before the read. No writes + are ever lost, but will eventually all be seen.

+ + + + + + + + Read counter value + +

Read counter value.

+ + + + + + Add to counter + +

Add Incr to counter.

+ + + + + + Subtract from counter + +

Subtract Decr from counter.

+ + + + + + Get information about counter array. + +

Return information about a counter array in a map. The map + has the following keys (at least):

+ + size +

The number of counters in the array.

 + memory +

Approximate memory consumption for the array in + bytes.

 + + + + + + diff --git a/erts/doc/src/ref_man.xml b/erts/doc/src/ref_man.xml index 98f7bbbb8b..a78aaa449e 100644 --- a/erts/doc/src/ref_man.xml +++ b/erts/doc/src/ref_man.xml @@ -51,5 +51,6 @@ + diff --git a/erts/doc/src/specs.xml b/erts/doc/src/specs.xml index 784212dfa0..0b943e6295 100644 --- a/erts/doc/src/specs.xml +++ b/erts/doc/src/specs.xml @@ -7,4 +7,5 @@ + -- cgit v1.2.3