Merge pull request #3047 from TimWSpence/ref-docs

Ref docs
typelevel · Jun 25, 2022 · f949dae · f949dae
2 parents 118d53f + 7daeb8a
commit f949dae
Show file tree

Hide file tree

Showing 2 changed files with 9 additions and 2 deletions.
diff --git a/docs/std/ref.md b/docs/std/ref.md
@@ -18,7 +18,12 @@ Provides safe concurrent access and modification of its content, but no function
 
 For this reason, a `Ref` is always initialised to a value.
 
-The default implementation is nonblocking and lightweight, consisting essentially of a purely functional wrapper over an `AtomicReference`.
+The default implementation is nonblocking and lightweight, consisting
+essentially of a purely functional wrapper over an `AtomicReference`.
+Consequently it _must not_ be used to store mutable data as
+`AtomicReference#compareAndSet` and friends are not threadsafe and are dependent
+upon object reference equality.
+
 
 ### Concurrent Counter
 

diff --git a/kernel/shared/src/main/scala/cats/effect/kernel/Ref.scala b/kernel/shared/src/main/scala/cats/effect/kernel/Ref.scala
@@ -34,7 +34,9 @@ import scala.annotation.tailrec
  * initialised to a value.
  *
  * The default implementation is nonblocking and lightweight, consisting essentially of a purely
- * functional wrapper over an `AtomicReference`.
+ * functional wrapper over an `AtomicReference`. Consequently it ''must not'' be used to store
+ * mutable data as `AtomicReference#compareAndSet` and friends are not threadsafe and are
+ * dependent upon object reference equality.
  */
 abstract class Ref[F[_], A] extends RefSource[F, A] with RefSink[F, A] {