Effectful

The kind of effects.

A type of dispatch. For more information consult the documentation in Effectful.Dispatch.Dynamic and Effectful.Dispatch.Static.

Dispatch types of effects.

A constraint that requires that a particular effect e is a member of the type-level list es. This is used to parameterize an Eff computation over an arbitrary list of effects, so long as e is somewhere in the list.

For example, a computation that only needs access to a mutable value of type Integer would have the following type:

State Integer :> es => Eff es ()

Convenience operator for expressing that a function uses multiple effects in a more concise way than enumerating them all with (:>).

[E1, E2, ..., En] :>> es ≡ (E1 :> es, E2 :> es, ..., En :> es)

Run a pure Eff computation.

For running computations with side effects see runEff.

Note: the computation runs in a separate thread as a workaround for #380.

Run an Eff computation with side effects.

For running pure computations see runPureEff.

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.

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.

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.

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 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.