@@ -6,7 +6,7 @@
6-- This module is intended for internal use only, and may change without warning
6-- This module is intended for internal use only, and may change without warning
7-- in subsequent releases.
7-- in subsequent releases.
8module Effectful.Internal.Monad
8module Effectful.Internal.Monad
9− ( -- * The 'Eff' monad
9+ ( -- * Monad
11 , runPureEff
11 , runPureEff
@@ -22,11 +22,11 @@ module Effectful.Internal.Monad
25− -- * Prim
25+ -- * Primitive
29− -- * Unlift strategies
29+ -- ** Unlift strategies
30 , UnliftStrategy(..)
30 , UnliftStrategy(..)
31 , Persistence(..)
31 , Persistence(..)
32 , Limit(..)
32 , Limit(..)
@@ -34,24 +34,29 @@ module Effectful.Internal.Monad
34 , withUnliftStrategy
34 , withUnliftStrategy
35 , withEffToIO
35 , withEffToIO
37− -- ** Low-level unlifts
37+ --- *** Low-level helpers
38 , seqUnliftIO
38 , seqUnliftIO
39 , concUnliftIO
39 , concUnliftIO
41 -- * Effects
41 -- * Effects
43− -- ** Dynamic dispatch
43+ -- ** Handler
44 , EffectHandler
44 , EffectHandler
45 , LocalEnv(..)
45 , LocalEnv(..)
46 , HandlerA(..)
46 , HandlerA(..)
47 , runHandler
47 , runHandler
49+ -- *** Sending operations
50− -- ** Static dispatch
52+ -- ** Primitive
53 , evalData
56 , evalData
54 , execData
57 , execData
57 , stateData
62 , stateData
@@ -87,16 +92,17 @@ type role Eff nominal representational
87-- would have the following type:
92-- would have the following type:
90−-- 'Eff' '['Effectful.Reader.Reader' 'String', 'Effectful.State.Local.State' 'Bool'] 'Integer'
95+-- 'Eff' '['Effectful.Reader.Reader' 'String', 'Effectful.State.State' 'Bool'] 'Integer'
93-- Normally, a concrete list of effects is not used to parameterize 'Eff'.
98-- Normally, a concrete list of effects is not used to parameterize 'Eff'.
94-- Instead, the '(:>)' type class is used to express constraints on the list of
99-- Instead, the '(:>)' type class is used to express constraints on the list of
95-- effects without coupling a computation to a concrete list of effects. For
100-- effects without coupling a computation to a concrete list of effects. For
96−-- example, the above example would be expressed with the following type:
101+-- example, the above example would more commonly be expressed with the
99−-- ('Effectful.Reader.Reader' 'String' ':>' es, 'Effectful.State.Local.State' 'Bool' ':>' es) => 'Eff' es 'Integer'
105+-- ('Effectful.Reader.Reader' 'String' ':>' es, 'Effectful.State.State' 'Bool' ':>' es) => 'Eff' es 'Integer'
102-- This abstraction allows the computation to be used in functions that may
108-- This abstraction allows the computation to be used in functions that may
@@ -110,12 +116,12 @@ newtype Eff (es :: [Effect]) a = Eff (Env es -> IO a)
110-- For running computations with side effects see 'runEff'.
116-- For running computations with side effects see 'runEff'.
111runPureEff :: Eff '[] a -> a
117runPureEff :: Eff '[] a -> a
112runPureEff (Eff m) =
118runPureEff (Eff m) =
113− -- unsafeDupablePerformIO is safe here since IOE was not on the stack, so no
119+ -- unsafePerformIO is safe here since IOE was not on the stack, so no IO with
114− -- IO with side effects was performed (unless someone sneakily introduced side
120+ -- side effects was performed (unless someone sneakily introduced side effects
115− -- effects with unsafeEff, but then all bets are off).
121+ -- with unsafeEff, but then all bets are off).
117 -- Moreover, internals don't allocate any resources that require explicit
123 -- Moreover, internals don't allocate any resources that require explicit
118− -- cleanup actions to run.
124+ -- cleanup actions to run, so the "Dupable" part should also be just fine.
119 unsafeDupablePerformIO $ m =<< emptyEnv
125 unsafeDupablePerformIO $ m =<< emptyEnv
121----------------------------------------
127----------------------------------------
@@ -158,7 +164,7 @@ withUnliftStrategy unlift = localData $ \_ -> DataA (IOE unlift)
158-- constraint for accurate stack traces in case an insufficiently powerful
164-- constraint for accurate stack traces in case an insufficiently powerful
159-- 'UnliftStrategy' is used and the unlifting function fails.
165-- 'UnliftStrategy' is used and the unlifting function fails.
161−-- /Note:/ the strategy is reset to 'SeqUnlift' inside the continuation.
167+-- /Note:/ the strategy is reset to 'SeqUnlift' for new threads.
162withEffToIO
168withEffToIO
163 :: (HasCallStack, IOE :> es)
169 :: (HasCallStack, IOE :> es)
164 => ((forall r. Eff es r -> IO r) -> IO a)
170 => ((forall r. Eff es r -> IO r) -> IO a)
@@ -303,7 +309,7 @@ instance Prim :> es => PrimMonad (Eff es) where
303 primitive = unsafeEff_ . IO
309 primitive = unsafeEff_ . IO
305----------------------------------------
311----------------------------------------
306−-- Dynamic dispatch
312+-- Handler
308type role LocalEnv nominal nominal
314type role LocalEnv nominal nominal
@@ -327,11 +333,11 @@ type EffectHandler e es
328-- | An adapter for dynamically dispatched effects.
334-- | An adapter for dynamically dispatched effects.
330−-- Represents the effect handler bundled with its environment.
336+-- Represents the effect handler bundled along with its environment.
331data HandlerA :: Effect -> Type where
337data HandlerA :: Effect -> Type where
332 HandlerA :: !(Env es) -> !(EffectHandler e es) -> HandlerA e
338 HandlerA :: !(Env es) -> !(EffectHandler e es) -> HandlerA e
334−-- | Run a dynamically dispatched effect with the given handler.
340+-- | Run the effect with the given handler.
335runHandler :: HandlerA e -> Eff (e : es) a -> Eff es a
341runHandler :: HandlerA e -> Eff (e : es) a -> Eff es a
336runHandler e m = unsafeEff $ \es0 -> do
342runHandler e m = unsafeEff $ \es0 -> do
337 size0 <- sizeEnv es0
343 size0 <- sizeEnv es0
@@ -351,17 +357,8 @@ send op = unsafeEff $ \es -> do
351 unEff (handle (LocalEnv es) op) handlerEs
357 unEff (handle (LocalEnv es) op) handlerEs
353----------------------------------------
359----------------------------------------
354−-- Static dispatch
360+-- Helpers
356−-- | An adapter for statically dispatched effects.
358−-- Represents an arbitrary data type with the appropriate number of phantom type
360−newtype DataA :: Effect -> Type where
361− DataA :: (forall m r. e m r) -> DataA e
363−-- | Run a statically dispatched effect with the given initial state and return
364−-- the final value along with the final state.
365runData :: DataA e -> Eff (e : es) a -> Eff es (a, DataA e)
362runData :: DataA e -> Eff (e : es) a -> Eff es (a, DataA e)
366runData e0 m = unsafeEff $ \es0 -> do
363runData e0 m = unsafeEff $ \es0 -> do
367 size0 <- sizeEnv es0
364 size0 <- sizeEnv es0
@@ -369,8 +366,6 @@ runData e0 m = unsafeEff $ \es0 -> do
369 (unsafeTailEnv size0)
366 (unsafeTailEnv size0)
370 (\es -> (,) <$> unEff m es <*> getEnv es)
367 (\es -> (,) <$> unEff m es <*> getEnv es)
372−-- | Run a statically dispatched effect with the given initial state and return
373−-- the final value, discarding the final state.
374evalData :: DataA e -> Eff (e : es) a -> Eff es a
369evalData :: DataA e -> Eff (e : es) a -> Eff es a
375evalData e m = unsafeEff $ \es0 -> do
370evalData e m = unsafeEff $ \es0 -> do
376 size0 <- sizeEnv es0
371 size0 <- sizeEnv es0
@@ -378,8 +373,6 @@ evalData e m = unsafeEff $ \es0 -> do
378 (unsafeTailEnv size0)
373 (unsafeTailEnv size0)
379 (\es -> unEff m es)
374 (\es -> unEff m es)
381−-- | Run a statically dispatched effect with the given initial state and return
382−-- the final state, discarding the final value.
383execData :: DataA e -> Eff (e : es) a -> Eff es (DataA e)
376execData :: DataA e -> Eff (e : es) a -> Eff es (DataA e)
384execData e0 m = unsafeEff $ \es0 -> do
377execData e0 m = unsafeEff $ \es0 -> do
385 size0 <- sizeEnv es0
378 size0 <- sizeEnv es0
@@ -387,27 +380,21 @@ execData e0 m = unsafeEff $ \es0 -> do
387 (unsafeTailEnv size0)
380 (unsafeTailEnv size0)
388 (\es -> unEff m es *> getEnv es)
381 (\es -> unEff m es *> getEnv es)
390−-- | Fetch the current state of the effect.
391getData :: e :> es => Eff es (DataA e)
383getData :: e :> es => Eff es (DataA e)
392getData = unsafeEff $ \es -> getEnv es
384getData = unsafeEff $ \es -> getEnv es
394−-- | Set the current state of the effect to the given value.
395putData :: e :> es => DataA e -> Eff es ()
386putData :: e :> es => DataA e -> Eff es ()
396putData e = unsafeEff $ \es -> putEnv es e
387putData e = unsafeEff $ \es -> putEnv es e
398−-- | Apply the function to the current state of the effect and return a value.
399stateData :: e :> es => (DataA e -> (a, DataA e)) -> Eff es a
389stateData :: e :> es => (DataA e -> (a, DataA e)) -> Eff es a
400stateData f = unsafeEff $ \es -> stateEnv es f
390stateData f = unsafeEff $ \es -> stateEnv es f
402−-- | Apply the monadic function to the current state of the effect and return a
404stateDataM :: e :> es => (DataA e -> Eff es (a, DataA e)) -> Eff es a
392stateDataM :: e :> es => (DataA e -> Eff es (a, DataA e)) -> Eff es a
405stateDataM f = unsafeEff $ \es -> E.mask $ \release -> do
393stateDataM f = unsafeEff $ \es -> E.mask $ \release -> do
406 (a, e) <- (\e -> release $ unEff (f e) es) =<< getEnv es
394 (a, e) <- (\e -> release $ unEff (f e) es) =<< getEnv es
407 putEnv es e
395 putEnv es e
410−-- | Execute a computation with a temporarily modified state of the effect.
411localData :: e :> es => (DataA e -> DataA e) -> Eff es a -> Eff es a
398localData :: e :> es => (DataA e -> DataA e) -> Eff es a -> Eff es a
412localData f m = unsafeEff $ \es -> do
399localData f m = unsafeEff $ \es -> do
413 E.bracket (stateEnv es $ \e -> (e, f e))
400 E.bracket (stateEnv es $ \e -> (e, f e))