Effectful.Internal.Monad

The Eff monad.

This module is intended for internal use only, and may change without warning in subsequent releases.

The Eff monad

data Eff (es :: [Effect]) a

The Eff monad provides the implementation of a computation that performs an arbitrary set of effects. In Eff es a, es is a type-level list that contains all the effects that the computation may perform. For example, a computation that produces an Integer by consuming a String from the global environment and acting upon a single mutable value of type Bool would have the following type:

(Reader String :> es, State Bool :> es) => Eff es Integer

Abstracting over the list of effects with (:>):

• Allows the computation to be used in functions that may perform other effects.
• Allows the effects to be handled in any order.

Instances

IOE :> es => MonadBase IO (Eff es)

Instance included for compatibility with existing code, usage of liftIO is preferrable.

Defined in Effectful.Internal.Monad

Methods

liftBase :: IO α -> Eff es α

IOE :> es => MonadBaseControl IO (Eff es)

Instance included for compatibility with existing code, usage of withRunInIO is preferrable.

Defined in Effectful.Internal.Monad

Associated Types

type StM (Eff es) a

Methods

liftBaseWith :: (RunInBase (Eff es) IO -> IO a) -> Eff es a

restoreM :: StM (Eff es) a -> Eff es a

Monad (Eff es)

Defined in Effectful.Internal.Monad

Methods

(>>=) :: Eff es a -> (a -> Eff es b) -> Eff es b

(>>) :: Eff es a -> Eff es b -> Eff es b

return :: a -> Eff es a

Functor (Eff es)

Defined in Effectful.Internal.Monad

Methods

fmap :: (a -> b) -> Eff es a -> Eff es b

(<$) :: a -> Eff es b -> Eff es a

MonadFix (Eff es)

Defined in Effectful.Internal.Monad

Methods

mfix :: (a -> Eff es a) -> Eff es a

Fail :> es => MonadFail (Eff es)

Defined in Effectful.Internal.Monad

Methods

fail :: String -> Eff es a

Applicative (Eff es)

Defined in Effectful.Internal.Monad

Methods

pure :: a -> Eff es a

(<*>) :: Eff es (a -> b) -> Eff es a -> Eff es b

liftA2 :: (a -> b -> c) -> Eff es a -> Eff es b -> Eff es c

(*>) :: Eff es a -> Eff es b -> Eff es b

(<*) :: Eff es a -> Eff es b -> Eff es a

IOE :> es => MonadIO (Eff es)

Defined in Effectful.Internal.Monad

Methods

liftIO :: IO a -> Eff es a

MonadThrow (Eff es)

Defined in Effectful.Internal.Monad

Methods

throwM :: Exception e => e -> Eff es a

MonadCatch (Eff es)

Defined in Effectful.Internal.Monad

Methods

catch :: Exception e => Eff es a -> (e -> Eff es a) -> Eff es a

MonadMask (Eff es)

Defined in Effectful.Internal.Monad

Methods

mask :: ((forall a. Eff es a -> Eff es a) -> Eff es b) -> Eff es b

uninterruptibleMask :: ((forall a. Eff es a -> Eff es a) -> Eff es b) -> Eff es b

generalBracket :: Eff es a -> (a -> ExitCase b -> Eff es c) -> (a -> Eff es b) -> Eff es (b, c)

Prim :> es => PrimMonad (Eff es)

Defined in Effectful.Internal.Monad

Associated Types

type PrimState (Eff es)

Methods

primitive :: (State# (PrimState (Eff es)) -> (# State# (PrimState (Eff es)), a #)) -> Eff es a

IOE :> es => MonadUnliftIO (Eff es)

Use withEffToIO if you want accurate stack traces on errors.

Defined in Effectful.Internal.Monad

Methods

withRunInIO :: ((forall a. Eff es a -> IO a) -> IO b) -> Eff es b

Semigroup a => Semigroup (Eff es a)

Defined in Effectful.Internal.Monad

Methods

(<>) :: Eff es a -> Eff es a -> Eff es a

sconcat :: NonEmpty (Eff es a) -> Eff es a

stimes :: Integral b => b -> Eff es a -> Eff es a

Monoid a => Monoid (Eff es a)

Defined in Effectful.Internal.Monad

Methods

mempty :: Eff es a

mappend :: Eff es a -> Eff es a -> Eff es a

mconcat :: [Eff es a] -> Eff es a

type PrimState (Eff es)

Defined in Effectful.Internal.Monad

type PrimState (Eff es) = RealWorld

type StM (Eff es) a

Defined in Effectful.Internal.Monad

type StM (Eff es) a = a

runPureEff :: Eff '[] a -> a

Run a pure Eff computation.

For running computations with side effects see runEff.

Access to the internal representation

unEff :: Eff es a -> Env es -> IO a

Peel off the constructor of Eff.

unsafeEff :: (Env es -> IO a) -> Eff es a

Access the underlying IO monad along with the environment.

This function is unsafe because it can be used to introduce arbitrary IO actions into pure Eff computations.

unsafeEff_ :: IO a -> Eff es a

Access the underlying IO monad.

This function is unsafe because it can be used to introduce arbitrary IO actions into pure Eff computations.

Fail

data Fail :: Effect where

Provide the ability to use the MonadFail instance of Eff.

Constructors

Fail :: String -> Fail m a

Instances

type DispatchOf Fail

Defined in Effectful.Internal.Monad

type DispatchOf Fail = 'Dynamic

IO

data IOE :: Effect

Run arbitrary IO computations via MonadIO or MonadUnliftIO.

Note: it is not recommended to use this effect in application code as it is too liberal. Ideally, this is only used in handlers of more fine-grained effects.

Instances

type DispatchOf IOE

Defined in Effectful.Internal.Monad

type DispatchOf IOE = 'Static 'WithSideEffects

newtype StaticRep IOE

Defined in Effectful.Internal.Monad

newtype StaticRep IOE = IOE UnliftStrategy

runEff :: Eff '[IOE] a -> IO a

Run an Eff computation with side effects.

For running pure computations see runPureEff.

Prim

data Prim :: Effect

Provide the ability to perform primitive state-transformer actions.

Instances

type DispatchOf Prim

Defined in Effectful.Internal.Monad

type DispatchOf Prim = 'Static 'WithSideEffects

data StaticRep Prim

Defined in Effectful.Internal.Monad

data StaticRep Prim = Prim

runPrim :: IOE :> es => Eff (Prim ': es) a -> Eff es a

Run an Eff computation with primitive state-transformer actions.

Lifting

raise :: Eff es a -> Eff (e ': es) a

Lift an Eff computation into an effect stack with one more effect.

Note: unless you need this function rarely, you're most likely working with monomorphic effect stacks, which is not recommended (see Eff for more information).

subsume :: e :> es => Eff (e ': es) a -> Eff es a

Eliminate a duplicate effect from the top of the effect stack.

inject :: Subset xs es => Eff xs a -> Eff es a

Allow for running an effect stack xs within es as long as xs is a permutation (with possible duplicates) of a subset of es.

Generalizes raise and subsume.

Note: this function should be needed rarely, usually when you have to cross API boundaries and monomorphic effect stacks are involved. Using monomorphic stacks is discouraged (see Eff), but sometimes might be necessary due to external constraints.

Unlifting

data UnliftStrategy

The strategy to use when unlifting Eff computations via withEffToIO, withRunInIO or the localUnlift family.

Warning: unlifting functions should not be used outside of continuations that brought them into scope. The behavior when doing so is undefined.

Constructors

SeqUnlift

The fastest strategy and a default setting for IOE. An attempt to call the unlifting function in threads distinct from its creator will result in a runtime error.

ConcUnlift !Persistence !Limit

A strategy that makes it possible for the unlifting function to be called in threads distinct from its creator. See Persistence and Limit settings for more information.

Instances

Eq UnliftStrategy

Defined in Effectful.Internal.Unlift

Methods

(==) :: UnliftStrategy -> UnliftStrategy -> Bool

(/=) :: UnliftStrategy -> UnliftStrategy -> Bool

Ord UnliftStrategy

Defined in Effectful.Internal.Unlift

Methods

compare :: UnliftStrategy -> UnliftStrategy -> Ordering

(<) :: UnliftStrategy -> UnliftStrategy -> Bool

(<=) :: UnliftStrategy -> UnliftStrategy -> Bool

(>) :: UnliftStrategy -> UnliftStrategy -> Bool

(>=) :: UnliftStrategy -> UnliftStrategy -> Bool

max :: UnliftStrategy -> UnliftStrategy -> UnliftStrategy

min :: UnliftStrategy -> UnliftStrategy -> UnliftStrategy

Show UnliftStrategy

Defined in Effectful.Internal.Unlift

Methods

showsPrec :: Int -> UnliftStrategy -> ShowS

show :: UnliftStrategy -> String

showList :: [UnliftStrategy] -> ShowS

Generic UnliftStrategy

Defined in Effectful.Internal.Unlift

Associated Types

type Rep UnliftStrategy :: Type -> Type

Methods

from :: UnliftStrategy -> Rep UnliftStrategy x

to :: Rep UnliftStrategy x -> UnliftStrategy

type Rep UnliftStrategy

Defined in Effectful.Internal.Unlift

type Rep UnliftStrategy = D1 ('MetaData "UnliftStrategy" "Effectful.Internal.Unlift" "effectful-core-1.0.0.0-4BpXn01Z327Fw2u2ibXHIX" 'False) (C1 ('MetaCons "SeqUnlift" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "ConcUnlift" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Persistence) :*: S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Limit)))

data Persistence

Persistence setting for the ConcUnlift strategy.

Different functions require different persistence strategies. Examples:

• Lifting pooledMapConcurrentlyN from the unliftio library requires the Ephemeral strategy as we don't want jobs to share environment changes made by previous jobs run in the same worker thread.
• Lifting forkIOWithUnmask requires the Persistent strategy, otherwise the unmasking function would start with a fresh environment each time it's called.

Constructors

Ephemeral

Don't persist the environment between calls to the unlifting function in threads distinct from its creator.

Persistent

Persist the environment between calls to the unlifting function within a particular thread.

Instances

Eq Persistence

Defined in Effectful.Internal.Unlift

Methods

(==) :: Persistence -> Persistence -> Bool

(/=) :: Persistence -> Persistence -> Bool

Ord Persistence

Defined in Effectful.Internal.Unlift

Methods

compare :: Persistence -> Persistence -> Ordering

(<) :: Persistence -> Persistence -> Bool

(<=) :: Persistence -> Persistence -> Bool

(>) :: Persistence -> Persistence -> Bool

(>=) :: Persistence -> Persistence -> Bool

max :: Persistence -> Persistence -> Persistence

min :: Persistence -> Persistence -> Persistence

Show Persistence

Defined in Effectful.Internal.Unlift

Methods

showsPrec :: Int -> Persistence -> ShowS

show :: Persistence -> String

showList :: [Persistence] -> ShowS

Generic Persistence

Defined in Effectful.Internal.Unlift

Associated Types

type Rep Persistence :: Type -> Type

Methods

from :: Persistence -> Rep Persistence x

to :: Rep Persistence x -> Persistence

type Rep Persistence

Defined in Effectful.Internal.Unlift

type Rep Persistence = D1 ('MetaData "Persistence" "Effectful.Internal.Unlift" "effectful-core-1.0.0.0-4BpXn01Z327Fw2u2ibXHIX" 'False) (C1 ('MetaCons "Ephemeral" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "Persistent" 'PrefixI 'False) (U1 :: Type -> Type))

data Limit

Limit setting for the ConcUnlift strategy.

Constructors

Limited !Int

Behavior dependent on the Persistence setting.

For Ephemeral, it limits the amount of uses of the unlifting function in threads distinct from its creator to N. The unlifting function will create N copies of the environment when called N times and K+1 copies when called K < N times.

For Persistent, it limits the amount of threads, distinct from the creator of the unlifting function, it can be called in to N. The amount of calls to the unlifting function within a particular threads is unlimited. The unlifting function will create N copies of the environment when called in N threads and K+1 copies when called in K < N threads.

Unlimited

Unlimited use of the unlifting function.

Instances

Eq Limit

Defined in Effectful.Internal.Unlift

Methods

(==) :: Limit -> Limit -> Bool

(/=) :: Limit -> Limit -> Bool

Ord Limit

Defined in Effectful.Internal.Unlift

Methods

compare :: Limit -> Limit -> Ordering

(<) :: Limit -> Limit -> Bool

(<=) :: Limit -> Limit -> Bool

(>) :: Limit -> Limit -> Bool

(>=) :: Limit -> Limit -> Bool

max :: Limit -> Limit -> Limit

min :: Limit -> Limit -> Limit

Show Limit

Defined in Effectful.Internal.Unlift

Methods

showsPrec :: Int -> Limit -> ShowS

show :: Limit -> String

showList :: [Limit] -> ShowS

Generic Limit

Defined in Effectful.Internal.Unlift

Associated Types

type Rep Limit :: Type -> Type

Methods

from :: Limit -> Rep Limit x

to :: Rep Limit x -> Limit

type Rep Limit

Defined in Effectful.Internal.Unlift

type Rep Limit = D1 ('MetaData "Limit" "Effectful.Internal.Unlift" "effectful-core-1.0.0.0-4BpXn01Z327Fw2u2ibXHIX" 'False) (C1 ('MetaCons "Limited" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Int)) :+: C1 ('MetaCons "Unlimited" 'PrefixI 'False) (U1 :: Type -> Type))

unliftStrategy :: IOE :> es => Eff es UnliftStrategy

Get the current UnliftStrategy.

withUnliftStrategy :: IOE :> es => UnliftStrategy -> Eff es a -> Eff es a

Locally override the UnliftStrategy with the given value.

withEffToIO

Arguments

:: (HasCallStack, IOE :> es)

=> ((forall r. Eff es r -> IO r) -> IO a)

Continuation with the unlifting function in scope.

Note: the strategy is reset to SeqUnlift inside the continuation.

-> Eff es a

Create an unlifting function with the current UnliftStrategy.

This function is equivalent to withRunInIO, but has a HasCallStack constraint for accurate stack traces in case an insufficiently powerful UnliftStrategy is used and the unlifting function fails.

Low-level unlifts

seqUnliftIO

Arguments

:: HasCallStack

=> Env es

The environment.

-> ((forall r. Eff es r -> IO r) -> IO a)

Continuation with the unlifting function in scope.

-> IO a

Create an unlifting function with the SeqUnlift strategy.

concUnliftIO

Arguments

:: HasCallStack

=> Env es

The environment.

-> Persistence

-> Limit

-> ((forall r. Eff es r -> IO r) -> IO a)

Continuation with the unlifting function in scope.

-> IO a

Create an unlifting function with the ConcUnlift strategy.

Dispatch

Dynamic dispatch

type EffectHandler e es

Arguments

 = forall a localEs. HasCallStack

=> LocalEnv localEs es

Capture of the local environment for handling local Eff computations when e is a higher order effect.

-> e (Eff localEs) a

The effect performed in the local environment.

-> Eff es a

Type signature of the effect handler.

newtype LocalEnv (localEs :: [Effect]) (handlerEs :: [Effect])

Opaque representation of the Eff environment at the point of calling the send function, i.e. right before the control is passed to the effect handler.

The second type variable represents effects of a handler and is needed for technical reasons to guarantee soundness.

Constructors

LocalEnv (Env localEs)

data Handler :: Effect -> Type where

An internal representation of dynamically dispatched effects, i.e. the effect handler bundled with its environment.

Constructors

Handler :: !(Env es) -> !(EffectHandler e es) -> Handler e

relinkHandler :: Relinker Handler e

runHandler :: DispatchOf e ~ Dynamic => Handler e -> Eff (e ': es) a -> Eff es a

Run a dynamically dispatched effect with the given handler.

send

Arguments

:: (HasCallStack, DispatchOf e ~ Dynamic, e :> es)

=> e (Eff es) a

The effect.

-> Eff es a

Send an operation of the given effect to its handler for execution.

Static dispatch

data family StaticRep (e :: Effect) :: Type

Internal representations of statically dispatched effects.

Instances

data StaticRep Prim

Defined in Effectful.Internal.Monad

data StaticRep Prim = Prim

newtype StaticRep IOE

Defined in Effectful.Internal.Monad

newtype StaticRep IOE = IOE UnliftStrategy

newtype StaticRep (Error e)

Defined in Effectful.Error.Static

newtype StaticRep (Error e) = Error ErrorId

newtype StaticRep (Reader r)

Defined in Effectful.Reader.Static

newtype StaticRep (Reader r) = Reader r

newtype StaticRep (State s)

Defined in Effectful.State.Static.Local

newtype StaticRep (State s) = State s

newtype StaticRep (State s)

Defined in Effectful.State.Static.Shared

newtype StaticRep (State s) = State (MVar s)

newtype StaticRep (Writer w)

Defined in Effectful.Writer.Static.Local

newtype StaticRep (Writer w) = Writer w

newtype StaticRep (Writer w)

Defined in Effectful.Writer.Static.Shared

newtype StaticRep (Writer w) = Writer (MVar w)

type family MaybeIOE (sideEffects :: SideEffects) (es :: [Effect]) :: Constraint where ...

Require the IOE effect for running statically dispatched effects whose operations perform side effects.

Equations

MaybeIOE NoSideEffects _ = ()

MaybeIOE WithSideEffects es = IOE :> es

runStaticRep

Arguments

:: (DispatchOf e ~ Static sideEffects, MaybeIOE sideEffects es)

=> StaticRep e

The initial representation.

-> Eff (e ': es) a

-> Eff es (a, StaticRep e)

Run a statically dispatched effect with the given initial representation and return the final value along with the final representation.

evalStaticRep

Arguments

:: (DispatchOf e ~ Static sideEffects, MaybeIOE sideEffects es)

=> StaticRep e

The initial representation.

-> Eff (e ': es) a

-> Eff es a

Run a statically dispatched effect with the given initial representation and return the final value, discarding the final representation.

execStaticRep

Arguments

:: (DispatchOf e ~ Static sideEffects, MaybeIOE sideEffects es)

=> StaticRep e

The initial representation.

-> Eff (e ': es) a

-> Eff es (StaticRep e)

Run a statically dispatched effect with the given initial representation and return the final representation, discarding the final value.

getStaticRep :: (DispatchOf e ~ Static sideEffects, e :> es) => Eff es (StaticRep e)

Fetch the current representation of the effect.

putStaticRep :: (DispatchOf e ~ Static sideEffects, e :> es) => StaticRep e -> Eff es ()

Set the current representation of the effect to the given value.

stateStaticRep

Arguments

:: (DispatchOf e ~ Static sideEffects, e :> es)

=> (StaticRep e -> (a, StaticRep e))

The function to modify the representation.

-> Eff es a

Apply the function to the current representation of the effect and return a value.

stateStaticRepM

Arguments

:: (DispatchOf e ~ Static sideEffects, e :> es)

=> (StaticRep e -> Eff es (a, StaticRep e))

The function to modify the representation.

-> Eff es a

Apply the monadic function to the current representation of the effect and return a value.

localStaticRep

Arguments

:: (DispatchOf e ~ Static sideEffects, e :> es)

=> (StaticRep e -> StaticRep e)

The function to temporarily modify the representation.

-> Eff es a

-> Eff es a

Execute a computation with a temporarily modified representation of the effect.

Primitive operations

consEnv

Arguments

:: EffectRep (DispatchOf e) e

The representation of the effect.

-> Relinker (EffectRep (DispatchOf e)) e

-> Env es

-> IO (Env (e ': es))

Extend the environment with a new data type (in place).

getEnv

Arguments

:: forall e es. e :> es

=> Env es

The environment.

-> IO (EffectRep (DispatchOf e) e)

Extract a specific data type from the environment.

putEnv

Arguments

:: forall e es. e :> es

=> Env es

The environment.

-> EffectRep (DispatchOf e) e

-> IO ()

Replace the data type in the environment with a new value (in place).

stateEnv

Arguments

:: forall e es a. e :> es

=> Env es

The environment.

-> (EffectRep (DispatchOf e) e -> (a, EffectRep (DispatchOf e) e))

-> IO a

Modify the data type in the environment (in place) and return a value.

modifyEnv

Arguments

:: forall e es. e :> es

=> Env es

The environment.

-> (EffectRep (DispatchOf e) e -> EffectRep (DispatchOf e) e)

-> IO ()

Modify the data type in the environment (in place).