@@ -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,47 +22,41 @@ 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(..)
3333 , unliftStrategy
3434 , withUnliftStrategy
3535 , withEffToIO
36− , UnliftError(..)
3736
38− --- *** Low-level helpers
37+ -- ** Low-level unlifts
3938 , seqUnliftIO
4039 , concUnliftIO
4140
4241 -- * Effects
4342
44− -- ** Handler
43+ -- ** Dynamic dispatch
4544 , EffectHandler
4645 , LocalEnv(..)
47− , Handler(..)
46+ , HandlerA(..)
4847 , runHandler
49−
50− -- *** Sending operations
5148 , send
5249
53− -- ** Primitive
54−
55− -- *** Running
56− , runEffect
57− , evalEffect
58− , execEffect
59−
60− -- *** Modification
61− , getEffect
62− , putEffect
63− , stateEffect
64− , stateEffectM
65− , localEffect
50+ -- ** Static dispatch
51+ , DataA(..)
52+ , runData
53+ , evalData
54+ , execData
55+ , getData
56+ , putData
57+ , stateData
58+ , stateDataM
59+ , localData
6660 ) where
6761
6862import Control.Applicative (liftA2)
@@ -85,44 +79,43 @@ import Effectful.Internal.Unlift
8579
8680type role Eff nominal representational
8781
88−-- | The 'Eff' monad provides the implementation of an operation that performs
82+-- | The 'Eff' monad provides the implementation of a computation that performs
8983-- an arbitrary set of effects. In @'Eff' es a@, @es@ is a type-level list that
90−-- contains all the effects that the operation may perform. For example, an
91−-- operation that produces an 'Integer' by consuming a 'String' from the global
92−-- environment and acting upon a single mutable cell containing a 'Bool' would
93−-- have the following type:
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:
9488--
9589-- @
96−-- 'Eff' '['Effectful.Reader.Reader' 'String', 'Effectful.State.State' 'Bool'] 'Integer'
90+-- 'Eff' '['Effectful.Reader.Reader' 'String', 'Effectful.State.Local.State' 'Bool'] 'Integer'
9791-- @
9892--
9993-- Normally, a concrete list of effects is not used to parameterize 'Eff'.
10094-- Instead, the '(:>)' type class is used to express constraints on the list of
101−-- effects without coupling an operation to a concrete list of effects. For
102−-- example, the above example would more commonly be expressed with the
103−-- following type:
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:
10497--
10598-- @
106−-- ('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'
107100-- @
108101--
109−-- This abstraction allows the operation to be used in functions that may
102+-- This abstraction allows the computation to be used in functions that may
110103-- perform other effects, and it also allows the effects to be handled in any
111104-- order.
112105newtype Eff (es :: [Effect]) a = Eff (Env es -> IO a)
113106 deriving (Monoid, Semigroup)
114107
115−-- | Run a pure 'Eff' operation.
108+-- | Run a pure 'Eff' computation.
116109--
117−-- For running operations with side effects see 'runEff'.
110+-- For running computations with side effects see 'runEff'.
118111runPureEff :: Eff '[] a -> a
119112runPureEff (Eff m) =
120− -- unsafePerformIO is safe here since IOE was not on the stack, so no IO with
121− -- side effects was performed (unless someone sneakily introduced side effects
122− -- 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).
123116 --
124117 -- Moreover, internals don't allocate any resources that require explicit
125− -- cleanup actions to run, so the "Dupable" part should also be just fine.
118+ -- cleanup actions to run.
126119 unsafeDupablePerformIO $ m =<< emptyEnv
127120
128121----------------------------------------
@@ -135,14 +128,14 @@ unEff (Eff m) = m
135128-- | Access the underlying 'IO' monad along with the environment.
136129--
137130-- This function is __unsafe__ because it can be used to introduce arbitrary
138−-- 'IO' actions into pure 'Eff' operations.
131+-- 'IO' actions into pure 'Eff' computations.
139132unsafeEff :: (Env es -> IO a) -> Eff es a
140133unsafeEff m = Eff (oneShot m)
141134
142135-- | Access the underlying 'IO' monad.
143136--
144137-- This function is __unsafe__ because it can be used to introduce arbitrary
145−-- 'IO' actions into pure 'Eff' operations.
138+-- 'IO' actions into pure 'Eff' computations.
146139unsafeEff_ :: IO a -> Eff es a
147140unsafeEff_ m = unsafeEff $ \_ -> m
148141
@@ -152,12 +145,12 @@ unsafeEff_ m = unsafeEff $ \_ -> m
152145-- | Get the current 'UnliftStrategy'.
153146unliftStrategy :: IOE :> es => Eff es UnliftStrategy
154147unliftStrategy = do
155− IdE (IOE unlift) <- getEffect
148+ DataA (IOE unlift) <- getData
156149 pure unlift
157150
158151-- | Locally override the 'UnliftStrategy' with the given value.
159152withUnliftStrategy :: IOE :> es => UnliftStrategy -> Eff es a -> Eff es a
160−withUnliftStrategy unlift = localEffect $ \_ -> IdE (IOE unlift)
153+withUnliftStrategy unlift = localData $ \_ -> DataA (IOE unlift)
161154
162155-- | Create an unlifting function with the current 'UnliftStrategy'.
163156--
@@ -165,7 +158,7 @@ withUnliftStrategy unlift = localEffect $ \_ -> IdE (IOE unlift)
165158-- constraint for accurate stack traces in case an insufficiently powerful
166159-- 'UnliftStrategy' is used and the unlifting function fails.
167160--
168−-- /Note:/ the strategy is reset to 'SeqUnlift' for new threads.
161+-- /Note:/ the strategy is reset to 'SeqUnlift' inside the continuation.
169162withEffToIO
170163 :: (HasCallStack, IOE :> es)
171164 => ((forall r. Eff es r -> IO r) -> IO a)
@@ -176,25 +169,25 @@ withEffToIO f = unliftStrategy >>= \case
176169 ConcUnlift p b -> withUnliftStrategy SeqUnlift $ do
177170 unsafeEff $ \es -> concUnliftIO es p b f
178171
179−-- | Lower 'Eff' operations into 'IO' ('SeqUnlift').
180−--
181−-- Exceptions thrown by this function:
182−--
183−-- - 'InvalidUseOfSeqUnlift' if the unlift function is used in another thread.
172+-- | Create an unlifting function with the 'SeqUnlift' strategy.
184173seqUnliftIO
185174 :: HasCallStack
186175 => Env es
176+ -- ^ The environment.
187177 -> ((forall r. Eff es r -> IO r) -> IO a)
178+ -- ^ Continuation with the unlifting function in scope.
188179 -> IO a
189180seqUnliftIO es k = seqUnlift k es unEff
190181
191−-- | Lower 'Eff' operations into 'IO' ('ConcUnlift').
182+-- | Create an unlifting function with the 'ConcUnlift' strategy.
192183concUnliftIO
193184 :: HasCallStack
194185 => Env es
186+ -- ^ The environment.
195187 -> Persistence
196188 -> Limit
197189 -> ((forall r. Eff es r -> IO r) -> IO a)
190+ -- ^ Continuation with the unlifting function in scope.
198191 -> IO a
199192concUnliftIO es persistence limit k = concUnlift persistence limit k es unEff
200193
@@ -265,15 +258,15 @@ instance Fail :> es => MonadFail (Eff es) where
265258----------------------------------------
266259-- IO
267260
268−-- | Run arbitrary 'IO' operations via 'MonadIO' or 'MonadUnliftIO'.
261+-- | Run arbitrary 'IO' computations via 'MonadIO' or 'MonadUnliftIO'.
269262newtype IOE :: Effect where
270263 IOE :: UnliftStrategy -> IOE m r
271264
272−-- | Run an 'Eff' operation with side effects.
265+-- | Run an 'Eff' computation with side effects.
273266--
274−-- For running pure operations see 'runPureEff'.
267+-- For running pure computations see 'runPureEff'.
275268runEff :: Eff '[IOE] a -> IO a
276−runEff m = unEff (evalEffect (IdE (IOE SeqUnlift)) m) =<< emptyEnv
269+runEff m = unEff (evalData (DataA (IOE SeqUnlift)) m) =<< emptyEnv
277270
278271instance IOE :> es => MonadIO (Eff es) where
279272 liftIO = unsafeEff_
@@ -297,20 +290,20 @@ instance IOE :> es => MonadBaseControl IO (Eff es) where
297290----------------------------------------
298291-- Primitive
299292
300−-- | An effect to perform primitive state-transformer actions.
293+-- | Provide the ability to perform primitive state-transformer actions.
301294data Prim :: Effect where
302295 Prim :: Prim m r
303296
304−-- | Run an 'Eff' operation with primitive state-transformer actions.
297+-- | Run an 'Eff' computation with primitive state-transformer actions.
305298runPrim :: IOE :> es => Eff (Prim : es) a -> Eff es a
306−runPrim = evalEffect (IdE Prim)
299+runPrim = evalData (DataA Prim)
307300
308301instance Prim :> es => PrimMonad (Eff es) where
309302 type PrimState (Eff es) = RealWorld
310303 primitive = unsafeEff_ . IO
311304
312305----------------------------------------
313−-- Handler
306+-- Dynamic dispatch
314307
315308type role LocalEnv nominal nominal
316309
@@ -326,78 +319,97 @@ newtype LocalEnv (localEs :: [Effect]) (handlerEs :: [Effect]) = LocalEnv (Env l
326319type EffectHandler e es
327320 = forall a localEs. HasCallStack
328321 => LocalEnv localEs es
329− -- ^ Capture of the local environment for handling local 'Eff' operations when
330− -- @e@ is a higher order effect.
322+ -- ^ Capture of the local environment for handling local 'Eff' computations
323+ -- when @e@ is a higher order effect.
331324 -> e (Eff localEs) a
332325 -- ^ The effect performed in the local environment.
333326 -> Eff es a
334327
335328-- | An adapter for dynamically dispatched effects.
336329--
337−-- Represents the effect handler bundled along with its environment.
338−data Handler :: Effect -> Type where
339− Handler :: !(Env es) -> !(EffectHandler e es) -> Handler e
330+-- Represents the effect handler bundled with its environment.
331+data HandlerA :: Effect -> Type where
332+ HandlerA :: !(Env es) -> !(EffectHandler e es) -> HandlerA e
340333
341−-- | Run the effect with the given handler.
342−runHandler :: Handler e -> Eff (e : es) a -> Eff es a
334+-- | Run a dynamically dispatched effect with the given handler.
335+runHandler :: HandlerA e -> Eff (e : es) a -> Eff es a
343336runHandler e m = unsafeEff $ \es0 -> do
344337 size0 <- sizeEnv es0
345338 E.bracket (unsafeConsEnv e relinker es0)
346339 (unsafeTailEnv size0)
347340 (\es -> unEff m es)
348341 where
349− relinker :: Relinker Handler e
350− relinker = Relinker $ \relink (Handler env handle) -> do
351− newEnv <- relink env
352− pure $ Handler newEnv handle
342+ relinker :: Relinker HandlerA e
343+ relinker = Relinker $ \relink (HandlerA handlerEs handle) -> do
344+ newHandlerEs <- relink handlerEs
345+ pure $ HandlerA newHandlerEs handle
353346
354347-- | Send an operation of the given effect to its handler for execution.
355348send :: (HasCallStack, e :> es) => e (Eff es) a -> Eff es a
356349send op = unsafeEff $ \es -> do
357− Handler handlerEs handle <- getEnv es
350+ HandlerA handlerEs handle <- getEnv es
358351 unEff (handle (LocalEnv es) op) handlerEs
359352
360353----------------------------------------
361−-- Helpers
354+-- Static dispatch
362355
363−runEffect :: adapter e -> Eff (e : es) a -> Eff es (a, adapter e)
364−runEffect e0 m = unsafeEff $ \es0 -> do
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
365367 size0 <- sizeEnv es0
366368 E.bracket (unsafeConsEnv e0 noRelinker es0)
367369 (unsafeTailEnv size0)
368370 (\es -> (,) <$> unEff m es <*> getEnv es)
369371
370−evalEffect :: adapter e -> Eff (e : es) a -> Eff es a
371−evalEffect e m = unsafeEff $ \es0 -> do
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
372376 size0 <- sizeEnv es0
373377 E.bracket (unsafeConsEnv e noRelinker es0)
374378 (unsafeTailEnv size0)
375379 (\es -> unEff m es)
376380
377−execEffect :: adapter e -> Eff (e : es) a -> Eff es (adapter e)
378−execEffect e0 m = unsafeEff $ \es0 -> do
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
379385 size0 <- sizeEnv es0
380386 E.bracket (unsafeConsEnv e0 noRelinker es0)
381387 (unsafeTailEnv size0)
382388 (\es -> unEff m es *> getEnv es)
383389
384−getEffect :: e :> es => Eff es (adapter e)
385−getEffect = unsafeEff $ \es -> getEnv es
390+-- | Fetch the current state of the effect.
391+getData :: e :> es => Eff es (DataA e)
392+getData = unsafeEff $ \es -> getEnv es
386393
387−putEffect :: e :> es => adapter e -> Eff es ()
388−putEffect e = unsafeEff $ \es -> putEnv es e
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
389397
390−stateEffect :: e :> es => (adapter e -> (a, adapter e)) -> Eff es a
391−stateEffect f = unsafeEff $ \es -> stateEnv es f
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
392401
393−stateEffectM :: e :> es => (adapter e -> Eff es (a, adapter e)) -> Eff es a
394−stateEffectM f = unsafeEff $ \es -> E.mask $ \release -> do
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
395406 (a, e) <- (\e -> release $ unEff (f e) es) =<< getEnv es
396407 putEnv es e
397408 pure a
398409
399−localEffect :: e :> es => (adapter e -> adapter e) -> Eff es a -> Eff es a
400−localEffect f m = unsafeEff $ \es -> do
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
401413 E.bracket (stateEnv es $ \e -> (e, f e))
402414 (\e -> putEnv es e)
403415 (\_ -> unEff m es)