Documentation

A restricted form of unsafeCoerce that only works for converting to/from Any. Still just as unsafe, but makes it slightly more difficult to accidentally misuse.

Used to explicitly overwrite references to values that should not be retained by the GC.

The kind of effects.

All eff computations operate in the Eff monad. Eff computations are parameterized by a type-level list that specifies which effects they are allowed to perform. For example, a computation of type Eff '[Error e, Reader r, State s] a can raise exceptions of type e, can access a global environment of type r, and can read and modify a single cell of mutable state of type s.

To run an Eff computation that performs effects, the effects must be explicitly handled. Functions that handle effects are called effect handlers, and they usually have types like the following:

runX :: Eff (X ': effs) a -> Eff effs a

Note that the argument to runX can perform the X effect, but the result cannot! Any X operations have been handled by runX, which interprets their meaning. Examples of effect handlers include runError, runReader, and runState.

After all effects have been handled, the resulting computation will have type Eff '[] a, a computation that performs no effects. A computation with this type is pure, so it can be converted to an ordinary value using run.

Some effects cannot be handled locally, but instead require performing I/O. These effects will delegate to the IOE effect, which provides low-level interop with Haskell’s built-in IO monad. After all other effects have been handled, a computation of type Eff '[IOE] a can be converted to an ordinary IO a computation using runIO.

Runs an EVM action with a new prompt installed. The arguments specify what happens when control exits the action.

Like promptVM, but for prompts that cannot be the target of a capture or abort (that is, prompts that only install winders/unwinders).

Runs a pure Eff computation to produce a value.

>>> run $ pure 42
42
>>> run $ runError $ throw "bang"
Left "bang"

The monad that effect handlers run in.

• The eff parameter is the effect being handled, and the effs parameter includes the other effects in scope at the point of the handle call (used by liftH).
• The i parameter is the return type of the handled computation before the exit handler has been applied (used by control0).
• The r parameter is the final return type of the handled computation (used by abort, control, and control0).
• The effs' parameter is the list of effects in scope at the point of the originating send call (used by locally).

See handle for more details.

Handles the topmost effect in an Eff computation. The given handler function must provide an interpretation for each effectful operation. The handler runs in the restrictive Handle monad, which generally uses one of the following core Handle operations:

• liftH — Runs an action in the context of the original handle call. This is the most common way to handle an effect.
• abort — Aborts the computation to the handle call and returns a value directly. This is usually used to implement exception-like operations.
• control — Captures the current continuation up to and including the handle call and aborts, passing the captured continuation to the handler. This can be used to implement complex control operators such as coroutines or resumable exceptions.
• control0 — Like control, but does not include the handle call itself in the captured continuation, so a different handler may be installed before resuming the computation.
• locally — Runs an action directly in the context of the originating send call. This can be used to implement “scoped” operations like local and catch.

See the documentation for each of the above functions for examples and more details.

Lifts an Eff computation into one that performs all the same effects, and possibly more. For example, if you have a computation

m :: Eff '[Foo, Bar] ()

then lift will transform it into a polymorphic computation with the following type:

lift m :: (Foo :< effs, Bar :< effs) => Eff effs ()

This type is much more general, and effs can now be instantiated at many different types. Generally, lift can manipulate the list of effects in any of the following ways:

• Effects can be reordered.
• New effects can be inserted anywhere in the list.
• Duplicate effects can be collapsed.

More generally, the list of effects doesn’t need to be entirely concrete in order for lift to work. For example, if you have a computation

n :: Eff (Foo ': Bar ': effs1) ()

then lift n will have the following type:

lift n :: (Foo :< effs2, Bar :< effs2, effs1 :<< effs2) => Eff effs2 ()

This type is extremely general, and it allows lift to manipulate the head of the effects list even if the entire list is not completely known.

The Lift typeclass provides some type-level programming machinery to implement lift, but it should be treated as an implementation detail. In most situations, the machinery should “just work,” but if it doesn’t, the type errors can be somewhat inscrutable. In those situations, adding some explicit type annotations (or using TypeApplications) can improve the type errors significantly.

Like lift, but restricted to introducing a single additional effect in the result. This is behaviorally identical to just using lift, but the restricted type can produce better type inference.

An effect used to run IO operations via liftIO. Handled by the special runIO handler.

Converts an Eff computation to IO. Unlike most handlers, IOE must be the final effect handled, and runIO completely replaces the call to run.

The State s effect provides access to a single cell of mutable state of type s.

The NonDet effect provides so-called nondeterministic execution, which runs all branches of a computation and collects some or all of their results. Actual execution is not usually truly nondeterministic in the sense that it is somehow random; rather, NonDet models nondeterministic binary choice by executing both possibilities rather than choosing just one.