git.iko.soy/effectful
on master help sign in
Documentation adjustments
037b37aAndrzej Rybczak
README.md+1−1
compare with master
unifiedsplit
@@ -13,7 +13,7 @@ Main features:
13
13
141. Very fast.
141. Very fast.
15
15
16−2. Internals of the library are reasonably easy to reason about.
16+2. Easy to use API (no boilerplate code and dealing with arcane types).
17
17
183. Correct semantics in presence of runtime exceptions (no more lost or
183. Correct semantics in presence of runtime exceptions (no more lost or
19 discarded state).
19 discarded state).
src/Effectful/Internal/Effect.hs+1−1
@@ -20,7 +20,7 @@ newtype IdE (e :: Effect) where
20 IdE :: (forall m r. e m r) -> IdE e
20 IdE :: (forall m r. e m r) -> IdE e
21
21
22class (e :: Effect) :> (es :: [Effect]) where
22class (e :: Effect) :> (es :: [Effect]) where
23− -- | Get position of @e@ in @es@.
23+ -- | Get the position of @e@ in @es@.
24 --
24 --
25 -- /Note:/ GHC is kind enough to cache these values as they're top level CAFs,
25 -- /Note:/ GHC is kind enough to cache these values as they're top level CAFs,
26 -- so the lookup is amortized @O(1)@ without any language level tricks.
26 -- so the lookup is amortized @O(1)@ without any language level tricks.
src/Effectful/Internal/Env.hs+3−3
@@ -160,11 +160,11 @@ cloneEnv (Env forks@(Forks fid lref0 _) gref0 ug0) = do
160-- Then forks will look like this:
160-- Then forks will look like this:
161--
161--
162-- Fork (baseIx: 10, unique: ...) [10,11]
162-- Fork (baseIx: 10, unique: ...) [10,11]
163−-- (Fork (baseIx: 6, unique: ...) [6,7,8,9]
163+-- (Fork (baseIx: 6, unique: ...) [6,7,8,9,..]
164−-- (Fork (baseIx: 2, unique: ...) [2,3,4,5]
164+-- (Fork (baseIx: 2, unique: ...) [2,3,4,5,..]
165-- NoFork))
165-- NoFork))
166--
166--
167−-- and elements [0,1] are taken from the global environment.
167+-- and elements [0,1] are taken from the global environment ([0,1,..]).
168--
168--
169-- We start with len: 12, we subtract baseIx: 10 and get n: 2, the number of
169-- We start with len: 12, we subtract baseIx: 10 and get n: 2, the number of
170-- elements to copy from the fork. We copy them, then call recursively with
170-- elements to copy from the fork. We copy them, then call recursively with
src/Effectful/Interpreter.hs+31−15
@@ -2,12 +2,15 @@ module Effectful.Interpreter
2 ( -- * Sending commands
2 ( -- * Sending commands
3 send
3 send
4
4
5+ -- * Handling effects
6+ , RunIn
7+
5− -- * Interpretation
8+ -- ** Interpretation
6 , interpret
9 , interpret
7 , interpretM
10 , interpretM
8 , interpretIO
11 , interpretIO
9
12
10− -- * Reinterpretation
13+ -- ** Reinterpretation
11 , reinterpret
14 , reinterpret
12 , reinterpretM
15 , reinterpretM
13 , reinterpretIO
16 , reinterpretIO
@@ -54,29 +57,36 @@ send op = readerEffectM $ \Interpreter{..} -> do
54----------------------------------------
57----------------------------------------
55-- Interpretation
58-- Interpretation
56
59
60+-- | A function that runs 'Eff' computations in @m@ (usually a local 'Eff'
61+-- environment or 'IO').
62+type RunIn es m = forall r. Eff es r -> m r
63+
57-- | Interpret a first order effect.
64-- | Interpret a first order effect.
58interpret
65interpret
59 :: (forall r es. HasCallStack => e (Eff es) r -> Eff baseEs r)
66 :: (forall r es. HasCallStack => e (Eff es) r -> Eff baseEs r)
67+ -- ^ The effect handler
60 -> Eff (e : baseEs) a
68 -> Eff (e : baseEs) a
61 -> Eff baseEs a
69 -> Eff baseEs a
62interpret interpreter m = unsafeEff $ \es -> do
70interpret interpreter m = unsafeEff $ \es -> do
63 les <- forkEnv es
71 les <- forkEnv es
64 runInterpreter es (Interpreter les $ \_ -> interpreter) m
72 runInterpreter es (Interpreter les $ \_ -> interpreter) m
65
73
66−-- | Interpret a higher order effect with help of a natural transformation from
74+-- | Interpret a higher order effect with help of a function running 'Eff'
67−-- 'Eff' to 'Eff'.
75+-- computations in the local 'Eff' of an effect handler.
68interpretM
76interpretM
69− :: (forall r es. HasCallStack => (forall t. Eff es t -> Eff baseEs t) -> e (Eff es) r -> Eff baseEs r)
77+ :: (forall r es. HasCallStack => RunIn es (Eff baseEs) -> e (Eff es) r -> Eff baseEs r)
78+ -- ^ The effect handler
70 -> Eff (e : baseEs) a
79 -> Eff (e : baseEs) a
71 -> Eff baseEs a
80 -> Eff baseEs a
72interpretM interpreter m = unsafeEff $ \es -> do
81interpretM interpreter m = unsafeEff $ \es -> do
73 les <- forkEnv es
82 les <- forkEnv es
74 runInterpreter es (Interpreter les $ \k -> interpreter $ unsafeEff_ . k) m
83 runInterpreter es (Interpreter les $ \k -> interpreter $ unsafeEff_ . k) m
75
84
76−-- | Interpret a higher order effect with help of a natural transformation from
85+-- | Interpret a higher order effect with help of a function running 'Eff'
77−-- 'Eff' to 'IO'.
86+-- computations in 'IO'.
78interpretIO
87interpretIO
79− :: (forall r es. HasCallStack => (forall t. Eff es t -> IO t) -> e (Eff es) r -> Eff baseEs r)
88+ :: (forall r es. HasCallStack => RunIn es IO -> e (Eff es) r -> Eff baseEs r)
89+ -- ^ The effect handler
80 -> Eff (e : baseEs) a
90 -> Eff (e : baseEs) a
81 -> Eff baseEs a
91 -> Eff baseEs a
82interpretIO interpreter m = unsafeEff $ \es -> do
92interpretIO interpreter m = unsafeEff $ \es -> do
@@ -86,10 +96,12 @@ interpretIO interpreter m = unsafeEff $ \es -> do
86----------------------------------------
96----------------------------------------
87-- Reinterpretation
97-- Reinterpretation
88
98
89−-- | Reinterpret local effects as a first order effect.
99+-- | Interpret a first order effect using local effects.
90reinterpret
100reinterpret
91 :: (Eff localEs a -> Eff baseEs b)
101 :: (Eff localEs a -> Eff baseEs b)
102+ -- ^ Introduction of local effects
92 -> (forall r es. HasCallStack => e (Eff es) r -> Eff localEs r)
103 -> (forall r es. HasCallStack => e (Eff es) r -> Eff localEs r)
104+ -- ^ The efect handler
93 -> Eff (e : baseEs) a
105 -> Eff (e : baseEs) a
94 -> Eff baseEs b
106 -> Eff baseEs b
95reinterpret runLocal interpreter m = unsafeEff $ \es -> do
107reinterpret runLocal interpreter m = unsafeEff $ \es -> do
@@ -97,11 +109,13 @@ reinterpret runLocal interpreter m = unsafeEff $ \es -> do
97 (`unEff` les0) . runLocal . unsafeEff $ \les -> do
109 (`unEff` les0) . runLocal . unsafeEff $ \les -> do
98 runInterpreter es (Interpreter les $ \_ -> interpreter) m
110 runInterpreter es (Interpreter les $ \_ -> interpreter) m
99
111
100−-- | Reinterpret local effects as a higher order effect with help of a natural
112+-- | Interpret a higher order effect using local effects with help of a function
101−-- transformation from 'Eff' to 'Eff'.
113+-- running 'Eff' computations in the local 'Eff' of an effect handler.
102reinterpretM
114reinterpretM
103 :: (Eff localEs a -> Eff baseEs b)
115 :: (Eff localEs a -> Eff baseEs b)
116+ -- ^ Introduction of local effects
104− -> (forall r es. HasCallStack => (forall t. Eff es t -> Eff localEs t) -> e (Eff es) r -> Eff localEs r)
117+ -> (forall r es. HasCallStack => RunIn es (Eff localEs) -> e (Eff es) r -> Eff localEs r)
118+ -- ^ The effect handler
105 -> Eff (e : baseEs) a
119 -> Eff (e : baseEs) a
106 -> Eff baseEs b
120 -> Eff baseEs b
107reinterpretM runLocal interpreter m = unsafeEff $ \es -> do
121reinterpretM runLocal interpreter m = unsafeEff $ \es -> do
@@ -109,11 +123,13 @@ reinterpretM runLocal interpreter m = unsafeEff $ \es -> do
109 (`unEff` les0) . runLocal . unsafeEff $ \les -> do
123 (`unEff` les0) . runLocal . unsafeEff $ \les -> do
110 runInterpreter es (Interpreter les $ \k -> interpreter $ unsafeEff_ . k) m
124 runInterpreter es (Interpreter les $ \k -> interpreter $ unsafeEff_ . k) m
111
125
112−-- | Reinterpret local effects as a higher order effect with help of a natural
126+-- | Interpret a higher order effect using local effects with help of a function
113−-- transformation from 'Eff' to 'IO'.
127+-- running 'Eff' computations in 'IO'.
114reinterpretIO
128reinterpretIO
115 :: (Eff localEs a -> Eff baseEs b)
129 :: (Eff localEs a -> Eff baseEs b)
130+ -- ^ Introduction of local effects
116− -> (forall r es. HasCallStack => (forall t. Eff es t -> IO t) -> e (Eff es) r -> Eff localEs r)
131+ -> (forall r es. HasCallStack => RunIn es IO -> e (Eff es) r -> Eff localEs r)
132+ -- ^ The effect handler
117 -> Eff (e : baseEs) a
133 -> Eff (e : baseEs) a
118 -> Eff baseEs b
134 -> Eff baseEs b
119reinterpretIO runLocal interpreter m = unsafeEff $ \es -> do
135reinterpretIO runLocal interpreter m = unsafeEff $ \es -> do