3[](https://github.com/arybczak/effectful/actions?query=branch%3Amaster)
4[](https://rybczak.net/files/effectful/effectful-core-0.1-docs)
5[](https://rybczak.net/files/effectful/effectful-0.1-docs)
7<img src="https://user-images.githubusercontent.com/387658/127747903-f728437f-2ee4-47b8-9f0c-5102fd44c8e4.png" width="128">
9*Note:* this is a pre-release.
11An easy to use, performant extensible effects library with seamless integration
12with the existing Haskell ecosystem.
161. Very fast (benchmark results with GHC 8.8.4:
17 [countdown](https://rybczak.net/files/effectful/countdown.html),
18 [filesize](https://rybczak.net/files/effectful/filesize.html), [comparison
19 with eff](https://rybczak.net/files/effectful/eff_comparison.html)).
212. Easy to use API (no boilerplate code and dealing with arcane types).
233. Correct semantics in presence of runtime exceptions (no more lost state
264. Seamless integration with the existing ecosystem (`exceptions`,
27 `monad-control`, `unliftio-core`, `resourcet` etc.).
295. Effects can be defined for either
31 - static dispatch (as fast as it gets, single interpretation) or
33 - dynamic dispatch (a bit slower, multiple interpretations),
35 depending on your needs.
39Do we really need yet another library for handling effects? There's
40[freer-simple](https://hackage.haskell.org/package/freer-simple),
41[fused-effects](https://hackage.haskell.org/package/fused-effects),
42[polysemy](https://hackage.haskell.org/package/polysemy),
43[eff](https://github.com/hasura/eff) and probably a few more.
45Unfortunately, of all of them only `eff` is a promising proposition because of
46reasonable performance characteristics (see the talk "Effects for Less" linked
47below for more information) and potential for good interoperability with the
50The second point is arguably the most important, because it allows focusing on
51things that matter instead of reinventing all kinds of wheels and is crucial for
52adoption of the library.
54However, `eff` uses delimited continuations underneath, which:
56- Are not yet supported by GHC (though [the
57proposal](https://github.com/ghc-proposals/ghc-proposals/pull/313) for including
58support for them has been accepted).
60- Are quite hard to understand.
62- Make the library "too powerful" in a sense as it faces
63 [a](https://github.com/hasura/eff/issues/13)
64 [few](https://github.com/hasura/eff/issues/7)
65 [issues](https://github.com/hasura/eff/issues/12) with no clear path towards
68On the other hand, if support for continuations is excluded from the handler
69monad, then the ability to define effects with non-linear control flow (such as
70`NonDet`) is lost. Arguably it's a small price to pay for predictability,
71because such specialized effects are needed rarely and locally, at which point a
72dedicated, well established solution such as
73[conduit](https://hackage.haskell.org/package/conduit),
74[list-t](https://hackage.haskell.org/package/list-t) or
75[logict](https://hackage.haskell.org/package/logict) can be used.
77This is where `effectful` comes in. The `Eff` monad it uses is essentially a
78`ReaderT` over `IO` on steroids, allowing us to dynamically extend its
79environment with data types that represent effects or their handlers.
81Because this concept is so simple:
83- It's reasonably easy to understand what is going on under the hood.
85- The `Eff` monad being a reader allows for seamless interoperability with
86 ubiquitous classes such as `MonadBaseControl` and `MonadUnliftIO` as well as
87 support for handling runtime exceptions without worrying about lost or
88 discarded state (see the talk "Monad Transformer State" linked below for more
93- The `Eff` monad is concrete, so GHC has many possibilities for optimization,
94 which results in a very fast code at a default optimization level. There is no
95 need to mark every function `INLINE` or enable additional optimization passes,
98- If an advanced effect with non-linear control flow is needed, you can always
99 stick a transformer that implements it on top of `Eff` in a local context.
101In conclusion, `effectful` aims to reduce duplication and bring back performance
102to "boring" transformer stacks, most of which are a dozen of newtype'd `StateT`
103or `ReaderT` transformers, each with a few associated operations (usually tied
104to a type class), not to replace monad transformers altogether.
108The effect system and its effects are split among several libraries:
110- The `effectful-core` library contains the main machinery of the effect system
111 itself and a few basic effects.
112 It aims for a small dependency footprint and provides the building blocks for
113 more advanced effects.
115- _TBD_ `effectful-resource`, `effectful-process`, ...
117- Finally, the `effectful` library which comes with 'batteries included'. It is
118 build on top of the other libraries and re-exports the functionality of those.
122A `Filesystem` effect with two handlers, one that runs in `IO` and another that
123uses an in-memory virtual file system can be found
124[here](https://github.com/arybczak/effectful/blob/master/effectful/examples/FileSystem.hs).
128Resources that inspired the rise of this library and had a lot of impact on its
133* [Effects for Less](https://www.youtube.com/watch?v=0jI-AlWEwYI) by Alexis King.
135* [Monad Transformer State](https://www.youtube.com/watch?v=KZIN9f9rI34) by Michael Snoyman.
139* [ReaderT design pattern](https://www.fpcomplete.com/blog/2017/06/readert-design-pattern/) by Michael Snoyman.
141* [Exceptions Best Practices](https://www.fpcomplete.com/blog/2016/11/exceptions-best-practices-haskell/) by Michael Snoyman.
143----------------------------------------
145<div>Icons made by <a href="https://www.freepik.com" title="Freepik">Freepik</a> from <a href="https://www.flaticon.com/" title="Flaticon">www.flaticon.com</a></div>
keysesc to close
- j k
- move down, up
- enter
- open
- esc
- back, or up a level
- 1 2 3 4
- readme, files, commits, refs
- /
- filter
- y
- copy the clone command
- c
- compare the chosen commit with another (or shift-click both)
- ?
- show or hide this list