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