Effectful.Internal.Monad

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.

Run a pure Eff computation.

For running computations with side effects see runEff.

Provide the ability to use the Alternative and MonadPlus instance for Eff.

Provide the ability to use the MonadFail instance for Eff.

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.

Run an Eff computation with side effects.

For running pure computations see runPureEff.

Provide the ability to perform primitive state-transformer actions.

PrimState token for Eff. Used instead of RealWorld to prevent the Prim effect from executing arbitrary IO actions via ioToPrim.

Run an Eff computation with primitive state-transformer actions.

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

Lift an Eff computation into an effect stack with one more effect and create an unlifting function with the given strategy.

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

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.

>>> data E1 :: Effect>>> data E2 :: Effect>>> data E3 :: Effect

It makes it possible to rearrange the effect stack however you like:

>>> :{  shuffle :: Eff (E3 : E1 : E2 : es) a -> Eff (E1 : E2 : E3 : es) a  shuffle = inject:}

It can also turn a monomorphic effect stack into a polymorphic one:

>>> :{  toPoly :: (E1 :> es, E2 :> es, E3 :> es) => Eff [E1, E2, E3] a -> Eff es a  toPoly = inject:}

Moreover, it allows for hiding specific effects from downstream:

>>> :{  onlyE1 :: Eff (E1 : es) a -> Eff (E1 : E2 : E3 : es) a  onlyE1 = inject:}

>>> :{  onlyE2 :: Eff (E2 : es) a -> Eff (E1 : E2 : E3 : es) a  onlyE2 = inject:}

>>> :{  onlyE3 :: Eff (E3 : es) a -> Eff (E1 : E2 : E3 : es) a  onlyE3 = inject:}

However, it's not possible to inject a computation into an incompatible effect stack:

>>> :{  coerceEs :: Eff es1 a -> Eff es2 a  coerceEs = inject:}......Couldn't match type ‘es1’ with ‘es2’...

Provide evidence that xs is a subset of es.

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

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.

Limit setting for the ConcUnlift strategy.

Get the current UnliftStrategy.

Note: this strategy is implicitly used by the MonadUnliftIO and MonadBaseControl instance for Eff.

Locally override the current UnliftStrategy with the given value.

Create an unlifting function with the SeqUnlift strategy. For the general version see withEffToIO.

Note: usage of this function is preferrable to withRunInIO because of explicit unlifting strategy and better error reporting.

Create an unlifting function with the given strategy.

Note: usage of this function is preferrable to withRunInIO because of explicit unlifting strategy and better error reporting.

Create an unlifting function with the ConcUnlift strategy.