effectful-th 1.0.0.0 → 1.0.0.1
raw patch · 3 files changed
+72/−48 lines, 3 filesdep +effectful-coredep −effectfuldep ~template-haskelldep ~th-abstractionPVP ok
version bump matches the API change (PVP)
Dependencies added: effectful-core
Dependencies removed: effectful
Dependency ranges changed: template-haskell, th-abstraction
API changes (from Hackage documentation)
Files
- CHANGELOG.md +3/−0
- README.md +62/−42
- effectful-th.cabal +7/−6
CHANGELOG.md view
@@ -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.
README.md view
@@ -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.
effectful-th.cabal view
@@ -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