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.

Since: 2.7.0.0

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

Since: 2.7.0.0

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.

Since: 2.7.0.0

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

Since: 2.7.0.0

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

Since: 2.7.0.0