@@ -6,7 +6,7 @@
66-- This module is intended for internal use only, and may change without warning
77-- in subsequent releases.
88module Effectful.Internal.Monad
9− ( -- * Monad
9+ ( -- * The 'Eff' monad
1010 Eff
1111 , runPureEff
1212
@@ -22,11 +22,11 @@ module Effectful.Internal.Monad
2222 , IOE
2323 , runEff
2424
25− -- * Primitive
25+ -- * Prim
2626 , Prim
2727 , runPrim
2828
29− -- ** Unlift strategies
29+ -- * Unlift strategies
3030 , UnliftStrategy(..)
3131 , Persistence(..)
3232 , Limit(..)
@@ -34,29 +34,24 @@ module Effectful.Internal.Monad
3434 , withUnliftStrategy
3535 , withEffToIO
3636
37− --- *** Low-level helpers
37+ -- ** Low-level unlifts
3838 , seqUnliftIO
3939 , concUnliftIO
4040
4141 -- * Effects
4242
43− -- ** Handler
43+ -- ** Dynamic dispatch
4444 , EffectHandler
4545 , LocalEnv(..)
4646 , HandlerA(..)
4747 , runHandler
48−
49− -- *** Sending operations
5048 , send
5149
52− -- ** Primitive
53−
54− -- *** Running
50+ -- ** Static dispatch
51+ , DataA(..)
5552 , runData
5653 , evalData
5754 , execData
58−
59− -- *** Modification
6055 , getData
6156 , putData
6257 , stateData
@@ -92,17 +87,16 @@ type role Eff nominal representational
9287-- would have the following type:
9388--
9489-- @
95−-- 'Eff' '['Effectful.Reader.Reader' 'String', 'Effectful.State.State' 'Bool'] 'Integer'
90+-- 'Eff' '['Effectful.Reader.Reader' 'String', 'Effectful.State.Local.State' 'Bool'] 'Integer'
9691-- @
9792--
9893-- Normally, a concrete list of effects is not used to parameterize 'Eff'.
9994-- Instead, the '(:>)' type class is used to express constraints on the list of
10095-- effects without coupling a computation to a concrete list of effects. For
101−-- example, the above example would more commonly be expressed with the
102−-- following type:
96+-- example, the above example would be expressed with the following type:
10397--
10498-- @
105−-- ('Effectful.Reader.Reader' 'String' ':>' es, 'Effectful.State.State' 'Bool' ':>' es) => 'Eff' es 'Integer'
99+-- ('Effectful.Reader.Reader' 'String' ':>' es, 'Effectful.State.Local.State' 'Bool' ':>' es) => 'Eff' es 'Integer'
106100-- @
107101--
108102-- This abstraction allows the computation to be used in functions that may
@@ -116,12 +110,12 @@ newtype Eff (es :: [Effect]) a = Eff (Env es -> IO a)
116110-- For running computations with side effects see 'runEff'.
117111runPureEff :: Eff '[] a -> a
118112runPureEff (Eff m) =
119− -- unsafePerformIO is safe here since IOE was not on the stack, so no IO with
120− -- side effects was performed (unless someone sneakily introduced side effects
121− -- with unsafeEff, but then all bets are off).
113+ -- unsafeDupablePerformIO is safe here since IOE was not on the stack, so no
114+ -- IO with side effects was performed (unless someone sneakily introduced side
115+ -- effects with unsafeEff, but then all bets are off).
122116 --
123117 -- Moreover, internals don't allocate any resources that require explicit
124− -- cleanup actions to run, so the "Dupable" part should also be just fine.
118+ -- cleanup actions to run.
125119 unsafeDupablePerformIO $ m =<< emptyEnv
126120
127121----------------------------------------
@@ -164,7 +158,7 @@ withUnliftStrategy unlift = localData $ \_ -> DataA (IOE unlift)
164158-- constraint for accurate stack traces in case an insufficiently powerful
165159-- 'UnliftStrategy' is used and the unlifting function fails.
166160--
167−-- /Note:/ the strategy is reset to 'SeqUnlift' for new threads.
161+-- /Note:/ the strategy is reset to 'SeqUnlift' inside the continuation.
168162withEffToIO
169163 :: (HasCallStack, IOE :> es)
170164 => ((forall r. Eff es r -> IO r) -> IO a)
@@ -309,7 +303,7 @@ instance Prim :> es => PrimMonad (Eff es) where
309303 primitive = unsafeEff_ . IO
310304
311305----------------------------------------
312−-- Handler
306+-- Dynamic dispatch
313307
314308type role LocalEnv nominal nominal
315309
@@ -333,11 +327,11 @@ type EffectHandler e es
333327
334328-- | An adapter for dynamically dispatched effects.
335329--
336−-- Represents the effect handler bundled along with its environment.
330+-- Represents the effect handler bundled with its environment.
337331data HandlerA :: Effect -> Type where
338332 HandlerA :: !(Env es) -> !(EffectHandler e es) -> HandlerA e
339333
340−-- | Run the effect with the given handler.
334+-- | Run a dynamically dispatched effect with the given handler.
341335runHandler :: HandlerA e -> Eff (e : es) a -> Eff es a
342336runHandler e m = unsafeEff $ \es0 -> do
343337 size0 <- sizeEnv es0
@@ -357,8 +351,17 @@ send op = unsafeEff $ \es -> do
357351 unEff (handle (LocalEnv es) op) handlerEs
358352
359353----------------------------------------
360−-- Helpers
354+-- Static dispatch
355+
356+-- | An adapter for statically dispatched effects.
357+--
358+-- Represents an arbitrary data type with the appropriate number of phantom type
359+-- parameters.
360+newtype DataA :: Effect -> Type where
361+ DataA :: (forall m r. e m r) -> DataA e
361362
363+-- | Run a statically dispatched effect with the given initial state and return
364+-- the final value along with the final state.
362365runData :: DataA e -> Eff (e : es) a -> Eff es (a, DataA e)
363366runData e0 m = unsafeEff $ \es0 -> do
364367 size0 <- sizeEnv es0
@@ -366,6 +369,8 @@ runData e0 m = unsafeEff $ \es0 -> do
366369 (unsafeTailEnv size0)
367370 (\es -> (,) <$> unEff m es <*> getEnv es)
368371
372+-- | Run a statically dispatched effect with the given initial state and return
373+-- the final value, discarding the final state.
369374evalData :: DataA e -> Eff (e : es) a -> Eff es a
370375evalData e m = unsafeEff $ \es0 -> do
371376 size0 <- sizeEnv es0
@@ -373,6 +378,8 @@ evalData e m = unsafeEff $ \es0 -> do
373378 (unsafeTailEnv size0)
374379 (\es -> unEff m es)
375380
381+-- | Run a statically dispatched effect with the given initial state and return
382+-- the final state, discarding the final value.
376383execData :: DataA e -> Eff (e : es) a -> Eff es (DataA e)
377384execData e0 m = unsafeEff $ \es0 -> do
378385 size0 <- sizeEnv es0
@@ -380,21 +387,27 @@ execData e0 m = unsafeEff $ \es0 -> do
380387 (unsafeTailEnv size0)
381388 (\es -> unEff m es *> getEnv es)
382389
390+-- | Fetch the current state of the effect.
383391getData :: e :> es => Eff es (DataA e)
384392getData = unsafeEff $ \es -> getEnv es
385393
394+-- | Set the current state of the effect to the given value.
386395putData :: e :> es => DataA e -> Eff es ()
387396putData e = unsafeEff $ \es -> putEnv es e
388397
398+-- | Apply the function to the current state of the effect and return a value.
389399stateData :: e :> es => (DataA e -> (a, DataA e)) -> Eff es a
390400stateData f = unsafeEff $ \es -> stateEnv es f
391401
402+-- | Apply the monadic function to the current state of the effect and return a
403+-- value.
392404stateDataM :: e :> es => (DataA e -> Eff es (a, DataA e)) -> Eff es a
393405stateDataM f = unsafeEff $ \es -> E.mask $ \release -> do
394406 (a, e) <- (\e -> release $ unEff (f e) es) =<< getEnv es
395407 putEnv es e
396408 pure a
397409
410+-- | Execute a computation with a temporarily modified state of the effect.
398411localData :: e :> es => (DataA e -> DataA e) -> Eff es a -> Eff es a
399412localData f m = unsafeEff $ \es -> do
400413 E.bracket (stateEnv es $ \e -> (e, f e))