Enhance explanation of executing 'suspend' with guarantees/safety

[clojj]

I think this is an important part in the documentation:
https://github.com/arrow-kt/arrow/tree/master/arrow-site/docs/docs/io#safety--purity--referential-transparency

Maybe it is possible to expand this part with at least one concrete example of

• which framework actually provides that f: (Result<A>) -> Unit to run a suspend () -> A program
• how the user (is it the user/developer of Arrow in this case ?) can recover from any exception

Referring respectively to

So the suspend API can also always return any exception safely to the user, and it can be recovered from at any point in the code.
and
..., we can only find startCoroutine in the standard library and it's isomorphic to unsafeRunAsync.
Instead of f: (Either<Throwable, A>) -> Unit you provide f: (Result<A>) -> Unit to run the suspend () -> A program.

[nomisRev]

Hey @clojj,

Thanks for opening this discussion!

which framework actually provides that f: (Result) -> Unit to run a suspend () -> A program

This is actually provided by the Kotlin Standard Library here and you can use it to run any suspend program with a callback.

val program: suspend () -> Int = suspend { 10 }
program.startCoroutine(Continuation(EmptyCoroutineContext) { result ->
   val i = result.getOrNull() // 10
})

But this is considered to bit a bit low-level, and when working with a frameworks there are other options.
For example, Ktor exposes a suspend API directly which does startCoroutine somewhere behind the scenes.

how the user (is it the user/developer of Arrow in this case ?) can recover from any exception

The idea is that just like you cannot execute IO code without calling unsafeRunXXX you can also not called suspend code from regular code. So this prevents you from executing side-effects in your code.
To recover from any orror you can just use Either.catch { } with handleError, getOrElse etc.

suspend fun program(): Int = 10

suspend fun program2(): Either<Throwable, Int> =
  Either.catch { program() }
  
suspend fun program3(): Int =
  Either.catch { program() }.getOrElse { 0 }

The cool thing about suspend is that you can simply use try/catch safely in combination with suspend, in contrast where you're unable to do that if in Java since that would require callbacks to write suspend code.
However, a better description on how we deal with errors can be found here (I linked the doc for the latest SNAPSHOT).

[nomisRev]

I hope that answers all your questions, and then we can add this extra information in the docs :)

[kyay10]

Closing since the relevant line has been added to the docs