Add AsyncCallback.ref

Closes #817

Author: japgolly

core/src/main/scala/japgolly/scalajs/react/AsyncCallback.scala

@@ -447,6 +447,92 @@ object AsyncCallback {
   /** Creates a new (non-reentrant) read/write mutex. */
   def readWriteMutex: CallbackTo[ReadWriteMutex] =
     CallbackTo(new ReadWriteMutex)
+
+  // ===================================================================================================================
+
+  final class Ref[A] private[AsyncCallback](atomicReads: Boolean, atomicWrites: Boolean) {
+
+    private val mutex       = readWriteMutex.runNow()
+    private val initialised = barrier.runNow()
+    private var _value: A   = _
+
+    private val markInitialised =
+      initialised.complete.asAsyncCallback
+
+    /** If this hasn't been set yet, it will block until it is set. */
+    val get: AsyncCallback[A] = {
+      var readValue: AsyncCallback[A] =
+        AsyncCallback.delay(_value)
+
+      if (atomicReads)
+        readValue = mutex.read(readValue)
+
+      initialised.await >> readValue
+    }
+
+    /** Synchronously return whatever value is currently stored. (Ignores atomicity). */
+    lazy val getIfAvailable: CallbackTo[Option[A]] =
+      initialised.isComplete.map {
+        case true  => Some(_value)
+        case false => None
+      }
+
+    private def inWriteMutex[B](a: AsyncCallback[B]): AsyncCallback[B] =
+      if (atomicWrites)
+        mutex.write(a)
+      else
+        a
+
+    // This must only be called within the write mutex
+    private def setWithinMutex(c: AsyncCallback[A]): AsyncCallback[Unit] =
+      for {
+        a <- c
+        _ <- AsyncCallback.delay { _value = a }
+        _ <- markInitialised
+      } yield ()
+
+    def set(a: => A): AsyncCallback[Unit] =
+      setAsync(AsyncCallback.delay(a))
+
+    def setSync(c: CallbackTo[A]): AsyncCallback[Unit] =
+      setAsync(c.asAsyncCallback)
+
+    def setAsync(c: AsyncCallback[A]): AsyncCallback[Unit] =
+      inWriteMutex(setWithinMutex(c))
+
+    /** Returns whether or not the value was set. */
+    def setIfUnset(a: => A): AsyncCallback[Boolean] =
+      setIfUnsetAsync(AsyncCallback.delay(a))
+
+    /** Returns whether or not the value was set. */
+    def setIfUnsetSync(c: CallbackTo[A]): AsyncCallback[Boolean] =
+      setIfUnsetAsync(c.asAsyncCallback)
+
+    /** Returns whether or not the value was set. */
+    def setIfUnsetAsync(c: AsyncCallback[A]): AsyncCallback[Boolean] =
+      initialised.isComplete.asAsyncCallback.flatMap {
+        case true => AsyncCallback.pure(false)
+        case false =>
+          inWriteMutex {
+            AsyncCallback.byName {
+              if (initialised.isComplete.runNow())
+                AsyncCallback.pure(false)
+              else
+                setWithinMutex(c).ret(true)
+            }
+          }
+      }
+  }
+
+  @inline def ref[A]: CallbackTo[Ref[A]] =
+    ref()
+
+  def ref[A](allowStaleReads: Boolean = false,
+             atomicWrites   : Boolean = true): CallbackTo[Ref[A]] =
+    CallbackTo(new Ref(
+      atomicReads   = atomicWrites && !allowStaleReads,
+      atomicWrites  = atomicWrites,
+    ))
 }
 
 // █████████████████████████████████████████████████████████████████████████████████████████████████████████████████████

doc/changelog/1.7.7.md

@@ -69,6 +69,24 @@ This entire release is focused on `AsyncCallback`.
     }
     ```
 
+  * Added `ref[A](allowStaleReads = false, atomicWrites = true)` which returns a `AsyncCallback.Ref`.
+    A ref is effectively a "wrapper" for mutable variable. By default, setters and getters are atomic.
+
+    ```scala
+    AsyncCallback.Ref[A] {
+      val get           : AsyncCallback[A]
+      val getIfAvailable: CallbackTo[Option[A]]
+
+      def set     (a: => A)            : AsyncCallback[Unit]
+      def setSync (c: CallbackTo[A])   : AsyncCallback[Unit]
+      def setAsync(c: AsyncCallback[A]): AsyncCallback[Unit]
+
+      def setIfUnset     (a: => A)            : AsyncCallback[Boolean]
+      def setIfUnsetSync (c: CallbackTo[A])   : AsyncCallback[Boolean]
+      def setIfUnsetAsync(c: AsyncCallback[A]): AsyncCallback[Boolean]
+    }
+    ```
+
   * You can now add a `_` suffix to the following to return an `AsyncCallback[Unit]` and be more efficient under-the-hood:
 
     * `traverse`

test/src/test/scala/japgolly/scalajs/react/core/AsyncCallbackTest.scala

@@ -281,5 +281,21 @@ object AsyncCallbackTest extends TestSuite {
       } yield ()
     }
 
+    "ref" - asyncTest {
+      for {
+        ref <- AsyncCallback.ref[Int].asAsyncCallback
+        g1  <- ref.get.fork.asAsyncCallback
+        _   <- ref.getIfAvailable.asAsyncCallback.tap(assertEq(_, None))
+        _   <- ref.setIfUnset(123)
+        _   <- ref.getIfAvailable.asAsyncCallback.tap(assertEq(_, Some(123)))
+        _   <- ref.setIfUnset(456)
+        _   <- ref.getIfAvailable.asAsyncCallback.tap(assertEq(_, Some(123)))
+        _   <- g1.await.tap(assertEq(_, 123))
+        _   <- ref.set(987)
+        _   <- ref.getIfAvailable.asAsyncCallback.tap(assertEq(_, Some(987)))
+        _   <- ref.get.tap(assertEq(_, 987))
+      } yield ()
+    }
+
   }
 }