Effectful.Internal.Unlift

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.

Concurrent unlift with limited uses that doesn't preserve the environment between calls to the unlifting function in threads other than its creator.

Concurrent unlift with unlimited uses that doesn't preserve the environment between calls to the unlifting function in threads other than its creator.

Concurrent unlift that preserves the environment between calls to the unlifting function within a particular thread.

Variant of persistentConcUnlift for a single other thread that doesn't need ThreadEntries.

Variant of persistentConcUnlift producing two unlifting functions that share the effect storage in each thread.

Variant of persistentConcUnlifts for a single other thread that doesn't need ThreadEntries.