@@ -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,41 +22,48 @@ 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(..)
3333 , unliftStrategy
3434 , withUnliftStrategy
3535 , withEffToIO
36+ , UnliftError(..)
3637
37− -- ** Low-level unlifts
38− , seqUnliftIO
39− , concUnliftIO
38+ --- *** Low-level helpers
39+ , unsafeLiftMapIO
40+ , seqUnliftEff
41+ , concUnliftEff
4042
4143 -- * Effects
4244
43− -- ** Dynamic dispatch
45+ -- ** Handler
4446 , EffectHandler
4547 , LocalEnv(..)
46− , HandlerA(..)
48+ , Handler(..)
4749 , runHandler
50+
51+ -- *** Sending operations
4852 , send
4953
50− -- ** Static dispatch
51− , DataA(..)
52− , runData
53− , evalData
54− , execData
55− , getData
56− , putData
57− , stateData
58− , stateDataM
59− , localData
54+ -- ** Primitive
55+
56+ -- *** Running
57+ , runEffect
58+ , evalEffect
59+ , execEffect
60+
61+ -- *** Modification
62+ , getEffect
63+ , putEffect
64+ , stateEffect
65+ , stateEffectM
66+ , localEffect
6067 ) where
6168
6269import Control.Applicative (liftA2)
@@ -79,43 +86,44 @@ import Effectful.Internal.Unlift
7986
8087type role Eff nominal representational
8188
82−-- | The 'Eff' monad provides the implementation of a computation that performs
89+-- | The 'Eff' monad provides the implementation of an operation that performs
8390-- 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:
91+-- contains all the effects that the operation may perform. For example, an
92+-- operation that produces an 'Integer' by consuming a 'String' from the global
93+-- environment and acting upon a single mutable cell containing a 'Bool' would
94+-- have the following type:
8895--
8996-- @
90−-- 'Eff' '['Effectful.Reader.Reader' 'String', 'Effectful.State.Local.State' 'Bool'] 'Integer'
97+-- 'Eff' '['Effectful.Reader.Reader' 'String', 'Effectful.State.State' 'Bool'] 'Integer'
9198-- @
9299--
93100-- Normally, a concrete list of effects is not used to parameterize 'Eff'.
94101-- 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:
102+-- effects without coupling an operation to a concrete list of effects. For
103+-- example, the above example would more commonly be expressed with the
104+-- following type:
97105--
98106-- @
99−-- ('Effectful.Reader.Reader' 'String' ':>' es, 'Effectful.State.Local.State' 'Bool' ':>' es) => 'Eff' es 'Integer'
107+-- ('Effectful.Reader.Reader' 'String' ':>' es, 'Effectful.State.State' 'Bool' ':>' es) => 'Eff' es 'Integer'
100108-- @
101109--
102−-- This abstraction allows the computation to be used in functions that may
110+-- This abstraction allows the operation to be used in functions that may
103111-- perform other effects, and it also allows the effects to be handled in any
104112-- order.
105113newtype Eff (es :: [Effect]) a = Eff (Env es -> IO a)
106114 deriving (Monoid, Semigroup)
107115
108−-- | Run a pure 'Eff' computation.
116+-- | Run a pure 'Eff' operation.
109117--
110−-- For running computations with side effects see 'runEff'.
118+-- For running operations with side effects see 'runEff'.
111119runPureEff :: Eff '[] a -> a
112120runPureEff (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).
121+ -- unsafePerformIO is safe here since IOE was not on the stack, so no IO with
122+ -- side effects was performed (unless someone sneakily introduced side effects
123+ -- with unsafeEff, but then all bets are off).
116124 --
117125 -- Moreover, internals don't allocate any resources that require explicit
118− -- cleanup actions to run.
126+ -- cleanup actions to run, so the "Dupable" part should also be just fine.
119127 unsafeDupablePerformIO $ m =<< emptyEnv
120128
121129----------------------------------------
@@ -128,68 +136,86 @@ unEff (Eff m) = m
128136-- | Access the underlying 'IO' monad along with the environment.
129137--
130138-- This function is __unsafe__ because it can be used to introduce arbitrary
131−-- 'IO' actions into pure 'Eff' computations.
139+-- 'IO' actions into pure 'Eff' operations.
132140unsafeEff :: (Env es -> IO a) -> Eff es a
133141unsafeEff m = Eff (oneShot m)
134142
135143-- | Access the underlying 'IO' monad.
136144--
137145-- This function is __unsafe__ because it can be used to introduce arbitrary
138−-- 'IO' actions into pure 'Eff' computations.
146+-- 'IO' actions into pure 'Eff' operations.
139147unsafeEff_ :: IO a -> Eff es a
140148unsafeEff_ m = unsafeEff $ \_ -> m
141149
150+-- | Utility for lifting 'IO' operations of type
151+--
152+-- @'IO' a -> 'IO' b@
153+--
154+-- to
155+--
156+-- @'Eff' es a -> 'Eff' es b@
157+--
158+-- This function is __unsafe__ because:
159+--
160+-- - It can be used to introduce arbitrary 'IO' actions into pure 'Eff'
161+-- operations.
162+--
163+-- - The 'IO' operation must not run its argument in a separate thread, but it's
164+-- not checked anywhere.
165+unsafeLiftMapIO :: (IO a -> IO b) -> Eff es a -> Eff es b
166+unsafeLiftMapIO f m = unsafeEff $ \es -> f (unEff m es)
167+
142168----------------------------------------
143−-- Unlifting IO
169+-- Unlifting Eff
144170
145171-- | Get the current 'UnliftStrategy'.
146172unliftStrategy :: IOE :> es => Eff es UnliftStrategy
147173unliftStrategy = do
148− DataA (IOE unlift) <- getData
174+ IdE (IOE unlift) <- getEffect
149175 pure unlift
150176
151177-- | Locally override the 'UnliftStrategy' with the given value.
152178withUnliftStrategy :: IOE :> es => UnliftStrategy -> Eff es a -> Eff es a
153−withUnliftStrategy unlift = localData $ \_ -> DataA (IOE unlift)
179+withUnliftStrategy unlift = localEffect $ \_ -> IdE (IOE unlift)
154180
155−-- | Create an unlifting function with the current 'UnliftStrategy'.
181+-- | Lower 'Eff' operations into 'IO' ('SeqUnlift').
156182--
157−-- This function is equivalent to 'withRunInIO', but has a 'HasCallStack'
158−-- constraint for accurate stack traces in case an insufficiently powerful
159−-- 'UnliftStrategy' is used and the unlifting function fails.
183+-- Exceptions thrown by this function:
160184--
161−-- /Note:/ the strategy is reset to 'SeqUnlift' inside the continuation.
162−withEffToIO
163− :: (HasCallStack, IOE :> es)
164− => ((forall r. Eff es r -> IO r) -> IO a)
165− -- ^ Continuation with the unlifting function in scope.
166− -> Eff es a
167−withEffToIO f = unliftStrategy >>= \case
168− SeqUnlift -> unsafeEff $ \es -> seqUnliftIO es f
169− ConcUnlift p b -> withUnliftStrategy SeqUnlift $ do
170− unsafeEff $ \es -> concUnliftIO es p b f
171−
172−-- | Create an unlifting function with the 'SeqUnlift' strategy.
173−seqUnliftIO
185+-- - 'InvalidUseOfSeqUnlift' if the unlift function is used in another thread.
186+seqUnliftEff
174187 :: HasCallStack
175188 => Env es
176− -- ^ The environment.
177189 -> ((forall r. Eff es r -> IO r) -> IO a)
178− -- ^ Continuation with the unlifting function in scope.
179190 -> IO a
180−seqUnliftIO es k = seqUnlift k es unEff
191+seqUnliftEff es k = seqUnliftIO k es unEff
181192
182−-- | Create an unlifting function with the 'ConcUnlift' strategy.
183−concUnliftIO
193+-- | Lower 'Eff' operations into 'IO' ('ConcUnlift').
194+concUnliftEff
184195 :: HasCallStack
185196 => Env es
186− -- ^ The environment.
187197 -> Persistence
188198 -> Limit
189199 -> ((forall r. Eff es r -> IO r) -> IO a)
190− -- ^ Continuation with the unlifting function in scope.
191200 -> IO a
192−concUnliftIO es persistence limit k = concUnlift persistence limit k es unEff
201+concUnliftEff es persistence limit k = concUnliftIO persistence limit k es unEff
202+
203+-- | Create an unlifting function with the current 'UnliftStrategy'.
204+--
205+-- This function is equivalent to 'withRunInIO', but has a 'HasCallStack'
206+-- constraint for accurate stack traces in case an insufficiently powerful
207+-- 'UnliftStrategy' is used and the unlifting function fails.
208+--
209+-- /Note:/ the strategy is reset to 'SeqUnlift' for new threads.
210+withEffToIO
211+ :: (HasCallStack, IOE :> es)
212+ => ((forall r. Eff es r -> IO r) -> IO a)
213+ -- ^ Continuation with the unlifting function in scope.
214+ -> Eff es a
215+withEffToIO f = unliftStrategy >>= \case
216+ SeqUnlift -> unsafeEff $ \es -> seqUnliftEff es f
217+ ConcUnlift p b -> withUnliftStrategy SeqUnlift $ do
218+ unsafeEff $ \es -> concUnliftEff es p b f
193219
194220----------------------------------------
195221-- Base
@@ -258,15 +284,15 @@ instance Fail :> es => MonadFail (Eff es) where
258284----------------------------------------
259285-- IO
260286
261−-- | Run arbitrary 'IO' computations via 'MonadIO' or 'MonadUnliftIO'.
287+-- | Run arbitrary 'IO' operations via 'MonadIO' or 'MonadUnliftIO'.
262288newtype IOE :: Effect where
263289 IOE :: UnliftStrategy -> IOE m r
264290
265−-- | Run an 'Eff' computation with side effects.
291+-- | Run an 'Eff' operation with side effects.
266292--
267−-- For running pure computations see 'runPureEff'.
293+-- For running pure operations see 'runPureEff'.
268294runEff :: Eff '[IOE] a -> IO a
269−runEff m = unEff (evalData (DataA (IOE SeqUnlift)) m) =<< emptyEnv
295+runEff m = unEff (evalEffect (IdE (IOE SeqUnlift)) m) =<< emptyEnv
270296
271297instance IOE :> es => MonadIO (Eff es) where
272298 liftIO = unsafeEff_
@@ -290,20 +316,20 @@ instance IOE :> es => MonadBaseControl IO (Eff es) where
290316----------------------------------------
291317-- Primitive
292318
293−-- | Provide the ability to perform primitive state-transformer actions.
319+-- | An effect to perform primitive state-transformer actions.
294320data Prim :: Effect where
295321 Prim :: Prim m r
296322
297−-- | Run an 'Eff' computation with primitive state-transformer actions.
323+-- | Run an 'Eff' operation with primitive state-transformer actions.
298324runPrim :: IOE :> es => Eff (Prim : es) a -> Eff es a
299−runPrim = evalData (DataA Prim)
325+runPrim = evalEffect (IdE Prim)
300326
301327instance Prim :> es => PrimMonad (Eff es) where
302328 type PrimState (Eff es) = RealWorld
303329 primitive = unsafeEff_ . IO
304330
305331----------------------------------------
306−-- Dynamic dispatch
332+-- Handler
307333
308334type role LocalEnv nominal nominal
309335
@@ -319,97 +345,76 @@ newtype LocalEnv (localEs :: [Effect]) (handlerEs :: [Effect]) = LocalEnv (Env l
319345type EffectHandler e es
320346 = forall a localEs. HasCallStack
321347 => LocalEnv localEs es
322− -- ^ Capture of the local environment for handling local 'Eff' computations
323− -- when @e@ is a higher order effect.
348+ -- ^ Capture of the local environment for handling local 'Eff' operations when
349+ -- @e@ is a higher order effect.
324350 -> e (Eff localEs) a
325351 -- ^ The effect performed in the local environment.
326352 -> Eff es a
327353
328−-- | An adapter for dynamically dispatched effects.
329−--
330−-- Represents the effect handler bundled with its environment.
331−data HandlerA :: Effect -> Type where
332− HandlerA :: !(Env es) -> !(EffectHandler e es) -> HandlerA e
354+-- | An effect handler bundled along with its environment.
355+data Handler :: Effect -> Type where
356+ Handler :: !(Env es) -> !(EffectHandler e es) -> Handler e
333357
334−-- | Run a dynamically dispatched effect with the given handler.
335−runHandler :: HandlerA e -> Eff (e : es) a -> Eff es a
358+-- | Run the effect with the given handler.
359+runHandler :: Handler e -> Eff (e : es) a -> Eff es a
336360runHandler e m = unsafeEff $ \es0 -> do
337361 size0 <- sizeEnv es0
338362 E.bracket (unsafeConsEnv e relinker es0)
339363 (unsafeTailEnv size0)
340364 (\es -> unEff m es)
341365 where
342− relinker :: Relinker HandlerA e
343− relinker = Relinker $ \relink (HandlerA handlerEs handle) -> do
344− newHandlerEs <- relink handlerEs
345− pure $ HandlerA newHandlerEs handle
366+ relinker :: Relinker Handler e
367+ relinker = Relinker $ \relink (Handler env handle) -> do
368+ newEnv <- relink env
369+ pure $ Handler newEnv handle
346370
347371-- | Send an operation of the given effect to its handler for execution.
348372send :: (HasCallStack, e :> es) => e (Eff es) a -> Eff es a
349373send op = unsafeEff $ \es -> do
350− HandlerA handlerEs handle <- getEnv es
351− unEff (handle (LocalEnv es) op) handlerEs
374+ Handler env handle <- getEnv es
375+ unEff (handle (LocalEnv es) op) env
352376
353377----------------------------------------
354−-- Static dispatch
378+-- Helpers
355379
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
380+runEffect :: handler e -> Eff (e : es) a -> Eff es (a, handler e)
381+runEffect e0 m = unsafeEff $ \es0 -> do
367382 size0 <- sizeEnv es0
368383 E.bracket (unsafeConsEnv e0 noRelinker es0)
369384 (unsafeTailEnv size0)
370385 (\es -> (,) <$> unEff m es <*> getEnv es)
371386
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
387+evalEffect :: handler e -> Eff (e : es) a -> Eff es a
388+evalEffect e m = unsafeEff $ \es0 -> do
376389 size0 <- sizeEnv es0
377390 E.bracket (unsafeConsEnv e noRelinker es0)
378391 (unsafeTailEnv size0)
379392 (\es -> unEff m es)
380393
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
394+execEffect :: handler e -> Eff (e : es) a -> Eff es (handler e)
395+execEffect e0 m = unsafeEff $ \es0 -> do
385396 size0 <- sizeEnv es0
386397 E.bracket (unsafeConsEnv e0 noRelinker es0)
387398 (unsafeTailEnv size0)
388399 (\es -> unEff m es *> getEnv es)
389400
390−-- | Fetch the current state of the effect.
391−getData :: e :> es => Eff es (DataA e)
392−getData = unsafeEff $ \es -> getEnv es
401+getEffect :: e :> es => Eff es (handler e)
402+getEffect = unsafeEff $ \es -> getEnv es
393403
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
404+putEffect :: e :> es => handler e -> Eff es ()
405+putEffect e = unsafeEff $ \es -> putEnv es e
397406
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
407+stateEffect :: e :> es => (handler e -> (a, handler e)) -> Eff es a
408+stateEffect f = unsafeEff $ \es -> stateEnv es f
401409
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
410+stateEffectM :: e :> es => (handler e -> Eff es (a, handler e)) -> Eff es a
411+stateEffectM f = unsafeEff $ \es -> E.mask $ \release -> do
406412 (a, e) <- (\e -> release $ unEff (f e) es) =<< getEnv es
407413 putEnv es e
408414 pure a
409415
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
416+localEffect :: e :> es => (handler e -> handler e) -> Eff es a -> Eff es a
417+localEffect f m = unsafeEff $ \es -> do
413418 E.bracket (stateEnv es $ \e -> (e, f e))
414419 (\e -> putEnv es e)
415420 (\_ -> unEff m es)