Avail

Description

avail is a companion to monad transformers that allows you to add effect management to concrete monads, i.e. specify what effects a piece of code can perform.

Traditionally, in order to manage effects, the effect typeclasses are placed on a polymorphic monad type m so that other details of the monad type is not known at that point, effectively limiting what a function can do:

(MonadWriter Log m, MonadState Store m, MonadReader Env m) => m ()


While this works well, it has inevitable performance drawback because of the polymorphic m. GHC doesn't know the implementation of m, hence cannot perform much optimization. On the other hand, if we use a concrete monad stack that supports all the effects we need, we will not be able to restrict the effects that can be performed.

avail addresses this by a monad transformer M. For any monad m, the monad type M m adds effect management on top of it. Specifically, for an effect typeclass c (such as MonadIO or MonadReader r), its methods can be used on M m only if:

• The monad m actually supports the effect, i.e. has an instance c m of the effect typeclass;
• The effect is available in current context, i.e. a phantom constraint Eff c (which doesn't contain any information) is added to the function signature.

This pattern was first outlined in the blog post Effect is a phantom. In avail, it allows you to manage effects via the phantom Eff constraint while still using a concrete monad stack; the Eff constarint is not tied to the stack anyhow. Finally, Eff has no instances, and can only be removed all at once via the runM function, obtaining the underlying monad.

avail supports libraries including mtl, unliftio, monad-control and capability out of the box, so there should be near-zero boilerplate to get started with avail. For other effect typeclasses, the avail support of them can be easily derived via the TH functions in Avail.Derive.

You need these language extensions when using this module:

DataKinds
FlexibleContexts
FlexibleInstances
RankNTypes
TypeApplications


You need more extensions when using Avail.Derive; see documentation in that module.

Synopsis

# Documentation

data M m a Source #

The M monad transformer acts as a barrier of effects. For example, for a monad type App and any effect typeclass MonadOvO that App has an instance of, the constraint Eff MonadOvO is required to perform the methods of MonadOvO in the monad M App as defined for the App monad.

In particular, M is expected to be used on a concrete monad instead of a polymorphic one. This is particularly good in terms of program performance, and generally means instead of writing this:

f :: MonadState Int m => m ()


You should write

f :: Eff (MonadState Int) => M App ()


where App is a monad stack of your choice that has support of MonadState Int. This also means there is no MonadTrans instance for M.

Note: you should not define instances of M for effect typeclasses directly by hand as that is error-prone and may create holes in effect management. For defining instances of effect typeclasses for M, check out the Avail.Derive module and specifically the avail and avail' TH functions.

Also keep in mind that typeclasses inside mtl, exceptions, unliftio, monad-control and capability work with M out-of-the-box so no instance for them is needed to be defined on M by you.

#### Instances

Instances details