Diff: platform/mbed_critical.h

Revision:

180:96ed750bd169

Parent:

178:79309dc6340a

diff -r b0033dcd6934 -r 96ed750bd169 platform/mbed_critical.h
--- a/platform/mbed_critical.h	Thu Dec 07 14:01:42 2017 +0000
+++ b/platform/mbed_critical.h	Wed Jan 17 15:23:54 2018 +0000
@@ -121,7 +121,7 @@
  * }
  *
  * @note: In the failure case (where the destination isn't set), the value
- * pointed to by expectedCurrentValue is still updated with the current value.
+ * pointed to by expectedCurrentValue is instead updated with the current value.
  * This property helps writing concise code for the following incr:
  *
  * function incr(p : pointer to int, a : int) returns int {
@@ -132,6 +132,10 @@
  *     }
  *     return value + a
  * }
+ *
+ * @note: This corresponds to the C11 "atomic_compare_exchange_strong" - it
+ * always succeeds if the current value is expected, as per the pseudocode
+ * above; it will not spuriously fail as "atomic_compare_exchange_weak" may.
  */
 bool core_util_atomic_cas_u8(uint8_t *ptr, uint8_t *expectedCurrentValue, uint8_t desiredValue);
 
@@ -174,7 +178,7 @@
  * }
  *
  * @note: In the failure case (where the destination isn't set), the value
- * pointed to by expectedCurrentValue is still updated with the current value.
+ * pointed to by expectedCurrentValue is instead updated with the current value.
  * This property helps writing concise code for the following incr:
  *
  * function incr(p : pointer to int, a : int) returns int {
@@ -185,6 +189,10 @@
  *     }
  *     return value + a
  * }
+ *
+ * @note: This corresponds to the C11 "atomic_compare_exchange_strong" - it
+ * always succeeds if the current value is expected, as per the pseudocode
+ * above; it will not spuriously fail as "atomic_compare_exchange_weak" may.
  */
 bool core_util_atomic_cas_u16(uint16_t *ptr, uint16_t *expectedCurrentValue, uint16_t desiredValue);
 
@@ -227,7 +235,7 @@
  * }
  *
  * @note: In the failure case (where the destination isn't set), the value
- * pointed to by expectedCurrentValue is still updated with the current value.
+ * pointed to by expectedCurrentValue is instead updated with the current value.
  * This property helps writing concise code for the following incr:
  *
  * function incr(p : pointer to int, a : int) returns int {
@@ -237,6 +245,10 @@
  *         done = atomic_cas(p, &value, value + a) // *value gets updated automatically until success
  *     }
  *     return value + a
+ *
+ * @note: This corresponds to the C11 "atomic_compare_exchange_strong" - it
+ * always succeeds if the current value is expected, as per the pseudocode
+ * above; it will not spuriously fail as "atomic_compare_exchange_weak" may.
  * }
  */
 bool core_util_atomic_cas_u32(uint32_t *ptr, uint32_t *expectedCurrentValue, uint32_t desiredValue);
@@ -280,7 +292,7 @@
  * }
  *
  * @note: In the failure case (where the destination isn't set), the value
- * pointed to by expectedCurrentValue is still updated with the current value.
+ * pointed to by expectedCurrentValue is instead updated with the current value.
  * This property helps writing concise code for the following incr:
  *
  * function incr(p : pointer to int, a : int) returns int {
@@ -291,6 +303,10 @@
  *     }
  *     return value + a
  * }
+ *
+ * @note: This corresponds to the C11 "atomic_compare_exchange_strong" - it
+ * always succeeds if the current value is expected, as per the pseudocode
+ * above; it will not spuriously fail as "atomic_compare_exchange_weak" may.
  */
 bool core_util_atomic_cas_ptr(void **ptr, void **expectedCurrentValue, void *desiredValue);