@@ -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− ( -- * The 'Eff' monad
9+ ( -- * Monad
1010 Eff
1111 , runPureEff
1212
@@ -22,11 +22,11 @@ module Effectful.Internal.Monad
2222 , IOE
2323 , runEff
2424
25− -- * Prim
25+ -- * Primitive
2626 , Prim
2727 , runPrim
2828
29− -- * Unlift strategies
29+ -- ** Unlift strategies
3030 , UnliftStrategy(..)
3131 , Persistence(..)
3232 , Limit(..)
@@ -34,29 +34,34 @@ module Effectful.Internal.Monad
3434 , withUnliftStrategy
3535 , withEffToIO
3636
37− -- ** Low-level unlifts
37+ --- *** Low-level helpers
3838 , seqUnliftIO
3939 , concUnliftIO
4040
4141 -- * Effects
4242
43− -- ** Dynamic dispatch
43+ -- ** Handler
4444 , EffectHandler
4545 , LocalEnv(..)
46− , HandlerA(..)
46+ , Handler(..)
4747 , runHandler
48+
49+ -- *** Sending operations
4850 , send
4951
50− -- ** Static dispatch
51− , DataA(..)
52− , runData
53− , evalData
54− , execData
55− , getData
56− , putData
57− , stateData
58− , stateDataM
59− , localData
52+ -- ** Primitive
53+
54+ -- *** Running
55+ , runEffect
56+ , evalEffect
57+ , execEffect
58+
59+ -- *** Modification
60+ , getEffect
61+ , putEffect
62+ , stateEffect
63+ , stateEffectM
64+ , localEffect
6065 ) where
6166
6267import Control.Applicative (liftA2)
@@ -79,43 +84,44 @@ import Effectful.Internal.Unlift
7984
8085type role Eff nominal representational
8186
82−-- | The 'Eff' monad provides the implementation of a computation that performs
87+-- | The 'Eff' monad provides the implementation of an operation that performs
8388-- an arbitrary set of effects. In @'Eff' es a@, @es@ is a type-level list that
84−-- contains all the effects that the computation may perform. For example, a
85−-- computation that produces an 'Integer' by consuming a 'String' from the
86−-- global environment and acting upon a single mutable value of type 'Bool'
87−-- would have the following type:
89+-- contains all the effects that the operation may perform. For example, an
90+-- operation that produces an 'Integer' by consuming a 'String' from the global
91+-- environment and acting upon a single mutable value of type 'Bool' would have
92+-- the following type:
8893--
8994-- @
90−-- 'Eff' '['Effectful.Reader.Reader' 'String', 'Effectful.State.Local.State' 'Bool'] 'Integer'
95+-- 'Eff' '['Effectful.Reader.Reader' 'String', 'Effectful.State.State' 'Bool'] 'Integer'
9196-- @
9297--
9398-- Normally, a concrete list of effects is not used to parameterize 'Eff'.
9499-- 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
96−-- example, the above example would be expressed with the following type:
100+-- effects without coupling an operation to a concrete list of effects. For
101+-- example, the above example would more commonly be expressed with the
102+-- following type:
97103--
98104-- @
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'
100106-- @
101107--
102−-- This abstraction allows the computation to be used in functions that may
108+-- This abstraction allows the operation to be used in functions that may
103109-- perform other effects, and it also allows the effects to be handled in any
104110-- order.
105111newtype Eff (es :: [Effect]) a = Eff (Env es -> IO a)
106112 deriving (Monoid, Semigroup)
107113
108−-- | Run a pure 'Eff' computation.
114+-- | Run a pure 'Eff' operation.
109115--
110−-- For running computations with side effects see 'runEff'.
116+-- For running operations with side effects see 'runEff'.
111117runPureEff :: Eff '[] a -> a
112118runPureEff (Eff m) =
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).
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).
116122 --
117123 -- 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.
119125 unsafeDupablePerformIO $ m =<< emptyEnv
120126
121127----------------------------------------
@@ -128,14 +134,14 @@ unEff (Eff m) = m
128134-- | Access the underlying 'IO' monad along with the environment.
129135--
130136-- This function is __unsafe__ because it can be used to introduce arbitrary
131−-- 'IO' actions into pure 'Eff' computations.
137+-- 'IO' actions into pure 'Eff' operations.
132138unsafeEff :: (Env es -> IO a) -> Eff es a
133139unsafeEff m = Eff (oneShot m)
134140
135141-- | Access the underlying 'IO' monad.
136142--
137143-- This function is __unsafe__ because it can be used to introduce arbitrary
138−-- 'IO' actions into pure 'Eff' computations.
144+-- 'IO' actions into pure 'Eff' operations.
139145unsafeEff_ :: IO a -> Eff es a
140146unsafeEff_ m = unsafeEff $ \_ -> m
141147
@@ -145,12 +151,12 @@ unsafeEff_ m = unsafeEff $ \_ -> m
145151-- | Get the current 'UnliftStrategy'.
146152unliftStrategy :: IOE :> es => Eff es UnliftStrategy
147153unliftStrategy = do
148− DataA (IOE unlift) <- getData
154+ IdE (IOE unlift) <- getEffect
149155 pure unlift
150156
151157-- | Locally override the 'UnliftStrategy' with the given value.
152158withUnliftStrategy :: IOE :> es => UnliftStrategy -> Eff es a -> Eff es a
153−withUnliftStrategy unlift = localData $ \_ -> DataA (IOE unlift)
159+withUnliftStrategy unlift = localEffect $ \_ -> IdE (IOE unlift)
154160
155161-- | Create an unlifting function with the current 'UnliftStrategy'.
156162--
@@ -158,7 +164,7 @@ withUnliftStrategy unlift = localData $ \_ -> DataA (IOE unlift)
158164-- constraint for accurate stack traces in case an insufficiently powerful
159165-- 'UnliftStrategy' is used and the unlifting function fails.
160166--
161−-- /Note:/ the strategy is reset to 'SeqUnlift' inside the continuation.
167+-- /Note:/ the strategy is reset to 'SeqUnlift' for new threads.
162168withEffToIO
163169 :: (HasCallStack, IOE :> es)
164170 => ((forall r. Eff es r -> IO r) -> IO a)
@@ -258,15 +264,15 @@ instance Fail :> es => MonadFail (Eff es) where
258264----------------------------------------
259265-- IO
260266
261−-- | Run arbitrary 'IO' computations via 'MonadIO' or 'MonadUnliftIO'.
267+-- | Run arbitrary 'IO' operations via 'MonadIO' or 'MonadUnliftIO'.
262268newtype IOE :: Effect where
263269 IOE :: UnliftStrategy -> IOE m r
264270
265−-- | Run an 'Eff' computation with side effects.
271+-- | Run an 'Eff' operation with side effects.
266272--
267−-- For running pure computations see 'runPureEff'.
273+-- For running pure operations see 'runPureEff'.
268274runEff :: Eff '[IOE] a -> IO a
269−runEff m = unEff (evalData (DataA (IOE SeqUnlift)) m) =<< emptyEnv
275+runEff m = unEff (evalEffect (IdE (IOE SeqUnlift)) m) =<< emptyEnv
270276
271277instance IOE :> es => MonadIO (Eff es) where
272278 liftIO = unsafeEff_
@@ -294,16 +300,16 @@ instance IOE :> es => MonadBaseControl IO (Eff es) where
294300data Prim :: Effect where
295301 Prim :: Prim m r
296302
297−-- | Run an 'Eff' computation with primitive state-transformer actions.
303+-- | Run an 'Eff' operation with primitive state-transformer actions.
298304runPrim :: IOE :> es => Eff (Prim : es) a -> Eff es a
299−runPrim = evalData (DataA Prim)
305+runPrim = evalEffect (IdE Prim)
300306
301307instance Prim :> es => PrimMonad (Eff es) where
302308 type PrimState (Eff es) = RealWorld
303309 primitive = unsafeEff_ . IO
304310
305311----------------------------------------
306−-- Dynamic dispatch
312+-- Handler
307313
308314type role LocalEnv nominal nominal
309315
@@ -319,97 +325,78 @@ newtype LocalEnv (localEs :: [Effect]) (handlerEs :: [Effect]) = LocalEnv (Env l
319325type EffectHandler e es
320326 = forall a localEs. HasCallStack
321327 => LocalEnv localEs es
322− -- ^ Capture of the local environment for handling local 'Eff' computations
323− -- when @e@ is a higher order effect.
328+ -- ^ Capture of the local environment for handling local 'Eff' operations when
329+ -- @e@ is a higher order effect.
324330 -> e (Eff localEs) a
325331 -- ^ The effect performed in the local environment.
326332 -> Eff es a
327333
328334-- | An adapter for dynamically dispatched effects.
329335--
330−-- Represents the effect handler bundled with its environment.
331−data HandlerA :: Effect -> Type where
332− HandlerA :: !(Env es) -> !(EffectHandler e es) -> HandlerA e
336+-- Represents the effect handler bundled along with its environment.
337+data Handler :: Effect -> Type where
338+ Handler :: !(Env es) -> !(EffectHandler e es) -> Handler e
333339
334−-- | Run a dynamically dispatched effect with the given handler.
335−runHandler :: HandlerA e -> Eff (e : es) a -> Eff es a
340+-- | Run the effect with the given handler.
341+runHandler :: Handler e -> Eff (e : es) a -> Eff es a
336342runHandler e m = unsafeEff $ \es0 -> do
337343 size0 <- sizeEnv es0
338344 E.bracket (unsafeConsEnv e relinker es0)
339345 (unsafeTailEnv size0)
340346 (\es -> unEff m es)
341347 where
342− relinker :: Relinker HandlerA e
343− relinker = Relinker $ \relink (HandlerA handlerEs handle) -> do
348+ relinker :: Relinker Handler e
349+ relinker = Relinker $ \relink (Handler handlerEs handle) -> do
344350 newHandlerEs <- relink handlerEs
345− pure $ HandlerA newHandlerEs handle
351+ pure $ Handler newHandlerEs handle
346352
347353-- | Send an operation of the given effect to its handler for execution.
348354send :: (HasCallStack, e :> es) => e (Eff es) a -> Eff es a
349355send op = unsafeEff $ \es -> do
350− HandlerA handlerEs handle <- getEnv es
356+ Handler handlerEs handle <- getEnv es
351357 unEff (handle (LocalEnv es) op) handlerEs
352358
353359----------------------------------------
354−-- Static dispatch
360+-- Helpers
355361
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
362−
363−-- | Run a statically dispatched effect with the given initial state and return
364−-- the final value along with the final state.
365−runData :: DataA e -> Eff (e : es) a -> Eff es (a, DataA e)
366−runData e0 m = unsafeEff $ \es0 -> do
362+runEffect :: adapter e -> Eff (e : es) a -> Eff es (a, adapter e)
363+runEffect e0 m = unsafeEff $ \es0 -> do
367364 size0 <- sizeEnv es0
368365 E.bracket (unsafeConsEnv e0 noRelinker es0)
369366 (unsafeTailEnv size0)
370367 (\es -> (,) <$> unEff m es <*> getEnv es)
371368
372−-- | Run a statically dispatched effect with the given initial state and return
373−-- the final value, discarding the final state.
374−evalData :: DataA e -> Eff (e : es) a -> Eff es a
375−evalData e m = unsafeEff $ \es0 -> do
369+evalEffect :: adapter e -> Eff (e : es) a -> Eff es a
370+evalEffect e m = unsafeEff $ \es0 -> do
376371 size0 <- sizeEnv es0
377372 E.bracket (unsafeConsEnv e noRelinker es0)
378373 (unsafeTailEnv size0)
379374 (\es -> unEff m es)
380375
381−-- | Run a statically dispatched effect with the given initial state and return
382−-- the final state, discarding the final value.
383−execData :: DataA e -> Eff (e : es) a -> Eff es (DataA e)
384−execData e0 m = unsafeEff $ \es0 -> do
376+execEffect :: adapter e -> Eff (e : es) a -> Eff es (adapter e)
377+execEffect e0 m = unsafeEff $ \es0 -> do
385378 size0 <- sizeEnv es0
386379 E.bracket (unsafeConsEnv e0 noRelinker es0)
387380 (unsafeTailEnv size0)
388381 (\es -> unEff m es *> getEnv es)
389382
390−-- | Fetch the current state of the effect.
391−getData :: e :> es => Eff es (DataA e)
392−getData = unsafeEff $ \es -> getEnv es
383+getEffect :: e :> es => Eff es (adapter e)
384+getEffect = unsafeEff $ \es -> getEnv es
393385
394−-- | Set the current state of the effect to the given value.
395−putData :: e :> es => DataA e -> Eff es ()
396−putData e = unsafeEff $ \es -> putEnv es e
386+putEffect :: e :> es => adapter e -> Eff es ()
387+putEffect e = unsafeEff $ \es -> putEnv es e
397388
398−-- | Apply the function to the current state of the effect and return a value.
399−stateData :: e :> es => (DataA e -> (a, DataA e)) -> Eff es a
400−stateData f = unsafeEff $ \es -> stateEnv es f
389+stateEffect :: e :> es => (adapter e -> (a, adapter e)) -> Eff es a
390+stateEffect f = unsafeEff $ \es -> stateEnv es f
401391
402−-- | Apply the monadic function to the current state of the effect and return a
403−-- value.
404−stateDataM :: e :> es => (DataA e -> Eff es (a, DataA e)) -> Eff es a
405−stateDataM f = unsafeEff $ \es -> E.mask $ \release -> do
392+stateEffectM :: e :> es => (adapter e -> Eff es (a, adapter e)) -> Eff es a
393+stateEffectM f = unsafeEff $ \es -> E.mask $ \release -> do
406394 (a, e) <- (\e -> release $ unEff (f e) es) =<< getEnv es
407395 putEnv es e
408396 pure a
409397
410−-- | Execute a computation with a temporarily modified state of the effect.
411−localData :: e :> es => (DataA e -> DataA e) -> Eff es a -> Eff es a
412−localData f m = unsafeEff $ \es -> do
398+localEffect :: e :> es => (adapter e -> adapter e) -> Eff es a -> Eff es a
399+localEffect f m = unsafeEff $ \es -> do
413400 E.bracket (stateEnv es $ \e -> (e, f e))
414401 (\e -> putEnv es e)
415402 (\_ -> unEff m es)