Transfer Cont from @nomisrev to arrow

[i-walker]

Thanks to @nomisRev proposal 🙌🏾
I've slightly changed the names from Cont to Effect and ContEffect to EffectScope, e.g.:

class DomainError(msg: String) 

context(CoroutineScope, EffectScope<DomainError>)
suspend fun program(): Int {
    val fa = async<Int> { shift(DomainError("error")) }
    val fb = async { delay(2000); 1 }
    return fa.await() + fb.await()
}

Feedback is welcome ☺️

[nomisRev]

I think we should use the same trick here as we do for Effect, so users have an escape hatch to differentiate between JobCanncellationException and ShiftCanncelationException when they have to in low-level niche use-cases.

[i-walker]

added tests in EagerEffect and Effect for low-level use-cases

[nomisRev]

This is not the documentation we want, this was part of the design process/documentation.
What we want instead is the README.MD

I'm thinking we should make it part of the KDoc on top of Effect, and link the page to Effect as well.

Currently, a lot of users have a hard time understanding the difference between Effect and EagerEffect and when or why they should be using either { } vs either.eager { }. This is currently completely undocumented inside arrow-continuations/arrow.core.computations.

I think we should add proper documentation in this PR before we merge, otherwise, it's going to be dropped to the bottom of the backlog again.

[i-walker]

I've ported most of the Docs and still updating others, but the last commit can be reviewed

[i-walker]

Updated most places I was aware of, can I get another review

[i-walker]

I removed EagerEffect<R, A>.toEffect(): Effect<R, A>, because effect { } and eagerEffect { } can fold or bind() an EagerEffect value and it would introduce multiple paths of how to operate with this value doing something like toEffect().bind(), even though bind() is sufficient.

[nomisRev]

Great work @i-walker! Thanks for all the great effort moving this into Arrow 🥳 👏 👏 👏

[nomisRev]

Not blocking this PR but I think we should put Effect under extensions and data types because it's something we want to promote.

It's the new implementation of Arrow's most powerful feature "computation blocks", and offers polymorphic properties we didn't have before. If we can somehow reference from the Effect page that'd be awesome.

Not sure if we have to link EffectScope, and EagerEffectScope since those should be linked from the Effect * EagerEffect page.
We can put EagerEffect alongside Effect and get away with only 2 new entries on the page, instead of a new section with 4 sub-sections.

I can take a stab at this in a subsequent PR though. What do you think?

cc\ @arrow-kt/maintainers

[i-walker]

Yes sounds great too, it would be great if we could link EffectScope with EagerEffectScope and showing they cover similar signatures.
And rearranging it sounds super.

On that note now that we moved on from Data type + extension (aka implementation of a Type class) we might want to consider just having Data types and computations.

The few typeclasses we have left can also have a dedicated place, if necessary
Just as a note, though.

[nomisRev]

Idem. Arrow Core functionality.
We have a document already concerning Arrow Fx Coroutines & Structured Concurrency, no?
If we don't need to create a ticket to write one and add it to this documentation page.

[i-walker]

We have this, but it doesn't go as deep as Semantics of Structured Concurrency and Effect maybe we can create a ticket and I'd be happy to contribute it. Or help in whatever way

[nomisRev]

If we follow the changes suggested above, we should add Effect and EagerEffect to Extensions and data types above.

Can be done in subsequent PR.

[i-walker]

yes we can leave it as a task in a ticket regarding how/ or what we should show on the site

[i-walker]

Thanks for extensive review @nomisRev, learnt a lot 🤗