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.

Peel off the constructor of Eff.

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.

Access the underlying IO monad.

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

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

Note: NonDet does not backtrack. Formally, it obeys the "left-catch" law for MonadPlus, rather than the "left-distribution" law. This means that it behaves more like Maybe than [].

Since: 2.2.0.0

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.

Since: 1.2.0.0

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

Allow for running an effect stack subEs within es as long as subEs 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 subEs 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.

Both cases come down to what happens when the unlifting function is called more than once in the same thread. If a thread calls it only once, the Persistence setting makes no observable difference.

Example 1

Consider a thread that modifies thread local state, then inspects it with a second call to the unlifting function:

>>> import Control.Concurrent
>>> import Control.Monad
>>> import Effectful
>>> import Effectful.State.Dynamic

>>> :{
  modifyThenGet :: UnliftStrategy -> IO Int
  modifyThenGet strategy = runEff . evalStateLocal @Int 0 $ do
    withEffToIO strategy $ \unlift -> do
      result <- newEmptyMVar
      void . forkIO $ do
        unlift $ modify @Int (+1)
        putMVar result =<< unlift (get @Int)
      takeMVar result
:}

With the Persistent strategy the unlifting function keeps the environment between the calls, so the second call sees the modification from the first one:

>>> modifyThenGet $ ConcUnlift Persistent (Limited 1)
1

On the other hand, with Ephemeral each call to the unlifting function starts with a fresh copy of the environment, so the modification is silently lost:

>>> modifyThenGet $ ConcUnlift Ephemeral (Limited 2)
0

This also showcases the limit meaning different things for the two settings: for the Persistent strategy it limits the number of threads the unlifting can happen in, for Ephemeral it limits the number of calls to the unlifting function.

Example 2

Consider a situation where a single worker thread runs multiple independent jobs:

>>> :{
  twoJobs :: UnliftStrategy -> IO [Int]
  twoJobs strategy = runEff . evalStateLocal @Int 0 $ do
    withEffToIO strategy $ \unlift -> do
      result <- newEmptyMVar
      void . forkIO $ do
        let job = unlift $ modify @Int (+1) >> get @Int
        putMVar result =<< sequence [job, job]
      takeMVar result
:}

With Ephemeral both jobs start from the environment as it was when the unlifting function was created:

>>> twoJobs $ ConcUnlift Ephemeral Unlimited
[1,1]

With Persistent the second job inherits changes made by the first one, even though the user would most likely expect them to be independent:

>>> twoJobs $ ConcUnlift Persistent Unlimited
[1,2]

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.

Since: 2.2.2.0

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.

Utility for lifting IO computations of type

IO a -> IO b

to

Eff es a -> Eff es b

This function is really unsafe because:

• It can be used to introduce arbitrary IO actions into pure Eff computations.
• The IO computation must run its argument in a way that's perceived as sequential to the outside observer, e.g. in the same thread or in a worker thread that finishes before the argument is run again.

Warning: if you disregard the second point, you will experience weird bugs, data races or internal consistency check failures.

When in doubt, use unsafeLiftMapIO, especially since this version saves only a simple safety check per call of reallyUnsafeLiftMapIO f.

Create an unlifting function.

This function is really unsafe because:

• It can be used to introduce arbitrary IO actions into pure Eff computations.
• Unlifted Eff computations must be run in a way that's perceived as sequential to the outside observer, e.g. in the same thread as the caller of reallyUnsafeUnliftIO or in a worker thread that finishes before another unlifted computation is run.

Warning: if you disregard the second point, you will experience weird bugs, data races or internal consistency check failures.

When in doubt, use unsafeSeqUnliftIO, especially since this version saves only a simple safety check per call of the unlifting function.

Create an unlifting function with the SeqUnlift strategy.

Create an unlifting function with the SeqForkUnlift strategy.

Create an unlifting function with the ConcUnlift strategy.

Create two unlifting functions with the SeqForkUnlift strategy.

The unlifting functions will share the effect storage (unlike with two separate calls to seqForkUnliftIO).

Warning: both environments must have the same underlying storage.

Since: 2.7.0.0

Create unlifting functions with the ConcUnlift strategy.

In the Persistent variant the unlifting functions will share the effect storage in each thread (unlike with two separate calls to concUnliftIO).

Warning: both environments must have the same underlying storage.

Since: 2.7.0.0

Type signature of the effect handler.

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.

Note: functions that consume it perform runtime checks to ensure that it's used within the scope of the effect handler it belongs to.

Unwrap the LocalEnv via requireMatchingStorages.

Make sure that the LocalEnv is used in the thread/context of the effect handler it belongs to.

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

Wrapper to prevent a space leak on reconstruction of Handler in relinkHandler (see https://gitlab.haskell.org/ghc/ghc/-/issues/25520).

Run a dynamically dispatched effect with the given handler.

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

Internal representations of statically dispatched effects.

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

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

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

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

Fetch the current representation of the effect.

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

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

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

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