Merge branch 'sverker/erts/atomics-counters/OTP-13468' into maint

* sverker/erts/atomics-counters/OTP-13468:
  erts: Add new module 'counters'
  erts: Add new module 'atomics'

5 files changed, 333 insertions, 7 deletions

diff --git a/erts/doc/src/Makefile b/erts/doc/src/Makefile
index fccdd744f3..40f74b78ff 100644
--- a/erts/doc/src/Makefile
+++ b/erts/doc/src/Makefile
@@ -53,19 +53,16 @@ XML_REF3_EFILES = \
 	erl_tracer.xml \
 	init.xml \
 	persistent_term.xml \
+	atomics.xml \
+	counters.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 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+  <header>
+    <copyright>
+      <year>2018</year>
+      <holder>Ericsson AB. All Rights Reserved.</holder>
+    </copyright>
+    <legalnotice>
+      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.
+    </legalnotice>
+
+    <title>atomics</title>
+  </header>
+  <module>atomics</module>
+  <modulesummary>Atomic Functions</modulesummary>
+  <description>
+    <p>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:</p>
+    <list type="bulleted">
+      <item>
+	<p>Atomics are 64 bit integers.</p>
+      </item>
+      <item>
+	<p>Atomics can be represented as either signed or unsigned.</p>
+      </item>
+      <item>
+	<p>Atomics wrap around at overflow and underflow operations.</p>
+      </item>
+      <item>
+	<p>All operations guarantee atomicity. No intermediate results can be
+	seen. The result of one mutation can only be the input to one
+	following mutation.</p>
+      </item>
+      <item>
+	<p>All atomic operations are mutually ordered. If atomic B is updated
+	<em>after</em> 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.</p>
+      </item>
+      <item>
+	<p>Indexes into atomic arrays are one-based. An atomic array of
+	arity N contains N atomics with index from 1 to N.</p>
+      </item>
+    </list>
+  </description>
+
+  <datatypes>
+    <datatype>
+      <name name="atomics_ref"/>
+      <desc><p>Identifies an atomic array returned from
+        <seealso marker="#new/2"><c>new/2</c></seealso>.</p>
+      </desc>
+    </datatype>
+  </datatypes>
+
+  <funcs>
+    <func>
+      <name name="new" arity="2"/>
+      <fsummary>Create atomic array</fsummary>
+      <desc>
+        <p>Create a new atomic array of <c><anno>Arity</anno></c> atomics.</p>
+	<p>Argument <c><anno>Opts</anno></c> is a list of the following possible
+	options:</p>
+	<taglist>
+	  <tag><c>{signed, boolean()}</c></tag>
+	  <item><p>Indicate if the elements of the array will be treated
+	  as signed or unsigned integers. Default is <c>true</c> (signed).</p>
+	  <p>The integer interval for signed atomics are from <c>-(1 bsl 63)</c>
+	  to <c>(1 bsl 63)-1</c> and for unsigned atomics from <c>0</c> to <c>(1
+	  bsl 64)-1</c>.</p>
+	  </item>
+	</taglist>
+      </desc>
+    </func>
+
+    <func>
+      <name name="put" arity="3"/>
+      <fsummary>Set atomic value</fsummary>
+      <desc>
+        <p>Set atomic to <c><anno>Value</anno></c>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name name="get" arity="2"/>
+      <fsummary>Read atomic value</fsummary>
+      <desc>
+        <p>Read atomic value.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name name="add" arity="3"/>
+      <fsummary>Add to atomic</fsummary>
+      <desc>
+        <p>Add <c><anno>Incr</anno></c> to atomic.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name name="add_get" arity="3"/>
+      <fsummary>Atomic add and get</fsummary>
+      <desc>
+        <p>Atomic addition and return of the result.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name name="sub" arity="3"/>
+      <fsummary>Subtract from atomic</fsummary>
+      <desc>
+        <p>Subtract <c><anno>Decr</anno></c> from atomic.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name name="sub_get" arity="3"/>
+      <fsummary>Atomic sub and get</fsummary>
+      <desc>
+        <p>Atomic subtraction and return of the result.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name name="exchange" arity="3"/>
+      <fsummary>Atomic exchange.</fsummary>
+      <desc>
+        <p>Atomically replaces the value of the atomic with
+	<c><anno>Desired</anno></c> and returns the value it held
+	previously.</p>
+      </desc>
+    </func>
+    
+    <func>
+    <name name="compare_exchange" arity="4"/>
+       <fsummary>Atomic compare and exchange.</fsummary>
+       <desc>
+         <p>Atomically compares the atomic with <c><anno>Expected</anno></c>,
+ 	and if those are equal, set atomic to <c><anno>Desired</anno></c>.
+ 	Returns <c>ok</c> if <c><anno>Desired</anno></c> was written. Returns
+ 	the actual atomic value if not equal to <c><anno>Expected</anno></c>.</p>
+       </desc>
+    </func>
+    
+    <func>
+      <name name="info" arity="1"/>
+      <fsummary>Get information about atomic array.</fsummary>
+      <desc>
+        <p>Return information about an atomic array in a map. The map
+	has the following keys:</p>
+	<taglist>
+	  <tag><c>size</c></tag>
+	  <item><p>The number of atomics in the array.</p></item>
+	  <tag><c>max</c></tag>
+	  <item><p>The highest possible value an atomic in this array can
+	  hold.</p></item>
+	  <tag><c>min</c></tag>
+	  <item><p>The lowest possible value an atomic in this array can
+	  hold.</p></item>
+	  <tag><c>memory</c></tag>
+	  <item><p>Approximate memory consumption for the array in
+	  bytes.</p></item>
+	</taglist>
+      </desc>
+    </func>
+
+ </funcs>
+</erlref>
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 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+  <header>
+    <copyright>
+      <year>2018</year>
+      <holder>Ericsson AB. All Rights Reserved.</holder>
+    </copyright>
+    <legalnotice>
+      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.
+    </legalnotice>
+
+    <title>counters</title>
+  </header>
+  <module>counters</module>
+  <modulesummary>Counter Functions</modulesummary>
+  <description>
+    <p>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:</p>
+    <list type="bulleted">
+      <item>
+	<p>Counters are 64 bit signed integers.</p>
+      </item>
+      <item>
+	<p>Counters wrap around at overflow and underflow operations.</p>
+      </item>
+      <item><p>Counters are initialized to zero and can then only be written to
+        by adding or subtracting.</p>
+      </item>
+      <item>
+	<p>Write operations guarantee atomicity. No intermediate results can be
+	seen from a single write operation.</p>
+      </item>
+      <item>
+	<p>Two types of counter arrays can be created with options <c>atomics</c> or
+	<c>write_concurrency</c>. The <c>atomics</c> counters have good allround
+	performance with nice consistent semantics while
+	<c>write_concurrency</c> counters offers even better concurrent
+	write performance at the expense of some potential read
+	inconsistencies. See <seealso marker="#new/2"><c>new/2</c></seealso>.</p>
+      </item>
+      <item>
+	<p>Indexes into counter arrays are one-based. A counter array of
+	size N contains N counters with index from 1 to N.</p>
+      </item>
+    </list>
+  </description>
+
+  <datatypes>
+    <datatype>
+      <name name="counters_ref"/>
+      <desc><p>Identifies a counter array returned from
+        <seealso marker="#new/2"><c>new/2</c></seealso>.</p>
+      </desc>
+    </datatype>
+  </datatypes>
+
+  <funcs>
+    <func>
+      <name name="new" arity="2"/>
+      <fsummary>Create counter array</fsummary>
+      <desc>
+        <p>Create a new counter array of <c><anno>Size</anno></c> counters.</p>
+	<p>Argument <c><anno>Opts</anno></c> is a list of the following possible
+	options:</p>
+	<taglist>
+	  <tag><c>atomics</c> (Default)</tag>
+	  <item><p>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.</p>
+	  </item>
+	  <tag><c>write_concurrency</c></tag>
+	  <item><p>This is an optimization to achieve very efficient concurrent
+	  write operations at the expense of potential read inconsistency and memory
+	  consumption per counter.</p>
+	  <p>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.</p>
+	  </item>
+	</taglist>
+      </desc>
+    </func>
+
+    <func>
+      <name name="get" arity="2"/>
+      <fsummary>Read counter value</fsummary>
+      <desc>
+        <p>Read counter value.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name name="add" arity="3"/>
+      <fsummary>Add to counter</fsummary>
+      <desc>
+        <p>Add <c><anno>Incr</anno></c> to counter.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name name="sub" arity="3"/>
+      <fsummary>Subtract from counter</fsummary>
+      <desc>
+        <p>Subtract <c><anno>Decr</anno></c> from counter.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name name="info" arity="1"/>
+      <fsummary>Get information about counter array.</fsummary>
+      <desc>
+        <p>Return information about a counter array in a map. The map
+	has the following keys (at least):</p>
+	<taglist>
+	  <tag><c>size</c></tag>
+	  <item><p>The number of counters in the array.</p></item>
+	  <tag><c>memory</c></tag>
+	  <item><p>Approximate memory consumption for the array in
+	  bytes.</p></item>
+	</taglist>
+      </desc>
+    </func>
+
+ </funcs>
+</erlref>
diff --git a/erts/doc/src/ref_man.xml b/erts/doc/src/ref_man.xml
index ff64aa86b8..a78aaa449e 100644
--- a/erts/doc/src/ref_man.xml
+++ b/erts/doc/src/ref_man.xml
@@ -50,5 +50,7 @@
   <xi:include href="erts_alloc.xml"/>
   <xi:include href="erl_nif.xml"/>
   <xi:include href="erl_tracer.xml"/>
+  <xi:include href="atomics.xml"/>
+  <xi:include href="counters.xml"/>
 </application>
 
diff --git a/erts/doc/src/specs.xml b/erts/doc/src/specs.xml
index 1ab6cdc19e..0b943e6295 100644
--- a/erts/doc/src/specs.xml
+++ b/erts/doc/src/specs.xml
@@ -6,4 +6,6 @@
   <xi:include href="../specs/specs_init.xml"/>
   <xi:include href="../specs/specs_persistent_term.xml"/>
   <xi:include href="../specs/specs_zlib.xml"/>
+  <xi:include href="../specs/specs_atomics.xml"/>
+  <xi:include href="../specs/specs_counters.xml"/>
 </specs>