# effectful: An easy to use, performant extensible effects library.

[ bsd3, control, library ] [ Propose Tags ]

An easy to use, performant extensible effects library with seamless integration with the existing Haskell ecosystem.

This is the "batteries-included" variant. See the effectful-core package if you need a more limited dependency footprint or want to browse documentation of core modules.

## Modules

[Index] [Quick Jump]

## Flags

Automatic Flags
NameDescriptionDefault
benchmark-foreign-libraries

Include other effect libraries in the benchmarks.

Disabled

Use -f <flag> to enable a flag, or -f -<flag> to disable that flag. More info

#### Maintainer's Corner

For package maintainers and hackage trustees

Candidates

• No Candidates
Versions [RSS] 0.0.0.0, 1.0.0.0, 1.1.0.0, 1.2.0.0, 2.0.0.0 (info) CHANGELOG.md async (>=2.2.2), base (>=4.13 && <5), bytestring (>=0.10), directory (>=1.3.2), effectful-core (>=2.0.0.0 && <2.0.1.0), process (>=1.6.9), stm (>=2.5.0.0), time (>=1.9.2), unliftio (>=0.2.20) [details] BSD-3-Clause Andrzej Rybczak andrzej@rybczak.net Control https://github.com/haskell-effectful/effectful/issues head: git clone https://github.com/haskell-effectful/effectful.git by arybczak at 2022-08-12T18:16:29Z NixOS:1.2.0.0 262 total (104 in the last 30 days) 2.25 (votes: 2) [estimated by Bayesian average] λ λ λ Docs available Last success reported on 2022-08-12

[back to package description]

# effectful

An easy to use, fast extensible effects library with seamless integration with the existing Haskell ecosystem.

Main features:

1. Very fast (benchmarks).

2. Easy to use API (comparable with usage of the MonadUnliftIO class).

3. Correct semantics in presence of runtime exceptions (no more discarded state updates).

4. Seamless integration with the existing ecosystem (exceptions, monad-control, unliftio-core, resourcet etc.).

5. Support for thread local and shared state (e.g. StateT provides a thread local state, while MVar holds a shared state, both approaches have their merits).

6. Support for statically (implementation determined at compile time) and dynamically (implementation determined at run time) dispatched effects.

## Motivation

Do we really need yet another library for handling effects? There's freer-simple, fused-effects, polysemy, 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 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 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 few issues with no clear path towards their resolution.

### What about mtl?

It's true that its "effects as classes" approach is widely known and used often.

However:

• mtl style effects are slow.

• The majority of popular monad transformers (except ReaderT) used for effect implementations are rife with subtle issues.

These are problematic enough that the ReaderT design pattern was invented. Its fundamentals are solid, but it's not an effect system.

A solution? Use the ReaderT pattern as a base and build around it to make an extensible effects library! This is where effectful comes in. The Eff monad it uses is essentially a ReaderT over IO on steroids, allowing us to extend its environment with data types representing effects.

This concept is quite simple, so:

• It's reasonably easy to understand what is going on under the hood.

• The Eff monad being a reader allows for seamless interoperability with ubiquitous classes such as MonadBaseControl and MonadUnliftIO and solves issues of monad transformers mentioned above.

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.

### 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 broken and none of the ones with support for higher order effects provide the Coroutine effect, so arguably it's not a big loss.

If you need such capability in your application, there are well established libraries such as conduit or list-t that can be used with effectful without any issues.

### 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.

## Package structure

The effect system is split among several libraries:

• The 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.

• The effectful-plugin library provides an optional GHC plugin for improving disambiguation of effects (see here for more information).

• The effectful-th library provides utilities for generating bits of effect-related boilerplate via Template Haskell.

• The effectful library re-exports public modules of effectful-core and additionally provides most features of the unliftio library divided into appropriate effects.

## Example

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.

## Resources

Resources that inspired the rise of this library and had a lot of impact on its design.

Talks:

Blog posts:

Icons made by Freepik from www.flaticon.com