# fused-effects: A fast, flexible, fused effect system.

**This is a package candidate release!** Here you can preview how this package release will appear once published to the main package index (which can be accomplished via the 'maintain' link below). Please note that once a package has been published to the main package index it cannot be undone! Please consult the package uploading documentation for more information.

A fast, flexible, fused effect system, à la Effect Handlers in Scope, Monad Transformers and Modular Algebraic Effects: What Binds Them Together, and Fusion for Free—Efficient Algebraic Effect Handlers.

[Skip to ReadMe]

## Properties

Versions | 0.1.0.0, 0.1.1.0, 0.1.2.0, 0.1.2.1, 0.2.0.0, 0.2.0.1, 0.2.0.2, 0.3.0.0, 0.3.1.0, 0.4.0.0, 0.5.0.0, 0.5.0.1, 1.0.0.0, 1.0.0.0 |
---|---|

Change log | ChangeLog.md |

Dependencies | base (>=4.9 && <4.14), transformers (>=0.4 && <0.6) [details] |

License | BSD-3-Clause |

Copyright | 2018-2019 Nicolas Wu, Tom Schrijvers, Rob Rix, Patrick Thomson |

Author | Nicolas Wu, Tom Schrijvers, Rob Rix, Patrick Thomson |

Maintainer | robrix@github.com |

Category | Control |

Home page | https://github.com/fused-effects/fused-effects |

Source repository | head: git clone https://github.com/fused-effects/fused-effects |

Uploaded | Mon Nov 11 20:02:34 UTC 2019 by patrick_thomson |

## Modules

[Index]

*Control*- Control.Algebra
*Carrier**Choose**Cull**Cut**Empty**Error**Fail**Fresh*- Control.Carrier.Interpret
- Control.Carrier.Lift
*NonDet*- Control.Carrier.Reader
*State**Throw**Trace**Writer*

*Effect*- Control.Effect.Catch
- Control.Effect.Choose
- Control.Effect.Class
- Control.Effect.Cull
- Control.Effect.Cut
- Control.Effect.Empty
- Control.Effect.Error
- Control.Effect.Fail
- Control.Effect.Fresh
- Control.Effect.Lift
- Control.Effect.NonDet
- Control.Effect.Reader
- Control.Effect.State
- Control.Effect.Sum
- Control.Effect.Throw
- Control.Effect.Trace
- Control.Effect.Writer

## Downloads

- fused-effects-1.0.0.0.tar.gz [browse] (Cabal source package)
- Package description (as included in the package)

#### Maintainers' corner

For package maintainers and hackage trustees

## Readme for fused-effects-1.0.0.0

[back to package description]# A fast, flexible, fused effect system for Haskell

## Overview

`fused-effects`

is an effect system for Haskell that values expressivity, efficiency, and rigor. It provides an encoding of algebraic, higher-order effects, includes a library of the most common effects, and generates efficient code by fusing effect handlers through computations. It is suitable for use in hobbyist, research, and industrial contexts.

Readers already familiar with effect systems may wish to start with the usage instead. For those interested, this talk at Strange Loop outlines the history of and motivation behind effect systems and `fused-effects`

itself.

```
{-# LANGUAGE ConstraintKinds, FlexibleInstances, GeneralizedNewtypeDeriving, MultiParamTypeClasses, UndecidableInstances #-}
module Main (module Main) where
import Control.Algebra
import Control.Carrier.Lift
import Control.Carrier.Reader
import Control.Carrier.State.Strict
import Control.Monad.IO.Class (liftIO)
import qualified Control.Monad.State.Class as MTL
main :: IO ()
main = pure ()
```

-->
### Algebraic effects

In `fused-effects`

and other systems with *algebraic* (or, sometimes, *extensible*) effects, effectful programs are split into two parts: the specification (or *syntax*) of the actions to be performed, and the interpretation (or *semantics*) given to them.

In `fused-effects`

, *effect types* provide syntax and *carrier types* provide semantics. Effect types are datatypes with one constructor for each action, invoked using the `send`

builtin. Carriers are monads, with an `Algebra`

instance specifying how an effect’s constructors should be interpreted. Carriers can handle more than one effect, and multiple carriers can be defined for the same effect, corresponding to different interpreters for the effect’s syntax.

### Higher-order effects

Unlike some other effect systems, `fused-effects`

offers *higher-order* (or *scoped*) effects in addition to first-order algebraic effects. In a strictly first-order algebraic effect system, operations like `local`

or `catchError`

, which specify some action limited to a given scope, must be implemented as interpreters, hard-coding their meaning in precisely the manner algebraic effects were designed to avoid. By specifying effects as higher-order functors, this limitation is removed, meaning that these operations admit a variety of interpretations. This means, for example, that you can introspect and redefine both the `local`

and `ask`

operations provided by the `Reader`

effect, rather than solely `ask`

(as is the case with certain formulations of algebraic effects).

As Nicolas Wu et al. showed in *Effect Handlers in Scope*, this has implications for the expressiveness of effect systems. It also has the benefit of making effect handling more consistent, since scoped operations are just syntax which can be interpreted like any other, and are thus simpler to reason about.

### Fusion

In order to maximize efficiency, `fused-effects`

applies *fusion laws*, avoiding the construction of intermediate representations of effectful computations between effect handlers. In fact, this is applied as far as the initial construction as well: there is no representation of the computation as a free monad parameterized by some syntax type. As such, `fused-effects`

avoids the overhead associated with constructing and evaluating any underlying free or freer monad.

Instead, computations are performed in a carrier type for the syntax, typically a monad wrapping further monads, via an instance of the `Carrier`

class. This carrier is specific to the effect handler selected, but since it isn’t described until the handler is applied, the separation between specification and interpretation is maintained. Computations are written against an abstract effectful signature, and only specialized to some concrete carrier when their effects are interpreted.

Since the interpretation of effects is written as a typeclass instance which `ghc`

is eager to inline, performance is excellent: approximately on par with `mtl`

.

Finally, since the fusion of carrier algebras occurs as a result of the selection of the carriers, it doesn’t depend on complex `RULES`

pragmas, making it easy to reason about and tune.

## Usage

### Package organization

The `fused-effects`

package is organized into two module hierarchies:

- those under
`Control.Effect`

, which provide effects and functions that invoke these effects’ capabilities. - those under
`Control.Carrier`

, which provide carrier types capable of executing the effects described by a given effect type.

An additional module, `Control.Algebra`

, provides the `Algebra`

interface that carrier types implement to provide an interpretation of a given effect. You shouldn’t need to import it unless you’re defining your own effects.

### Invoking effects

Each module under the `Control.Effect`

hierarchy provides a set of functions that invoke effects, each mapping to a constructor of the underlying effect type. These functions are similar to, but more powerful than, those provided by `mtl`

. In this example, we invoke the `get`

and `put`

functions provided by `Control.Effect.State`

, first extracting the state and then updating it with a new value:

```
action1 :: Has (State String) sig m => m ()
action1 = get >>= \ s -> put ("hello, " ++ s)
```

The `Has`

constraint requires a given effect (here `State`

) to be present in a *signature* (`sig`

), and relates that signature to be present in a carrier type (`m`

). We generally, but not always, program against an abstract carrier type, usually called `m`

, as carrier types always implement the `Monad`

typeclass.

To add effects to a given computation, add more `Has`

constraints to the signature/carrier pair `sig`

and `m`

. For example, to add a `Reader`

effect managing an `Int`

, we would write:

```
action2 :: (Has (State String) sig m, Has (Reader Int) sig m) => m ()
action2 = do
i <- ask
put (replicate i '!')
```

### Running effects

Effects are run with *effect handlers*, specified as functions (generally starting with `run…`

) unpacking some specific monad with a `Carrier`

instance. For example, we can run a `State`

computation using `runState`

, imported from the `Control.Carrier.State.Strict`

carrier module:

```
example1 :: (Algebra sig m, Effect sig) => [a] -> m (Int, ())
example1 list = runState 0 $ do
i <- get
put (i + length list)
```

`runState`

returns a tuple of both the computed value (the `()`

) and the final state (the `Int`

), visible in the result of the returned computation. The `get`

function is resolved with a visible type application, due to the fact that effects can contain more than one state type (in contrast with `mtl`

’s `MonadState`

, which limits the user to a single state type).

Since this function returns a value in some carrier `m`

, effect handlers can be chained to run multiple effects. Here, we get the list to compute the length of from a `Reader`

effect:

```
example2 :: (Algebra sig m, Effect sig) => m (Int, ())
example2 = runReader "hello" . runState 0 $ do
list <- ask
put (length (list :: String))
```

(Note that the type annotation on `list`

is necessary to disambiguate the requested value, since otherwise all the typechecker knows is that it’s an arbitrary `Foldable`

. For more information, see the comparison to `mtl`

.)

When all effects have been handled, a computation’s final value can be extracted with `run`

:

```
example3 :: (Int, ())
example3 = run . runReader "hello" . runState 0 $ do
list <- ask
put (length (list :: String))
```

`run`

is itself actually an effect handler for the `Lift Identity`

effect, whose only operation is to lift a result value into a computation.

Alternatively, arbitrary `Monad`

s can be embedded into effectful computations using the `Lift`

effect. In this case, the underlying `Monad`

ic computation can be extracted using `runM`

. Here, we use the `MonadIO`

instance for the `LiftC`

carrier to lift `putStrLn`

into the middle of our computation:

```
example4 :: IO (Int, ())
example4 = runM . runReader "hello" . runState 0 $ do
list <- ask
liftIO (putStrLn list)
put (length list)
```

(Note that we no longer need to give a type annotation for `list`

, since `putStrLn`

constrains the type for us.)

### Required compiler extensions

When defining your own effects, you may need `-XKindSignatures`

if GHC cannot correctly infer the type of your handler; see the documentation on common errors for more information about this case. `-XDeriveGeneric`

can be used with many first-order effects to derive default implementations of `HFunctor`

and `Effect`

.

When defining carriers, you’ll need `-XTypeOperators`

to declare a `Carrier`

instance over (`:+:`

), `-XFlexibleInstances`

to loosen the conditions on the instance, `-XMultiParamTypeClasses`

since `Carrier`

takes two parameters, and `-XUndecidableInstances`

to satisfy the coverage condition for this instance.

The following invocation, taken from the teletype example, should suffice for most use or construction of effects and carriers:

```
{-# LANGUAGE DeriveFunctor, DeriveGeneric, FlexibleInstances, GeneralizedNewtypeDeriving, MultiParamTypeClasses, TypeOperators, UndecidableInstances #-}
```

### Defining new effects

The process of defining new effects is outlined in `docs/defining_effects.md`

, using the classic `Teletype`

effect as an example.

## Project overview

This project builds a Haskell package named `fused-effects`

. The library’s sources are in `src`

. Unit tests are in `test`

, and library usage examples are in `examples`

. Further documentation can be found in `docs`

.

This project adheres to the Contributor Covenant code of conduct. By participating, you are expected to uphold this code.

Finally, this project is licensed under the BSD 3-clause license.

### Development

Development of `fused-effects`

is typically done using `cabal v2-build`

:

```
cabal v2-build # build the library
cabal v2-test # build and run the examples and tests
```

The package is available on hackage, and can be used by adding it to a component’s `build-depends`

field in your `.cabal`

file.

### Testing

`fused-effects`

comes with a rigorous test suite. Each law or property stated in the Haddock documentation is checked using generative tests powered by the `hedgehog`

library.

### Versioning

`fused-effects`

adheres to the Package Versioning Policy standard.

## Benchmarks

To run the provided benchmark suite, use `cabal v2-bench`

. You may wish to provide the `-O2`

compiler option to view performance under aggressive optimizations. `fused-effects`

has been benchmarked against a number of other effect systems. See also @patrickt’s benchmarks.

## Related work

`fused-effects`

is an encoding of higher-order algebraic effects following the recipes in *Effect Handlers in Scope* (Nicolas Wu, Tom Schrijvers, Ralf Hinze), *Monad Transformers and Modular Algebraic Effects: What Binds Them Together* (Tom Schrijvers, Maciej Piróg, Nicolas Wu, Mauro Jaskelioff), and *Fusion for Free—Efficient Algebraic Effect Handlers* (Nicolas Wu, Tom Schrijvers).

### Contributed packages

Though we aim to keep the `fused-effects`

core minimal, we encourage the development of external `fused-effects`

-compatible libraries. If you’ve written one that you’d like to be mentioned here, get in touch!

`fused-effects-lens`

provides combinators to use the`lens`

library fluently inside effectful computations.`fused-effects-exceptions`

provides handlers for exceptions thrown in the`IO`

monad.`fused-effects-resumable`

provides resumable exceptions, which can also serve as a limited form of coroutines.`fused-effects-random`

provides a`Random`

effect integrated into a`fused-effects`

stack.

### Projects using `fused-effects`

`semantic`

, a program analysis toolkit`aurapm`

, a package manager for Arch Linux`now-haskell`

, a client library for AWS Lambda

### Comparison to other effect libraries

#### Comparison to `mtl`

Like `mtl`

, `fused-effects`

provides a library of monadic effects which can be given different interpretations. In `mtl`

this is done by defining new instances of the typeclasses encoding the actions of the effect, e.g. `MonadState`

. In `fused-effects`

, this is done by defining new instances of the `Carrier`

typeclass for the effect.

Also like `mtl`

, `fused-effects`

allows scoped operations like `local`

and `catchError`

to be given different interpretations. As with first-order operations, `mtl`

achieves this with a final tagless encoding via methods, whereas `fused-effects`

achieves this with an initial algebra encoding via `Carrier`

instances.

Unlike `mtl`

, effects are automatically available regardless of where they occur in the signature; in `mtl`

this requires instances for all valid orderings of the transformers (O(n²) of them, in general).

Also unlike `mtl`

, there can be more than one `State`

or `Reader`

effect in a signature. This is a tradeoff: `mtl`

is able to provide excellent type inference for effectful operations like `get`

, since the functional dependencies can resolve the state type from the monad type. On the other hand, this behaviour can be recovered in `fused-effects`

using `newtype`

wrappers with phantom type parameters and helper functions, e.g.:

```
newtype Wrapper s m a = Wrapper { runWrapper :: m a }
deriving (Applicative, Functor, Monad)
instance Algebra sig m => Algebra sig (Wrapper s m) where
alg = Wrapper . alg . handleCoercible
getState :: Has (State s) sig m => Wrapper s m s
getState = get
```

Indeed, `Wrapper`

can now be made an instance of `MonadState`

:

```
instance Has (State s) sig m => MTL.MonadState s (Wrapper s m) where
get = Control.Carrier.State.Strict.get
put = Control.Carrier.State.Strict.put
```

Thus, the approaches aren’t mutually exclusive; consumers are free to decide which approach makes the most sense for their situation.

Unlike `fused-effects`

, `mtl`

provides a `ContT`

monad transformer; however, it’s worth noting that many behaviours possible with delimited continuations (e.g. resumable exceptions) are directly encodable as effects.

Finally, thanks to the fusion and inlining of carriers, `fused-effects`

is only marginally slower than equivalent `mtl`

code (see benchmarks).

#### Comparison to `freer-simple`

Like `freer-simple`

, `fused-effects`

uses an initial encoding of library- and user-defined effects as syntax which can then be given different interpretations. In `freer-simple`

, this is done with a family of interpreter functions (which cover a variety of needs, and which can be extended for more bespoke needs), whereas in `fused-effects`

this is done with `Carrier`

instances for `newtype`

s.

Unlike `fused-effects`

, in `freer-simple`

, scoped operations like `catchError`

and `local`

are implemented as interpreters, and can therefore not be given new interpretations.

Unlike `freer-simple`

, `fused-effects`

has relatively little attention paid to compiler error messaging, which can make common (compile-time) errors somewhat more confusing to diagnose. Similarly, `freer-simple`

’s family of interpreter functions can make the job of defining new effect handlers somewhat easier than in `fused-effects`

. Further, `freer-simple`

provides many of the same effects as `fused-effects`

, plus a coroutine effect, but minus resource management and random generation.

Finally, `fused-effects`

has been benchmarked as faster than `freer-simple`

.

#### Comparison to `polysemy`

Like `polysemy`

, `fused-effects`

is a batteries-included effect system capable of scoped, reinterpretable algebraic effects.

As of GHC 8.8, `fused-effects`

outperforms `polysemy`

, though new effects take more code to define in `fused-effects`

than `polysemy`

(though the `Control.Effect.Interpret`

effect is suitable for rapid prototyping of new effects). Like `freer-simple`

and unlike `fused-effects`

, polysemy provides custom type errors if a given effect invocation is ambigous or invalid in the current context.

#### Comparison to `eff`

`eff`

is similar in many ways to `fused-effects`

, but is slightly more performant due to its representation of effects as typeclasses. This approach lets GHC generate better code in exchange for sacrificing the flexibility associated with effects represented as data types. `eff`

also uses the `monad-control`

package to lift effects between contexts rather than implementing an `Algebra`

-style class itself.

### Acknowledgements

The authors of fused-effects would like to thank:

- Tom Schrijvers, Nicholas Wu, and all their collaborators for the research that led to
`fused-effects`

; - Alexis King for thoughtful discussions about and suggestions regarding our methodology;
- the authors of other effect libraries, including
`eff`

,`polysemy`

, and`capabilities`

, for their exploration of the space.