diff --git a/CHANGELOG.md b/CHANGELOG.md --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,2 +1,5 @@ +# effectful-th-1.0.0.1 (2023-01-13) +* Depend on `effectful-core`, not `effectful`. + # effectful-th-1.0.0.0 (2022-07-13) * Initial release. diff --git a/README.md b/README.md --- a/README.md +++ b/README.md @@ -40,28 +40,21 @@ [polysemy](https://hackage.haskell.org/package/polysemy), [eff](https://github.com/hasura/eff) and probably a few more. -Unfortunately, of all of them only `eff` is a promising proposition because of -reasonable performance characteristics (see the talk [Effects for -Less](https://www.youtube.com/watch?v=0jI-AlWEwYI) for more information) and -potential for good interoperability with the existing ecosystem. +It needs to be noted that of all of them only the work-in-progress `eff` library +is a promising proposition because of reasonable performance characteristics +(see the talk [Effects for Less](https://www.youtube.com/watch?v=0jI-AlWEwYI) +for more information) and potential for good interoperability with the existing +ecosystem. The second point is arguably the most important, because it allows focusing on things that matter instead of reinventing all kinds of wheels, hence being a necessary condition for broader adoption of the library. -However, `eff` uses delimited continuations underneath, which: - -- Are not yet supported by GHC (though [the -proposal](https://github.com/ghc-proposals/ghc-proposals/pull/313) for including -support for them has been accepted). - -- Are quite hard to understand. - -- Make the library "too powerful" in a sense as it faces - [a](https://github.com/hasura/eff/issues/13) - [few](https://github.com/hasura/eff/issues/7) - [issues](https://github.com/hasura/eff/issues/12) with no clear path towards - their resolution. +Unfortunately, the development of `eff` has stalled due to a +[few](https://github.com/hasura/eff/issues/13) +[subtle](https://github.com/hasura/eff/issues/7) +[issues](https://github.com/hasura/eff/issues/12) related to its use of +delimited continuations underneath. ### What about `mtl`? @@ -96,13 +89,24 @@ What is more, the `Eff` monad is concrete, so GHC has many possibilities for optimization, which results in a very fast code at a default optimization -level. There is no need to mark every function `INLINE` or enable additional -optimization passes, it just works. +level. There is no need to explicitly mark functions with `INLINE` pragmas or +enable additional optimization passes, it just works. ### Any downsides? -As always, there's no free lunch. The `Eff` monad doesn't support `NonDet` nor -`Coroutine` effects. However, the `NonDet` effect in existing libraries is +As always, there's no free lunch. The `Eff` monad doesn't support effect +handlers that require the ability to suspend or capture the rest of the +computation and resume it later (potentially multiple times). This prevents +`effectful` from providing (in particular): + +- A `NonDet` effect handler that executes multiple +[`Alternative`](https://hackage.haskell.org/package/base/docs/Control-Applicative.html#t:Alternative) +branches and collects their results. + +- A `Coroutine` effect. + +It needs to be noted however that such `NonDet` effect handler in existing +libraries is [broken](https://github.com/lexi-lambda/eff/blob/8c4df4bf54faf22456354be18095b14825be5e85/notes/semantics-zoo.md) and none of the ones with support for higher order effects provide the `Coroutine` effect, so arguably it's not a big loss. @@ -110,48 +114,64 @@ If you need such capability in your application, there are well established libraries such as [conduit](https://hackage.haskell.org/package/conduit) or [list-t](https://hackage.haskell.org/package/list-t) that can be used with -`effectful` without any issues. +`effectful` without any hassle. ### Summary -`effectful` is an extensible effects library that aims to replace "boring" -transformer stacks (which consist of a dozen of newtype'd `ExceptT`, `ReaderT`, -`StateT` and `WriterT` transformers) and their derivatives by providing -equivalent effects with improved semantics, performance and usability (it also -makes it easy to reuse them for your own effects). It doesn't try to make monad -transformers obsolete, so you're free to use it with `ConduitT`, `ContT`, -`ListT` etc. when necessary. +`effectful` is an extensible effects library that aims to be the replacement +for: +- The bare `ReaderT` pattern by being essentially its enriched version. + +- Monad transformer stacks typically encountered in the wild (i.e. consisting of + a dozen of newtype'd `ExceptT`, `ReaderT`, `StateT` and `WriterT` transformers + and their derivatives) by providing equivalent effects with improved + semantics, performance, usability and making it easy to reuse them for your + own effects. + +It doesn't try to make monad transformers obsolete, so you're free to +use it with `ConduitT`, `ContT`, `ListT` etc. when necessary. + ## Package structure -The effect system is split among several libraries: +The library is split among several packages: - The [`effectful-core`](https://hackage.haskell.org/package/effectful-core) - library contains the core of the effect system along with the basic - effects. It aims for a small dependency footprint and provides building blocks - for more advanced effects. + package contains the core of the library along with basic effects. It aims for + a small dependency footprint and provides building blocks for more advanced + effects. - The [`effectful-plugin`](https://hackage.haskell.org/package/effectful-plugin) - library provides an optional GHC plugin for improving disambiguation of + package provides an optional GHC plugin for improving disambiguation of effects (see [here](https://github.com/haskell-effectful/effectful/blob/master/effectful-plugin/README.md) for more information). -- The [`effectful-th`](https://hackage.haskell.org/package/effectful-th) library +- The [`effectful-th`](https://hackage.haskell.org/package/effectful-th) package provides utilities for generating bits of effect-related boilerplate via Template Haskell. -- The [`effectful`](https://hackage.haskell.org/package/effectful) library +- The [`effectful`](https://hackage.haskell.org/package/effectful) package re-exports public modules of `effectful-core` and additionally provides most - features of the `unliftio` library divided into appropriate effects. + features of the [`unliftio`](https://hackage.haskell.org/package/unliftio) + package divided into appropriate effects. -## Example +## Examples -A `Filesystem` effect with two handlers, one that runs in `IO` and another that -uses an in-memory virtual file system can be found -[here](https://github.com/haskell-effectful/effectful/blob/master/effectful/examples/FileSystem.hs). +For the examples see the *Introduction* sections of +[`Effectful.Dispatch.Dynamic`](https://hackage.haskell.org/package/effectful-core/docs/Effectful-Dispatch-Dynamic.html) +and +[`Effectful.Dispatch.Static`](https://hackage.haskell.org/package/effectful-core/docs/Effectful-Dispatch-Static.html). -## Resources +## Acknowledgements + +To all contributors of existing effect libraries - thank you for putting the +time and effort to explore the space. In particular, conversations in issue +trackers of `cleff`, `eff`, `freer-simple`, `fused-effects` and `polysemy` +repositories were invaluable in helping me discover and understand challenges in +the space. + +### Resources Resources that inspired the rise of this library and had a lot of impact on its design. diff --git a/effectful-th.cabal b/effectful-th.cabal --- a/effectful-th.cabal +++ b/effectful-th.cabal @@ -1,7 +1,7 @@ cabal-version: 2.4 build-type: Simple name: effectful-th -version: 1.0.0.0 +version: 1.0.0.1 license: BSD-3-Clause license-file: LICENSE category: Control @@ -9,14 +9,15 @@ author: Andrzej Rybczak synopsis: Template Haskell utilities for the effectful library. -description: Generate functions for performing operations of dynamically - dispatched effects via Template Haskell. +description: + Generate functions for performing operations of dynamically dispatched effects + via Template Haskell. extra-source-files: CHANGELOG.md README.md -tested-with: GHC ==8.8.4 || ==8.10.7 || ==9.0.2 || ==9.2.3 || ==9.4.1 +tested-with: GHC ==8.8.4 || ==8.10.7 || ==9.0.2 || ==9.2.5 || ==9.4.4 bug-reports: https://github.com/haskell-effectful/effectful/issues source-repository head @@ -55,7 +56,7 @@ build-depends: base >= 4.13 && < 5 , containers >= 0.6 - , effectful >= 1.0.0.0 && < 1.0.1.0 + , effectful-core >= 1.0.0.0 && < 3.0.0.0 , exceptions >= 0.10.4 , template-haskell >= 2.15 && < 2.20 , th-abstraction >= 0.4 && < 0.5 @@ -68,7 +69,7 @@ import: language build-depends: base - , effectful + , effectful-core , effectful-th hs-source-dirs: tests