effectful

An easy to use, performant extensible effects library.

Version on this page:2.2.2.0
LTS Haskell 22.36:2.3.1.0
Stackage Nightly 2024-10-03:2.3.1.0
Latest on Hackage:2.3.1.0

See all snapshots effectful appears in

BSD-3-Clause licensed by Andrzej Rybczak
Maintained by [email protected]
This version can be pinned in stack with:effectful-2.2.2.0@sha256:1d5682727c2d5ebd83f7a7ae0ef809369422ccd37d4157ae7e2084f2a1cf6cfd,6044

effectful

Build Status Hackage Dependencies Stackage LTS Stackage Nightly

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.

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

Unfortunately, the development of eff has stalled due to a few subtle issues related to its use of delimited continuations underneath.

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 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 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 branches and collects their results.

  • A Coroutine effect.

It needs to be noted however that such NonDet effect handler 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 hassle.

Summary

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 library is split among several packages:

  • The effectful-core 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 package provides an optional GHC plugin for improving disambiguation of effects (see here for more information).

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

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

Examples

For the examples see the Introduction sections of Effectful.Dispatch.Dynamic and Effectful.Dispatch.Static.

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.

Talks:

Blog posts:


Changes

effectful-2.2.2.0 (2023-01-11)

  • Add withSeqEffToIO and withConcEffToIO to Effectful.
  • Use strict IORef and MVar variants where appropriate.
  • Make inject work with effect stacks sharing a polymorphic suffix.

effectful-2.2.1.0 (2022-11-09)

  • Add localSeqLift and localLift to Effectful.Dispatch.Dynamic.

effectful-2.2.0.0 (2022-10-24)

  • Change PrimState for Eff from RealWorld to PrimStateEff to prevent the Prim effect from executing arbitrary IO actions via ioToPrim.
  • Deprecate (:>>) as GHC can’t efficiently deal with type families.
  • Add support for the Alternative and MonadPlus instances for Eff via the NonDet effect.

effectful-2.1.0.0 (2022-08-22)

  • Include the e :> localEs constraint in the EffectHandler to allow more flexibility in handling higher order effects.
  • Do not include internal stack frames in throwError from Effectful.Error.Dynamic.

effectful-2.0.0.0 (2022-08-12)

  • Make storage references in the environment immutable.
  • Remove checkSizeEnv and forkEnv from Effectful.Dispatch.Static.Primitive.
  • Add internal versioning of effects to prevent leakage of unsafeCoerce.
  • Make interpose and impose properly interact with other handlers.

effectful-1.2.0.0 (2022-07-28)

  • Change SuffixOf to SharedSuffix and make it behave as advertised.
  • Add raiseWith.

effectful-1.1.0.0 (2022-07-19)

  • Don’t reset the UnliftStrategy to SeqUnlift inside the continuation of withEffToIO.
  • Add withReader.

effectful-1.0.0.0 (2022-07-13)

  • Initial release.