Rename suspend to defer in cats-free (#1709)

I chose `defer` over `suspend` because both `Free` and `FreeT` have a `Suspend` which is used by `liftF` (not by `suspend`), so this may reduce that confusion as well.
typelevel · May 30, 2017 · 4e55158 · 4e55158
1 parent b722f2b
commit 4e55158
Show file tree

Hide file tree

Showing 5 changed files with 23 additions and 8 deletions.
diff --git a/bench/src/main/scala/cats/bench/TrampolineBench.scala b/bench/src/main/scala/cats/bench/TrampolineBench.scala
@@ -26,8 +26,8 @@ class TrampolineBench {
 
   def trampolineFib(n: Int): Trampoline[Int] =
     if (n < 2) Trampoline.done(n) else for {
-      x <- Trampoline.suspend(trampolineFib(n - 1))
-      y <- Trampoline.suspend(trampolineFib(n - 2))
+      x <- Trampoline.defer(trampolineFib(n - 1))
+      y <- Trampoline.defer(trampolineFib(n - 2))
     } yield x + y
 
   // TailRec[A] only has .flatMap in 2.11.

diff --git a/free/src/main/scala/cats/free/Free.scala b/free/src/main/scala/cats/free/Free.scala
@@ -193,7 +193,14 @@ object Free {
   /**
    * Suspend the creation of a `Free[F, A]` value.
    */
+  @deprecated("Use Free.defer.", "1.0.0-MF")
   def suspend[F[_], A](value: => Free[F, A]): Free[F, A] =
+    defer(value)
+
+  /**
+   * Defer the creation of a `Free[F, A]` value.
+   */
+  def defer[F[_], A](value: => Free[F, A]): Free[F, A] =
     pure(()).flatMap(_ => value)
 
   /**

diff --git a/free/src/main/scala/cats/free/FreeT.scala b/free/src/main/scala/cats/free/FreeT.scala
@@ -149,7 +149,11 @@ object FreeT extends FreeTInstances {
   /** Return the given value in the free monad. */
   def pure[S[_], M[_], A](value: A)(implicit M: Applicative[M]): FreeT[S, M, A] = Suspend(M.pure(Right(value)))
 
+  @deprecated("Use FreeT.defer.", "1.0.0-MF")
   def suspend[S[_], M[_], A](a: M[Either[A, S[FreeT[S, M, A]]]])(implicit M: Applicative[M]): FreeT[S, M, A] =
+    defer(a)
+
+  def defer[S[_], M[_], A](a: M[Either[A, S[FreeT[S, M, A]]]])(implicit M: Applicative[M]): FreeT[S, M, A] =
     liftT(a).flatMap({
       case Left(a) => pure(a)
       case Right(s) => roll(s)

diff --git a/free/src/main/scala/cats/free/Trampoline.scala b/free/src/main/scala/cats/free/Trampoline.scala
@@ -7,10 +7,14 @@ private[free] abstract class TrampolineFunctions {
   def done[A](a: A): Trampoline[A] =
     Free.pure[Function0, A](a)
 
+  @deprecated("Use Trampoline.defer.", "1.0.0-MF")
   def suspend[A](a: => Trampoline[A]): Trampoline[A] =
-    Free.suspend(a)
+    defer(a)
+
+  def defer[A](a: => Trampoline[A]): Trampoline[A] =
+    Free.defer(a)
 
   def delay[A](a: => A): Trampoline[A] =
-    suspend(done(a))
+    defer(done(a))
 }
 
diff --git a/free/src/test/scala/cats/free/FreeTests.scala b/free/src/test/scala/cats/free/FreeTests.scala
@@ -32,16 +32,16 @@ class FreeTests extends CatsSuite {
     }
   }
 
-  test("suspend doesn't change value"){
+  test("defer doesn't change value"){
     forAll { x: Free[List, Int] =>
-      Free.suspend(x) should === (x)
+      Free.defer(x) should === (x)
     }
   }
 
-  test("suspend is lazy"){
+  test("defer is lazy"){
     def yikes[F[_], A]: Free[F, A] = throw new RuntimeException("blargh")
     // this shouldn't throw an exception unless we try to run it
-    val _ = Free.suspend(yikes[Option, Int])
+    val _ = Free.defer(yikes[Option, Int])
   }
 
   test("compile consistent with foldMap"){