Merge pull request #739 from kubum/add-tryRead-mvar

MVar: add "tryRead" fixes #732

build.sbt

@@ -29,6 +29,7 @@ val CompileTime = config("CompileTime").hide
 val SimulacrumVersion = "1.0.0"
 val CatsVersion = "2.1.1"
 val DisciplineScalatestVersion = "1.0.1"
+val SilencerVersion = "1.6.0"
 val customScalaJSVersion = Option(System.getenv("SCALAJS_VERSION"))
 
 addCommandAlias("ci", ";scalafmtSbtCheck ;scalafmtCheckAll ;test ;mimaReportBinaryIssues; doc")
@@ -239,6 +240,11 @@ lazy val core = crossProject(JSPlatform, JVMPlatform)
       "org.typelevel" %%% "cats-laws" % CatsVersion % Test,
       "org.typelevel" %%% "discipline-scalatest" % DisciplineScalatestVersion % Test
     ),
+    libraryDependencies ++= Seq(
+      compilerPlugin(("com.github.ghik" % "silencer-plugin" % SilencerVersion).cross(CrossVersion.full)),
+      ("com.github.ghik" % "silencer-lib" % SilencerVersion % CompileTime).cross(CrossVersion.full),
+      ("com.github.ghik" % "silencer-lib" % SilencerVersion % Test).cross(CrossVersion.full)
+    ),
     libraryDependencies ++= {
       CrossVersion.partialVersion(scalaVersion.value) match {
         case Some((2, v)) if v <= 12 =>
@@ -330,9 +336,6 @@ lazy val siteSettings = Seq(
       Map("permalink" -> "/", "title" -> "Home", "section" -> "home", "position" -> "0")
     )
   ),
-  micrositeConfigYaml := ConfigYml(
-    yamlCustomProperties = Map("plugins" -> List("jekyll-relative-links"))
-  ),
   micrositeCompilingDocsTool := WithMdoc,
   mdocIn := (sourceDirectory in Compile).value / "mdoc",
   fork in mdoc := true,

core/shared/src/main/scala/cats/effect/concurrent/MVar.scala

@@ -17,13 +17,13 @@
 package cats.effect
 package concurrent
 
-import cats.effect.concurrent.MVar.TransformedMVar
+import cats.effect.concurrent.MVar.{TransformedMVar, TransformedMVar2}
 import cats.effect.internals.{MVarAsync, MVarConcurrent}
 import cats.~>
+import com.github.ghik.silencer.silent
 
 /**
- * A mutable location, that is either empty or contains
- * a value of type `A`.
+ * @define mVarDescription A mutable location, that is either empty or contains a value of type `A`.
  *
  * It has the following fundamental atomic operations:
  *
@@ -37,6 +37,8 @@ import cats.~>
  *  - [[read]] which reads the current value without touching it,
  *    assuming there is one, or otherwise it waits until a value
  *    is made available via `put`
+ *  - `tryRead` returns a variable if it exists. Implemented in the successor [[MVar2]]
+ *  - `swap` takes a value, replaces it and returns the taken value. Implemented in the successor [[MVar2]]
  *  - [[isEmpty]] returns true if currently empty
  *
  * The `MVar` is appropriate for building synchronization
@@ -52,7 +54,13 @@ import cats.~>
  * Inspired by `Control.Concurrent.MVar` from Haskell and
  * by `scalaz.concurrent.MVar`.
  */
-abstract class MVar[F[_], A] {
+sealed private[concurrent] trait MVarDocumentation extends Any {}
+
+/**
+ * $mVarDescription
+ */
+@deprecated("`MVar` is now deprecated in favour of a new generation `MVar2` with `tryRead` and `swap` support", "2.2.0")
+abstract class MVar[F[_], A] extends MVarDocumentation {
 
   /**
    * Returns `true` if the `MVar` is empty and can receive a `put`, or
@@ -120,6 +128,39 @@ abstract class MVar[F[_], A] {
     new TransformedMVar(this, f)
 }
 
+/**
+ * $mVarDescription
+ *
+ * The `MVar2` is the successor of `MVar` with [[tryRead]] and [[swap]]. It was implemented separately only to maintain
+ * binary compatibility with `MVar`.
+ */
+@silent("deprecated")
+abstract class MVar2[F[_], A] extends MVar[F, A] {
+
+  /**
+   * Replaces a value in MVar and returns the old value.
+
+   * @param newValue is a new value
+   * @return the value taken
+   */
+  def swap(newValue: A): F[A]
+
+  /**
+   * Returns the value without waiting or modifying.
+   *
+   * This operation is atomic.
+   *
+   * @return an Option holding the current value, None means it was empty
+   */
+  def tryRead: F[Option[A]]
+
+  /**
+   * Modify the context `F` using transformation `f`.
+   */
+  override def mapK[G[_]](f: F ~> G): MVar2[G, A] =
+    new TransformedMVar2(this, f)
+}
+
 /** Builders for [[MVar]]. */
 object MVar {
 
@@ -156,7 +197,7 @@ object MVar {
    * @param F is a [[Concurrent]] constraint, needed in order to
    *        describe cancelable operations
    */
-  def empty[F[_], A](implicit F: Concurrent[F]): F[MVar[F, A]] =
+  def empty[F[_], A](implicit F: Concurrent[F]): F[MVar2[F, A]] =
     F.delay(MVarConcurrent.empty)
 
   /**
@@ -172,7 +213,7 @@ object MVar {
    *
    * @see [[empty]] for creating cancelable MVars
    */
-  def uncancelableEmpty[F[_], A](implicit F: Async[F]): F[MVar[F, A]] =
+  def uncancelableEmpty[F[_], A](implicit F: Async[F]): F[MVar2[F, A]] =
     F.delay(MVarAsync.empty)
 
   /**
@@ -187,7 +228,7 @@ object MVar {
    * @param F is a [[Concurrent]] constraint, needed in order to
    *        describe cancelable operations
    */
-  def of[F[_], A](initial: A)(implicit F: Concurrent[F]): F[MVar[F, A]] =
+  def of[F[_], A](initial: A)(implicit F: Concurrent[F]): F[MVar2[F, A]] =
     F.delay(MVarConcurrent(initial))
 
   /**
@@ -204,31 +245,31 @@ object MVar {
    *
    * @see [[of]] for creating cancelable MVars
    */
-  def uncancelableOf[F[_], A](initial: A)(implicit F: Async[F]): F[MVar[F, A]] =
+  def uncancelableOf[F[_], A](initial: A)(implicit F: Async[F]): F[MVar2[F, A]] =
     F.delay(MVarAsync(initial))
 
   /**
    * Like [[of]] but initializes state using another effect constructor
    */
-  def in[F[_], G[_], A](initial: A)(implicit F: Sync[F], G: Concurrent[G]): F[MVar[G, A]] =
+  def in[F[_], G[_], A](initial: A)(implicit F: Sync[F], G: Concurrent[G]): F[MVar2[G, A]] =
     F.delay(MVarConcurrent(initial))
 
   /**
    * Like [[empty]] but initializes state using another effect constructor
    */
-  def emptyIn[F[_], G[_], A](implicit F: Sync[F], G: Concurrent[G]): F[MVar[G, A]] =
+  def emptyIn[F[_], G[_], A](implicit F: Sync[F], G: Concurrent[G]): F[MVar2[G, A]] =
     F.delay(MVarConcurrent.empty)
 
   /**
    * Like [[uncancelableOf]] but initializes state using another effect constructor
    */
-  def uncancelableIn[F[_], G[_], A](initial: A)(implicit F: Sync[F], G: Async[G]): F[MVar[G, A]] =
+  def uncancelableIn[F[_], G[_], A](initial: A)(implicit F: Sync[F], G: Async[G]): F[MVar2[G, A]] =
     F.delay(MVarAsync(initial))
 
   /**
    * Like [[uncancelableEmpty]] but initializes state using another effect constructor
    */
-  def uncancelableEmptyIn[F[_], G[_], A](implicit F: Sync[F], G: Async[G]): F[MVar[G, A]] =
+  def uncancelableEmptyIn[F[_], G[_], A](implicit F: Sync[F], G: Async[G]): F[MVar2[G, A]] =
     F.delay(MVarAsync.empty)
 
   /**
@@ -241,15 +282,15 @@ object MVar {
      *
      * @see documentation for [[MVar.of]]
      */
-    def of[A](a: A): F[MVar[F, A]] =
+    def of[A](a: A): F[MVar2[F, A]] =
       MVar.of(a)(F)
 
     /**
      * Builds an empty `MVar`.
      *
      * @see documentation for [[MVar.empty]]
      */
-    def empty[A]: F[MVar[F, A]] =
+    def empty[A]: F[MVar2[F, A]] =
       MVar.empty(F)
   }
 
@@ -262,4 +303,16 @@ object MVar {
     override def tryTake: G[Option[A]] = trans(underlying.tryTake)
     override def read: G[A] = trans(underlying.read)
   }
+
+  final private[concurrent] class TransformedMVar2[F[_], G[_], A](underlying: MVar2[F, A], trans: F ~> G)
+      extends MVar2[G, A] {
+    override def isEmpty: G[Boolean] = trans(underlying.isEmpty)
+    override def put(a: A): G[Unit] = trans(underlying.put(a))
+    override def tryPut(a: A): G[Boolean] = trans(underlying.tryPut(a))
+    override def take: G[A] = trans(underlying.take)
+    override def tryTake: G[Option[A]] = trans(underlying.tryTake)
+    override def read: G[A] = trans(underlying.read)
+    override def tryRead: G[Option[A]] = trans(underlying.tryRead)
+    override def swap(newValue: A): G[A] = trans(underlying.swap(newValue))
+  }
 }

core/shared/src/main/scala/cats/effect/internals/MVarAsync.scala

@@ -18,16 +18,18 @@ package cats.effect
 package internals
 
 import java.util.concurrent.atomic.AtomicReference
-import cats.effect.concurrent.MVar
+
+import cats.effect.concurrent.MVar2
 import cats.effect.internals.Callback.rightUnit
+
 import scala.annotation.tailrec
 import scala.collection.immutable.Queue
 
 /**
  * [[MVar]] implementation for [[Async]] data types.
  */
 final private[effect] class MVarAsync[F[_], A] private (initial: MVarAsync.State[A])(implicit F: Async[F])
-    extends MVar[F, A] {
+    extends MVar2[F, A] {
   import MVarAsync._
 
   /** Shared mutable state. */
@@ -55,6 +57,18 @@ final private[effect] class MVarAsync[F[_], A] private (initial: MVarAsync.State
   def read: F[A] =
     F.async(unsafeRead)
 
+  def tryRead: F[Option[A]] = F.delay {
+    stateRef.get match {
+      case WaitForTake(value, _) => Some(value)
+      case WaitForPut(_, _)      => None
+    }
+  }
+
+  def swap(newValue: A): F[A] =
+    F.flatMap(take) { oldValue =>
+      F.map(put(newValue))(_ => oldValue)
+    }
+
   def isEmpty: F[Boolean] =
     F.delay {
       stateRef.get match {
@@ -226,11 +240,11 @@ final private[effect] class MVarAsync[F[_], A] private (initial: MVarAsync.State
 private[effect] object MVarAsync {
 
   /** Builds an [[MVarAsync]] instance with an `initial` value. */
-  def apply[F[_], A](initial: A)(implicit F: Async[F]): MVar[F, A] =
+  def apply[F[_], A](initial: A)(implicit F: Async[F]): MVar2[F, A] =
     new MVarAsync[F, A](State(initial))
 
   /** Returns an empty [[MVarAsync]] instance. */
-  def empty[F[_], A](implicit F: Async[F]): MVar[F, A] =
+  def empty[F[_], A](implicit F: Async[F]): MVar2[F, A] =
     new MVarAsync[F, A](State.empty)
 
   /**

core/shared/src/main/scala/cats/effect/internals/MVarConcurrent.scala

@@ -18,16 +18,18 @@ package cats.effect
 package internals
 
 import java.util.concurrent.atomic.AtomicReference
-import cats.effect.concurrent.MVar
+
+import cats.effect.concurrent.MVar2
 import cats.effect.internals.Callback.rightUnit
+
 import scala.annotation.tailrec
 
 /**
  * [[MVar]] implementation for [[Concurrent]] data types.
  */
 final private[effect] class MVarConcurrent[F[_], A] private (initial: MVarConcurrent.State[A])(
   implicit F: Concurrent[F]
-) extends MVar[F, A] {
+) extends MVar2[F, A] {
   import MVarConcurrent._
 
   /** Shared mutable state. */
@@ -58,6 +60,14 @@ final private[effect] class MVarConcurrent[F[_], A] private (initial: MVarConcur
   val read: F[A] =
     F.cancelable(unsafeRead)
 
+  def tryRead =
+    F.delay {
+      stateRef.get match {
+        case WaitForTake(value, _) => Some(value)
+        case WaitForPut(_, _)      => None
+      }
+    }
+
   def isEmpty: F[Boolean] =
     F.delay {
       stateRef.get match {
@@ -66,6 +76,11 @@ final private[effect] class MVarConcurrent[F[_], A] private (initial: MVarConcur
       }
     }
 
+  def swap(newValue: A): F[A] =
+    F.flatMap(take) { oldValue =>
+      F.map(put(newValue))(_ => oldValue)
+    }
+
   @tailrec private def unsafeTryPut(a: A): F[Boolean] =
     stateRef.get match {
       case WaitForTake(_, _) => F.pure(false)
@@ -280,11 +295,11 @@ final private[effect] class MVarConcurrent[F[_], A] private (initial: MVarConcur
 private[effect] object MVarConcurrent {
 
   /** Builds an [[MVarConcurrent]] instance with an `initial` value. */
-  def apply[F[_], A](initial: A)(implicit F: Concurrent[F]): MVar[F, A] =
+  def apply[F[_], A](initial: A)(implicit F: Concurrent[F]): MVar2[F, A] =
     new MVarConcurrent[F, A](State(initial))
 
   /** Returns an empty [[MVarConcurrent]] instance. */
-  def empty[F[_], A](implicit F: Concurrent[F]): MVar[F, A] =
+  def empty[F[_], A](implicit F: Concurrent[F]): MVar2[F, A] =
     new MVarConcurrent[F, A](State.empty)
 
   /**