From c3358851de1399de1041c76927e294210dafafce Mon Sep 17 00:00:00 2001
From: Elizabeth Mattijsen <liz@wenzperl.nl>
Date: Wed, 28 Feb 2018 16:34:58 +0100
Subject: [PATCH] Add some more guidance in comments for atomics

---
 src/core/atomicops.pm | 26 ++++++++++++--------------
 1 file changed, 12 insertions(+), 14 deletions(-)

diff --git a/src/core/atomicops.pm b/src/core/atomicops.pm
index 2060bb317eb..55fe739a457 100644
--- a/src/core/atomicops.pm
+++ b/src/core/atomicops.pm
@@ -37,7 +37,7 @@ multi sub cas($target is rw, &code) {
 #?if moar
 my native atomicint is repr('P6int') is Int is ctype('atomic') { }
 
-#-- fetching a value atomically
+#-- fetching a native integer value atomically
 multi sub atomic-fetch(atomicint $source is rw) {
     nqp::atomicload_i($source)
 }
@@ -46,7 +46,7 @@ multi sub prefix:<⚛>(atomicint $source is rw) {
     nqp::atomicload_i($source)
 }
 
-#-- assigning a value atomically
+#-- assigning a native integer value atomically
 multi sub atomic-assign(atomicint $target is rw, int $value) {
     nqp::atomicstore_i($target, $value)
 }
@@ -71,7 +71,7 @@ multi sub infix:<⚛=>(atomicint $target is rw, $value) {
     nqp::atomicstore_i($target, $value.Int)
 }
 
-#-- atomically fetch value and increment it
+#-- atomically fetch native integer value and increment it
 sub atomic-fetch-inc(atomicint $target is rw --> atomicint) {
     nqp::atomicinc_i($target)
 }
@@ -80,15 +80,16 @@ sub postfix:<⚛++>(atomicint $target is rw --> atomicint) {
     nqp::atomicinc_i($target)
 }
 
-#-- atomically increment value and fetch it
+#-- atomically increment native integer value and fetch it
 sub atomic-inc-fetch(atomicint $target is rw --> atomicint) {
     my atomicint $ = nqp::atomicinc_i($target) + 1
 }
+
 sub prefix:<++⚛>(atomicint $target is rw --> atomicint) {
     my atomicint $ = nqp::atomicinc_i($target) + 1
 }
 
-#-- atomically fetch value and decrement it
+#-- atomically fetch native integer value and decrement it
 sub atomic-fetch-dec(atomicint $target is rw --> atomicint) {
     nqp::atomicdec_i($target)
 }
@@ -97,7 +98,7 @@ sub postfix:<⚛-->(atomicint $target is rw --> atomicint) {
     nqp::atomicdec_i($target)
 }
 
-#-- atomically decrement value and fetch it
+#-- atomically decrement native integer value and fetch it
 sub atomic-dec-fetch(atomicint $target is rw --> atomicint) {
     my atomicint $ = nqp::atomicdec_i($target) - 1
 }
@@ -105,7 +106,7 @@ sub prefix:<--⚛>(atomicint $target is rw --> atomicint) {
     my atomicint $ = nqp::atomicdec_i($target) - 1
 }
 
-#-- atomically fetch value and then add given value to it
+#-- atomically fetch native integer value and then add given value to it
 proto sub atomic-fetch-add($, $) {*}
 multi sub atomic-fetch-add(atomicint $target is rw, int $add --> atomicint) {
     nqp::atomicadd_i($target, $add)
@@ -117,7 +118,7 @@ multi sub atomic-fetch-add(atomicint $target is rw, $add --> atomicint) {
     nqp::atomicadd_i($target, $add.Int)
 }
 
-#-- atomically add given value to value and return that
+#-- atomically add given native integer value to value and return that
 proto sub atomic-add-fetch($, $) {*}
 multi sub atomic-add-fetch(atomicint $target is rw, int $add --> atomicint) {
     my atomicint $ = nqp::atomicadd_i($target, $add) + $add
@@ -142,7 +143,7 @@ multi sub infix:<⚛+=>(atomicint $target is rw, $add --> atomicint) {
     my atomicint $ = nqp::atomicadd_i($target, $add-int) + $add-int
 }
 
-#-- atomically fetch value and then subtract given value from it
+#-- atomically fetch native integer value and then subtract given value from it
 proto sub atomic-fetch-sub($, $) {*}
 multi sub atomic-fetch-sub(atomicint $target is rw, int $add --> atomicint) {
     nqp::atomicadd_i($target, nqp::neg_i($add))
@@ -154,7 +155,7 @@ multi sub atomic-fetch-sub(atomicint $target is rw, $add --> atomicint) {
     nqp::atomicadd_i($target, nqp::neg_i($add.Int))
 }
 
-#-- atomically subtract given value from value and return that
+#-- atomically subtract given native integer value from value and return that
 proto sub atomic-sub-fetch($, $) {*}
 multi sub atomic-sub-fetch(atomicint $target is rw, int $add --> atomicint) {
     my atomicint $ = nqp::atomicadd_i($target, nqp::neg_i($add)) - $add
@@ -185,19 +186,16 @@ sub full-barrier(--> Nil) {
     nqp::barrierfull()
 }
 
-#-- atomic compare and swap
+#-- atomic compare and swap a native integer
 multi sub cas(atomicint $target is rw, int $expected, int $value) {
     nqp::cas_i($target, $expected, $value)
 }
-
 multi sub cas(atomicint $target is rw, Int:D $expected, Int:D $value) {
     nqp::cas_i($target, $expected, $value)
 }
-
 multi sub cas(atomicint $target is rw, $expected, $value) {
     nqp::cas_i($target, $expected.Int, $value.Int)
 }
-
 multi sub cas(atomicint $target is rw, &code) {
     my int $current = nqp::atomicload_i($target);
     loop {