aboutsummaryrefslogtreecommitdiffstats
path: root/erts/doc
diff options
context:
space:
mode:
authorSverker Eriksson <[email protected]>2018-11-22 15:52:13 +0100
committerSverker Eriksson <[email protected]>2018-11-22 15:52:13 +0100
commitfb8018f9ebebbcb5ef074e33514a4c03aaefbe2d (patch)
tree01dc57e92e043916c611cf9c814fe9102cc9a81f /erts/doc
parente0cfc10e85515823cdd8343919dfaeb1884dc0a4 (diff)
parentf504781a136b1992a1cee26a7da841892d796d91 (diff)
downloadotp-fb8018f9ebebbcb5ef074e33514a4c03aaefbe2d.tar.gz
otp-fb8018f9ebebbcb5ef074e33514a4c03aaefbe2d.tar.bz2
otp-fb8018f9ebebbcb5ef074e33514a4c03aaefbe2d.zip
Merge branch 'sverker/erts/atomics-counters/OTP-13468' into maint
AGAIN * sverker/erts/atomics-counters/OTP-13468: erts: Add counters:put/3
Diffstat (limited to 'erts/doc')
-rw-r--r--erts/doc/src/counters.xml36
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>