Either concrete non-suspend fx (#124)

* Suspend fx

* Add concrete Either fx

* Fix docs

Co-authored-by: Alberto Ballano <[email protected]>

Author: nomisRev

arrow-libs/core/arrow-core-data/src/main/kotlin/arrow/core/Either.kt

@@ -5,9 +5,8 @@ import arrow.core.Either.Left
 import arrow.core.Either.Right
 import arrow.higherkind
 import arrow.typeclasses.Show
+import arrow.typeclasses.suspended.BindSyntax
 import kotlin.coroutines.Continuation
-import kotlin.coroutines.intrinsics.COROUTINE_SUSPENDED
-import kotlin.coroutines.intrinsics.startCoroutineUninterceptedOrReturn
 import kotlin.coroutines.intrinsics.suspendCoroutineUninterceptedOrReturn
 
 /**
@@ -651,6 +650,7 @@ import kotlin.coroutines.intrinsics.suspendCoroutineUninterceptedOrReturn
  * import arrow.core.extensions.fx
  * import arrow.core.Either
  *
+ * suspend fun main() {
  * val value =
  * //sampleStart
  *  Either.fx<Int, Int> {
@@ -660,7 +660,6 @@ import kotlin.coroutines.intrinsics.suspendCoroutineUninterceptedOrReturn
  *   a + b + c
  *  }
  * //sampleEnd
- * fun main() {
  *  println(value)
  * }
  * ```
@@ -901,6 +900,21 @@ sealed class Either<out A, out B> : EitherOf<A, B> {
       } catch (t: Throwable) {
         fe(t.nonFatalOrThrow()).left()
       }
+
+    fun <E, A> fx2(c: suspend EagerBind<EitherPartialOf<E>>.() -> A): Either<E, A> {
+      val continuation: EitherContinuation<E, A> = EitherContinuation()
+      return continuation.startCoroutineUninterceptedAndReturn {
+        Right(c())
+      } as Either<E, A>
+    }
+
+    suspend fun <E, A> fx(c: suspend BindSyntax<EitherPartialOf<E>>.() -> A): Either<E, A> =
+      suspendCoroutineUninterceptedOrReturn sc@{ cont ->
+        val continuation = EitherSContinuation(cont as Continuation<EitherOf<E, A>>)
+        continuation.startCoroutineUninterceptedOrReturn {
+          Right(c())
+        }
+      }
   }
 }
 
@@ -1102,29 +1116,20 @@ fun <A, B> EitherOf<A, B>.handleErrorWith(f: (A) -> EitherOf<A, B>): Either<A, B
     }
   }
 
-suspend fun <E, A> Either.Companion.fx(c: suspend EitherContinuation<E, A>.() -> A): Either<E, A> =
-  suspendCoroutineUninterceptedOrReturn sc@{ cont ->
-    val continuation = EitherContinuation(cont as Continuation<EitherOf<E, A>>)
-    val wrapReturn: suspend EitherContinuation<E, A>.() -> Either<E, A> = { c().right() }
-
-    // Returns either `Either<A, B>` or `COROUTINE_SUSPENDED`
-    val x: Any? = try {
-      wrapReturn.startCoroutineUninterceptedOrReturn(continuation, continuation)
-    } catch (e: Throwable) {
-      if (e is SuspendMonadContinuation.ShortCircuit) Left(e.e as E)
-      else throw e
-    }
-
-    return@sc if (x == COROUTINE_SUSPENDED) continuation.getResult()
-    else x as Either<E, A>
-  }
-
-class EitherContinuation<E, A>(
+internal class EitherSContinuation<E, A>(
   parent: Continuation<EitherOf<E, A>>
 ) : SuspendMonadContinuation<EitherPartialOf<E>, A>(parent) {
+  override fun ShortCircuit.recover(): Kind<EitherPartialOf<E>, A> =
+    Left(value as E)
+
   override suspend fun <A> Kind<EitherPartialOf<E>, A>.bind(): A =
     fix().fold({ e -> throw ShortCircuit(e) }, ::identity)
+}
 
+internal class EitherContinuation<E, A> : MonadContinuation<EitherPartialOf<E>, A>() {
   override fun ShortCircuit.recover(): Kind<EitherPartialOf<E>, A> =
-    Left(e as E)
+    Left(value as E)
+
+  override suspend fun <A> Kind<EitherPartialOf<E>, A>.bind(): A =
+    fix().fold({ e -> throw ShortCircuit(e) }, ::identity)
 }

arrow-libs/core/arrow-core-data/src/main/kotlin/arrow/core/MonadContinuation.kt

@@ -0,0 +1,46 @@
+package arrow.core
+
+import arrow.Kind
+import arrow.typeclasses.suspended.BindSyntax
+import kotlin.coroutines.Continuation
+import kotlin.coroutines.CoroutineContext
+import kotlin.coroutines.EmptyCoroutineContext
+import kotlin.coroutines.RestrictsSuspension
+import kotlin.coroutines.intrinsics.startCoroutineUninterceptedOrReturn
+
+@RestrictsSuspension
+interface EagerBind<F> : BindSyntax<F>
+
+@PublishedApi
+internal class ShortCircuit(val value: Any?) : RuntimeException(null, null) {
+  override fun fillInStackTrace(): Throwable = this
+  override fun toString(): String = "ShortCircuit($value)"
+}
+
+@Suppress("UNCHECKED_CAST")
+internal abstract class MonadContinuation<F, A> : Continuation<Kind<F, A>>, EagerBind<F> {
+
+  abstract fun ShortCircuit.recover(): Kind<F, A>
+
+  override val context: CoroutineContext = EmptyCoroutineContext
+
+  protected lateinit var returnedMonad: Kind<F, A>
+
+  fun returnedMonad(): Kind<F, A> = returnedMonad
+
+  override fun resumeWith(result: Result<Kind<F, A>>) {
+    result.fold({ returnedMonad = it }, { e ->
+      if (e is ShortCircuit) {
+        returnedMonad = e.recover()
+      } else throw e
+    })
+  }
+
+  fun startCoroutineUninterceptedAndReturn(f: suspend EagerBind<F>.() -> Kind<F, A>): Any? =
+    try {
+      f.startCoroutineUninterceptedOrReturn(this, this) as Kind<F, A>
+    } catch (e: Throwable) {
+      if (e is ShortCircuit) e.recover()
+      else throw e
+    }
+}

arrow-libs/core/arrow-core-data/src/main/kotlin/arrow/core/SuspendingMonadContinuation.kt

@@ -8,17 +8,16 @@ import kotlin.coroutines.Continuation
 import kotlin.coroutines.CoroutineContext
 import kotlin.coroutines.EmptyCoroutineContext
 import kotlin.coroutines.intrinsics.COROUTINE_SUSPENDED
+import kotlin.coroutines.intrinsics.startCoroutineUninterceptedOrReturn
 import kotlin.coroutines.resumeWithException
 
 internal const val UNDECIDED = 0
 internal const val SUSPENDED = 1
 
 @Suppress("UNCHECKED_CAST")
-abstract class SuspendMonadContinuation<F, A>(private val parent: Continuation<Kind<F, A>>) : Continuation<Kind<F, A>>, BindSyntax<F> {
-
-  class ShortCircuit(val e: Any?) : RuntimeException(null, null) {
-    override fun fillInStackTrace(): Throwable = this
-  }
+internal abstract class SuspendMonadContinuation<F, A>(
+  private val parent: Continuation<Kind<F, A>>
+) : Continuation<Kind<F, A>>, BindSyntax<F> {
 
   abstract fun ShortCircuit.recover(): Kind<F, A>
 
@@ -74,4 +73,15 @@ abstract class SuspendMonadContinuation<F, A>(private val parent: Continuation<K
         else -> return decision
       }
     }
+
+  fun startCoroutineUninterceptedOrReturn(f: suspend SuspendMonadContinuation<F, A>.() -> Kind<F, A>): Any? =
+    try {
+      f.startCoroutineUninterceptedOrReturn(this, this)?.let {
+        if (it == COROUTINE_SUSPENDED) getResult()
+        else it
+      }
+    } catch (e: Throwable) {
+      if (e is ShortCircuit) e.recover()
+      else throw e
+    }
 }

arrow-libs/core/arrow-core-data/src/main/kotlin/arrow/typeclasses/MonadContinuations.kt

@@ -12,16 +12,18 @@ import kotlin.coroutines.resume
 @RestrictsSuspension
 interface MonadSyntax<F> : Monad<F>, BindSyntax<F>
 
-open class MonadContinuation<F, A>(M: Monad<F>, override val context: CoroutineContext = EmptyCoroutineContext) :
-  Continuation<Kind<F, A>>, Monad<F> by M, BindSyntax<F>, MonadSyntax<F> {
+open class MonadContinuation<F, A>(
+  M: Monad<F>,
+  override val context: CoroutineContext = EmptyCoroutineContext
+) : Continuation<Kind<F, A>>, Monad<F> by M, BindSyntax<F>, MonadSyntax<F> {
 
   override fun resume(value: Kind<F, A>) {
     returnedMonad = value
   }
 
   @Suppress("UNCHECKED_CAST")
   override fun resumeWithException(exception: Throwable) {
-      throw exception
+    throw exception
   }
 
   protected lateinit var returnedMonad: Kind<F, A>

arrow-libs/core/arrow-core-data/src/test/kotlin/arrow/core/EitherTest.kt

@@ -212,6 +212,29 @@ class EitherTest : UnitSpec() {
       }
     }
 
+    "non-suspended Either.fx can bind immediate values" {
+      forAll(Gen.either(Gen.string(), Gen.int())) { either ->
+        Either.fx2<String, Int> {
+          val res = !either
+          res
+        } == either
+      }
+    }
+
+    "non-suspended Either.fx can safely handle immediate exceptions" {
+      forAll(Gen.int(), Gen.throwable()) { i: Int, exception ->
+        shouldThrow<Throwable> {
+          Either.fx2<String, Int> {
+            val res = !Either.Right(i)
+            throw exception
+            res
+          }
+
+          fail("It should never reach here. Either.fx should've thrown $exception")
+        } == exception
+      }
+    }
+
     "suspended Either.fx can bind immediate values" {
       Gen.either(Gen.string(), Gen.int())
         .random()

arrow-libs/core/arrow-docs/docs/patterns/errorhandling/README.md

@@ -236,7 +236,7 @@ fun getKnife(): Either<KnifeIsDull, Knife> = Right(Knife)
 fun lunch(knife: Knife, food: Lettuce): Either<InsufficientAmountOfLettuce, Salad> = Left(InsufficientAmountOfLettuce(5))
 
 //sampleStart
-fun prepareEither(): Either<CookingException, Salad> =
+suspend fun prepareEither(): Either<CookingException, Salad> =
   Either.fx {
     val lettuce = takeFoodFromRefrigerator().bind()
     val knife = getKnife().bind()
@@ -245,7 +245,9 @@ fun prepareEither(): Either<CookingException, Salad> =
   }
 //sampleEnd
 
-prepareEither()
+suspend fun main() {
+  prepareEither()
+}
 //Left(InsufficientAmountOfLettuce(5))
 ```