@@ -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− ( -- * Monad
9+ ( -- * The 'Eff' monad
11 , runPureEff
11 , runPureEff
@@ -22,49 +22,41 @@ module Effectful.Internal.Monad
25− -- * Primitive
25+ -- * Prim
29− -- ** Unlift strategies
29+ -- * Unlift strategies
30 , UnliftStrategy(..)
30 , UnliftStrategy(..)
31 , Persistence(..)
31 , Persistence(..)
32 , Limit(..)
32 , Limit(..)
33 , unliftStrategy
33 , unliftStrategy
34 , withUnliftStrategy
34 , withUnliftStrategy
35 , withEffToIO
35 , withEffToIO
38− --- *** Low-level helpers
37+ -- ** Low-level unlifts
39− , unsafeLiftMapIO
38+ , seqUnliftIO
40− , unsafeUnliftToEff
39+ , concUnliftIO
44 -- * Effects
41 -- * Effects
46− -- ** Handler
43+ -- ** Dynamic dispatch
47 , EffectHandler
44 , EffectHandler
48 , LocalEnv(..)
45 , LocalEnv(..)
49− , Handler(..)
46+ , HandlerA(..)
50 , runHandler
47 , runHandler
52− -- *** Sending operations
55− -- ** Primitive
50+ -- ** Static dispatch
57− -- *** Running
52+ , runData
58− , runEffect
53+ , evalData
59− , evalEffect
54+ , execData
60− , execEffect
55+ , getData
62− -- *** Modification
57+ , stateData
63− , getEffect
58+ , stateDataM
64− , putEffect
59+ , localData
70import Control.Applicative (liftA2)
62import Control.Applicative (liftA2)
@@ -87,44 +79,43 @@ import Effectful.Internal.Unlift
88type role Eff nominal representational
80type role Eff nominal representational
90−-- | The 'Eff' monad provides the implementation of an operation that performs
82+-- | The 'Eff' monad provides the implementation of a computation that performs
91-- an arbitrary set of effects. In @'Eff' es a@, @es@ is a type-level list that
83-- an arbitrary set of effects. In @'Eff' es a@, @es@ is a type-level list that
92−-- contains all the effects that the operation may perform. For example, an
84+-- contains all the effects that the computation may perform. For example, a
93−-- operation that produces an 'Integer' by consuming a 'String' from the global
85+-- computation that produces an 'Integer' by consuming a 'String' from the
94−-- environment and acting upon a single mutable cell containing a 'Bool' would
86+-- global environment and acting upon a single mutable value of type 'Bool'
95−-- have the following type:
87+-- would have the following type:
98−-- 'Eff' '['Effectful.Reader.Reader' 'String', 'Effectful.State.State' 'Bool'] 'Integer'
90+-- 'Eff' '['Effectful.Reader.Reader' 'String', 'Effectful.State.Local.State' 'Bool'] 'Integer'
101-- Normally, a concrete list of effects is not used to parameterize 'Eff'.
93-- Normally, a concrete list of effects is not used to parameterize 'Eff'.
102-- Instead, the '(:>)' type class is used to express constraints on the list of
94-- Instead, the '(:>)' type class is used to express constraints on the list of
103−-- effects without coupling an operation to a concrete list of effects. For
95+-- effects without coupling a computation to a concrete list of effects. For
104−-- example, the above example would more commonly be expressed with the
96+-- example, the above example would be expressed with the following type:
108−-- ('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'
111−-- 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
112-- perform other effects, and it also allows the effects to be handled in any
103-- perform other effects, and it also allows the effects to be handled in any
114newtype Eff (es :: [Effect]) a = Eff (Env es -> IO a)
105newtype Eff (es :: [Effect]) a = Eff (Env es -> IO a)
115 deriving (Monoid, Semigroup)
106 deriving (Monoid, Semigroup)
117−-- | Run a pure 'Eff' operation.
108+-- | Run a pure 'Eff' computation.
119−-- For running operations with side effects see 'runEff'.
110+-- For running computations with side effects see 'runEff'.
120runPureEff :: Eff '[] a -> a
111runPureEff :: Eff '[] a -> a
121runPureEff (Eff m) =
112runPureEff (Eff m) =
122− -- unsafePerformIO is safe here since IOE was not on the stack, so no IO with
113+ -- unsafeDupablePerformIO is safe here since IOE was not on the stack, so no
123− -- side effects was performed (unless someone sneakily introduced side effects
114+ -- IO with side effects was performed (unless someone sneakily introduced side
124− -- with unsafeEff, but then all bets are off).
115+ -- effects with unsafeEff, but then all bets are off).
126 -- Moreover, internals don't allocate any resources that require explicit
117 -- Moreover, internals don't allocate any resources that require explicit
127− -- cleanup actions to run, so the "Dupable" part should also be just fine.
118+ -- cleanup actions to run.
128 unsafeDupablePerformIO $ m =<< emptyEnv
119 unsafeDupablePerformIO $ m =<< emptyEnv
130----------------------------------------
121----------------------------------------
@@ -137,69 +128,29 @@ unEff (Eff m) = m
137-- | Access the underlying 'IO' monad along with the environment.
128-- | Access the underlying 'IO' monad along with the environment.
139-- This function is __unsafe__ because it can be used to introduce arbitrary
130-- This function is __unsafe__ because it can be used to introduce arbitrary
140−-- 'IO' actions into pure 'Eff' operations.
131+-- 'IO' actions into pure 'Eff' computations.
141unsafeEff :: (Env es -> IO a) -> Eff es a
132unsafeEff :: (Env es -> IO a) -> Eff es a
142unsafeEff m = Eff (oneShot m)
133unsafeEff m = Eff (oneShot m)
144-- | Access the underlying 'IO' monad.
135-- | Access the underlying 'IO' monad.
146-- This function is __unsafe__ because it can be used to introduce arbitrary
137-- This function is __unsafe__ because it can be used to introduce arbitrary
147−-- 'IO' actions into pure 'Eff' operations.
138+-- 'IO' actions into pure 'Eff' computations.
148unsafeEff_ :: IO a -> Eff es a
139unsafeEff_ :: IO a -> Eff es a
149unsafeEff_ m = unsafeEff $ \_ -> m
140unsafeEff_ m = unsafeEff $ \_ -> m
151−-- | Utility for lifting 'IO' operations of type
153−-- @'IO' a -> 'IO' b@
157−-- @'Eff' es a -> 'Eff' es b@
159−-- This function is __unsafe__ because:
161−-- - It can be used to introduce arbitrary 'IO' actions into pure 'Eff'
164−-- - The 'IO' operation must not run its argument in a separate thread, but it's
165−-- not checked anywhere.
166−unsafeLiftMapIO :: (IO a -> IO b) -> Eff es a -> Eff es b
167−unsafeLiftMapIO f m = unsafeEff $ \es -> f (unEff m es)
169----------------------------------------
142----------------------------------------
170−-- Unlifting Eff
143+-- Unlifting IO
172-- | Get the current 'UnliftStrategy'.
145-- | Get the current 'UnliftStrategy'.
173unliftStrategy :: IOE :> es => Eff es UnliftStrategy
146unliftStrategy :: IOE :> es => Eff es UnliftStrategy
174unliftStrategy = do
147unliftStrategy = do
175− IdE (IOE unlift) <- getEffect
148+ DataA (IOE unlift) <- getData
176 pure unlift
149 pure unlift
178-- | Locally override the 'UnliftStrategy' with the given value.
151-- | Locally override the 'UnliftStrategy' with the given value.
179withUnliftStrategy :: IOE :> es => UnliftStrategy -> Eff es a -> Eff es a
152withUnliftStrategy :: IOE :> es => UnliftStrategy -> Eff es a -> Eff es a
180−withUnliftStrategy unlift = localEffect $ \_ -> IdE (IOE unlift)
153+withUnliftStrategy unlift = localData $ \_ -> DataA (IOE unlift)
182−-- | Lower 'Eff' operations into 'IO' ('SeqUnlift').
184−-- Exceptions thrown by this function:
186−-- - 'InvalidUseOfSeqUnlift' if the unlift function is used in another thread.
190− -> ((forall r. Eff es r -> IO r) -> IO a)
192−seqUnliftEff es k = seqUnliftIO k es unEff
194−-- | Lower 'Eff' operations into 'IO' ('ConcUnlift').
200− -> ((forall r. Eff es r -> IO r) -> IO a)
202−concUnliftEff es persistence limit k = concUnliftIO persistence limit k es unEff
204-- | Create an unlifting function with the current 'UnliftStrategy'.
155-- | Create an unlifting function with the current 'UnliftStrategy'.
@@ -207,25 +158,38 @@ concUnliftEff es persistence limit k = concUnliftIO persistence limit k es unEff
207-- constraint for accurate stack traces in case an insufficiently powerful
158-- constraint for accurate stack traces in case an insufficiently powerful
208-- 'UnliftStrategy' is used and the unlifting function fails.
159-- 'UnliftStrategy' is used and the unlifting function fails.
210−-- /Note:/ the strategy is reset to 'SeqUnlift' for new threads.
161+-- /Note:/ the strategy is reset to 'SeqUnlift' inside the continuation.
211withEffToIO
162withEffToIO
212 :: (HasCallStack, IOE :> es)
163 :: (HasCallStack, IOE :> es)
213 => ((forall r. Eff es r -> IO r) -> IO a)
164 => ((forall r. Eff es r -> IO r) -> IO a)
214 -- ^ Continuation with the unlifting function in scope.
165 -- ^ Continuation with the unlifting function in scope.
215 -> Eff es a
166 -> Eff es a
216withEffToIO f = unliftStrategy >>= \case
167withEffToIO f = unliftStrategy >>= \case
217− SeqUnlift -> unsafeEff $ \es -> seqUnliftEff es f
168+ SeqUnlift -> unsafeEff $ \es -> seqUnliftIO es f
218 ConcUnlift p b -> withUnliftStrategy SeqUnlift $ do
169 ConcUnlift p b -> withUnliftStrategy SeqUnlift $ do
219− unsafeEff $ \es -> concUnliftEff es p b f
170+ unsafeEff $ \es -> concUnliftIO es p b f
221−-- | An unlifing function that lifts a function and its callback from 'IO' to
172+-- | Create an unlifting function with the 'SeqUnlift' strategy.
222−-- 'Eff'.
173+seqUnliftIO
223−--
174+ :: HasCallStack
224−-- This function is unsafe since there are no checks wrt. to concurrency at all.
175+ => Env es
225−-- Use with care.
176+ -- ^ The environment.
226−unsafeUnliftToEff :: ((a -> IO b) -> IO c) -> (a -> Eff es b) -> Eff es c
177+ -> ((forall r. Eff es r -> IO r) -> IO a)
227−unsafeUnliftToEff k f = unsafeEff $ \es -> do
178+ -- ^ Continuation with the unlifting function in scope.
228− k ((`unEff` es) . f)
179+ -> IO a
180+seqUnliftIO es k = seqUnlift k es unEff
182+-- | Create an unlifting function with the 'ConcUnlift' strategy.
186+ -- ^ The environment.
189+ -> ((forall r. Eff es r -> IO r) -> IO a)
190+ -- ^ Continuation with the unlifting function in scope.
192+concUnliftIO es persistence limit k = concUnlift persistence limit k es unEff
230----------------------------------------
194----------------------------------------
@@ -294,15 +258,15 @@ instance Fail :> es => MonadFail (Eff es) where
294----------------------------------------
258----------------------------------------
297−-- | Run arbitrary 'IO' operations via 'MonadIO' or 'MonadUnliftIO'.
261+-- | Run arbitrary 'IO' computations via 'MonadIO' or 'MonadUnliftIO'.
298newtype IOE :: Effect where
262newtype IOE :: Effect where
299 IOE :: UnliftStrategy -> IOE m r
263 IOE :: UnliftStrategy -> IOE m r
301−-- | Run an 'Eff' operation with side effects.
265+-- | Run an 'Eff' computation with side effects.
303−-- For running pure operations see 'runPureEff'.
267+-- For running pure computations see 'runPureEff'.
304runEff :: Eff '[IOE] a -> IO a
268runEff :: Eff '[IOE] a -> IO a
305−runEff m = unEff (evalEffect (IdE (IOE SeqUnlift)) m) =<< emptyEnv
269+runEff m = unEff (evalData (DataA (IOE SeqUnlift)) m) =<< emptyEnv
307instance IOE :> es => MonadIO (Eff es) where
271instance IOE :> es => MonadIO (Eff es) where
308 liftIO = unsafeEff_
272 liftIO = unsafeEff_
@@ -326,20 +290,20 @@ instance IOE :> es => MonadBaseControl IO (Eff es) where
326----------------------------------------
290----------------------------------------
327-- Primitive
291-- Primitive
329−-- | An effect to perform primitive state-transformer actions.
293+-- | Provide the ability to perform primitive state-transformer actions.
330data Prim :: Effect where
294data Prim :: Effect where
331 Prim :: Prim m r
295 Prim :: Prim m r
333−-- | Run an 'Eff' operation with primitive state-transformer actions.
297+-- | Run an 'Eff' computation with primitive state-transformer actions.
334runPrim :: IOE :> es => Eff (Prim : es) a -> Eff es a
298runPrim :: IOE :> es => Eff (Prim : es) a -> Eff es a
335−runPrim = evalEffect (IdE Prim)
299+runPrim = evalData (DataA Prim)
337instance Prim :> es => PrimMonad (Eff es) where
301instance Prim :> es => PrimMonad (Eff es) where
338 type PrimState (Eff es) = RealWorld
302 type PrimState (Eff es) = RealWorld
339 primitive = unsafeEff_ . IO
303 primitive = unsafeEff_ . IO
341----------------------------------------
305----------------------------------------
342−-- Handler
306+-- Dynamic dispatch
344type role LocalEnv nominal nominal
308type role LocalEnv nominal nominal
@@ -355,76 +319,97 @@ newtype LocalEnv (localEs :: [Effect]) (handlerEs :: [Effect]) = LocalEnv (Env l
355type EffectHandler e es
319type EffectHandler e es
356 = forall a localEs. HasCallStack
320 = forall a localEs. HasCallStack
357 => LocalEnv localEs es
321 => LocalEnv localEs es
358− -- ^ Capture of the local environment for handling local 'Eff' operations when
322+ -- ^ Capture of the local environment for handling local 'Eff' computations
359− -- @e@ is a higher order effect.
323+ -- when @e@ is a higher order effect.
360 -> e (Eff localEs) a
324 -> e (Eff localEs) a
361 -- ^ The effect performed in the local environment.
325 -- ^ The effect performed in the local environment.
362 -> Eff es a
326 -> Eff es a
328+-- | An adapter for dynamically dispatched effects.
364−-- | An effect handler bundled along with its environment.
330+-- Represents the effect handler bundled with its environment.
365−data Handler :: Effect -> Type where
331+data HandlerA :: Effect -> Type where
366− Handler :: !(Env es) -> !(EffectHandler e es) -> Handler e
332+ HandlerA :: !(Env es) -> !(EffectHandler e es) -> HandlerA e
368−-- | Run the effect with the given handler.
334+-- | Run a dynamically dispatched effect with the given handler.
369−runHandler :: Handler e -> Eff (e : es) a -> Eff es a
335+runHandler :: HandlerA e -> Eff (e : es) a -> Eff es a
370runHandler e m = unsafeEff $ \es0 -> do
336runHandler e m = unsafeEff $ \es0 -> do
371 size0 <- sizeEnv es0
337 size0 <- sizeEnv es0
372 E.bracket (unsafeConsEnv e relinker es0)
338 E.bracket (unsafeConsEnv e relinker es0)
373 (unsafeTailEnv size0)
339 (unsafeTailEnv size0)
374 (\es -> unEff m es)
340 (\es -> unEff m es)
376− relinker :: Relinker Handler e
342+ relinker :: Relinker HandlerA e
377− relinker = Relinker $ \relink (Handler env handle) -> do
343+ relinker = Relinker $ \relink (HandlerA handlerEs handle) -> do
378− newEnv <- relink env
344+ newHandlerEs <- relink handlerEs
379− pure $ Handler newEnv handle
345+ pure $ HandlerA newHandlerEs handle
381-- | Send an operation of the given effect to its handler for execution.
347-- | Send an operation of the given effect to its handler for execution.
382send :: (HasCallStack, e :> es) => e (Eff es) a -> Eff es a
348send :: (HasCallStack, e :> es) => e (Eff es) a -> Eff es a
383send op = unsafeEff $ \es -> do
349send op = unsafeEff $ \es -> do
384− Handler env handle <- getEnv es
350+ HandlerA handlerEs handle <- getEnv es
385− unEff (handle (LocalEnv es) op) env
351+ unEff (handle (LocalEnv es) op) handlerEs
387----------------------------------------
353----------------------------------------
388−-- Helpers
354+-- Static dispatch
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.
390−runEffect :: handler e -> Eff (e : es) a -> Eff es (a, handler e)
365+runData :: DataA e -> Eff (e : es) a -> Eff es (a, DataA e)
391−runEffect e0 m = unsafeEff $ \es0 -> do
366+runData e0 m = unsafeEff $ \es0 -> do
392 size0 <- sizeEnv es0
367 size0 <- sizeEnv es0
393 E.bracket (unsafeConsEnv e0 noRelinker es0)
368 E.bracket (unsafeConsEnv e0 noRelinker es0)
394 (unsafeTailEnv size0)
369 (unsafeTailEnv size0)
395 (\es -> (,) <$> unEff m es <*> getEnv es)
370 (\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.
397−evalEffect :: handler e -> Eff (e : es) a -> Eff es a
374+evalData :: DataA e -> Eff (e : es) a -> Eff es a
398−evalEffect e m = unsafeEff $ \es0 -> do
375+evalData e m = unsafeEff $ \es0 -> do
399 size0 <- sizeEnv es0
376 size0 <- sizeEnv es0
400 E.bracket (unsafeConsEnv e noRelinker es0)
377 E.bracket (unsafeConsEnv e noRelinker es0)
401 (unsafeTailEnv size0)
378 (unsafeTailEnv size0)
402 (\es -> unEff m es)
379 (\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.
404−execEffect :: handler e -> Eff (e : es) a -> Eff es (handler e)
383+execData :: DataA e -> Eff (e : es) a -> Eff es (DataA e)
405−execEffect e0 m = unsafeEff $ \es0 -> do
384+execData e0 m = unsafeEff $ \es0 -> do
406 size0 <- sizeEnv es0
385 size0 <- sizeEnv es0
407 E.bracket (unsafeConsEnv e0 noRelinker es0)
386 E.bracket (unsafeConsEnv e0 noRelinker es0)
408 (unsafeTailEnv size0)
387 (unsafeTailEnv size0)
409 (\es -> unEff m es *> getEnv es)
388 (\es -> unEff m es *> getEnv es)
411−getEffect :: e :> es => Eff es (handler e)
390+-- | Fetch the current state of the effect.
391+getData :: e :> es => Eff es (DataA e)
412−getEffect = unsafeEff $ \es -> getEnv es
392+getData = unsafeEff $ \es -> getEnv es
414−putEffect :: e :> es => handler e -> Eff es ()
394+-- | Set the current state of the effect to the given value.
395+putData :: e :> es => DataA e -> Eff es ()
415−putEffect e = unsafeEff $ \es -> putEnv es e
396+putData e = unsafeEff $ \es -> putEnv es e
417−stateEffect :: e :> es => (handler e -> (a, handler e)) -> Eff es a
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
418−stateEffect f = unsafeEff $ \es -> stateEnv es f
400+stateData f = unsafeEff $ \es -> stateEnv es f
402+-- | Apply the monadic function to the current state of the effect and return a
420−stateEffectM :: e :> es => (handler e -> Eff es (a, handler e)) -> Eff es a
404+stateDataM :: e :> es => (DataA e -> Eff es (a, DataA e)) -> Eff es a
421−stateEffectM f = unsafeEff $ \es -> E.mask $ \release -> do
405+stateDataM f = unsafeEff $ \es -> E.mask $ \release -> do
422 (a, e) <- (\e -> release $ unEff (f e) es) =<< getEnv es
406 (a, e) <- (\e -> release $ unEff (f e) es) =<< getEnv es
423 putEnv es e
407 putEnv es e
410+-- | Execute a computation with a temporarily modified state of the effect.
426−localEffect :: e :> es => (handler e -> handler e) -> Eff es a -> Eff es a
411+localData :: e :> es => (DataA e -> DataA e) -> Eff es a -> Eff es a
427−localEffect f m = unsafeEff $ \es -> do
412+localData f m = unsafeEff $ \es -> do
428 E.bracket (stateEnv es $ \e -> (e, f e))
413 E.bracket (stateEnv es $ \e -> (e, f e))
429 (\e -> putEnv es e)
414 (\e -> putEnv es e)
430 (\_ -> unEff m es)
415 (\_ -> unEff m es)