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

AGAIN

* sverker/erts/atomics-counters/OTP-13468:
  erts: Add counters:put/3

1 files changed, 32 insertions, 4 deletions

diff --git a/erts/doc/src/counters.xml b/erts/doc/src/counters.xml
index 85eedfdadc..ba4a22759f 100644
--- a/erts/doc/src/counters.xml
+++ b/erts/doc/src/counters.xml
@@ -85,14 +85,22 @@
 	  </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>
+	  <seealso marker="#add/3"><c>add</c></seealso> and <seealso
+	  marker="#sub/3"><c>sub</c></seealso> 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>
+	  <p>The typical use case for <c>write_concurrency</c> is when
+	  concurrent calls to <seealso marker="#add/3"><c>add</c></seealso> and
+	  <seealso marker="#sub/3"><c>sub</c></seealso> toward the same counters
+	  are very frequent, while calls to <seealso marker="#get/2"><c>get</c>
+	  </seealso> and <seealso marker="#put/3"><c>put</c></seealso> are much
+	  less frequent. The lack of absolute read consistency must also be
+	  acceptable.</p>
 	  </item>
 	</taglist>
       </desc>
@@ -110,7 +118,8 @@
       <name name="add" arity="3"/>
       <fsummary>Add to counter</fsummary>
       <desc>
-        <p>Add <c><anno>Incr</anno></c> to counter.</p>
+        <p>Add <c><anno>Incr</anno></c> to counter at index
+	<c><anno>Ix</anno></c>.</p>
       </desc>
     </func>
 
@@ -118,7 +127,26 @@
       <name name="sub" arity="3"/>
       <fsummary>Subtract from counter</fsummary>
       <desc>
-        <p>Subtract <c><anno>Decr</anno></c> from counter.</p>
+        <p>Subtract <c><anno>Decr</anno></c> from counter at index
+	<c><anno>Ix</anno></c>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name name="put" arity="3"/>
+      <fsummary>Set counter to value</fsummary>
+      <desc>
+        <p>Write <c><anno>Value</anno></c> to counter at index
+	<c><anno>Ix</anno></c>.</p>
+	<note>
+	  <p>Despite its name, the <c>write_concurrency</c> optimization does not
+	  improve <c>put</c>. A call to <c>put</c> is a relative heavy
+	  operation compared to the very lightweight and scalable <seealso
+	  marker="#add/3"><c>add</c></seealso> and <seealso marker="#sub/3">
+	  <c>sub</c></seealso>. The cost for a <c>put</c> with
+	  <c>write_concurrency</c> is lika a <seealso marker="#get/2"><c>get</c>
+	  </seealso> plus a <c>put</c> without <c>write_concurrency</c>.</p>
+	</note>
       </desc>
     </func>