037b37a · effectful · git.iko.soy

git.iko.soy/effectful

Documentation adjustments

commit037b37a42cdc1b0522074f6920c84cc51792604d authorAndrzej Rybczak <andrzej@rybczak.net> dateTue 22 Jun 2021, 12:24 (5 years ago) parent587e87a

4 files changed+36−20

compare with master

unifiedsplit

README.md+1−1 src/Effectful/Internal/Effect.hs+1−1 src/Effectful/Internal/Env.hs+3−3 src/Effectful/Interpreter.hs+31−15

README.md+1−1

@@ -13,7 +13,7 @@ Main features:

1313

14141. Very fast.

1515

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).

1717

18183. Correct semantics in presence of runtime exceptions (no more lost or

1919 discarded state).

src/Effectful/Internal/Effect.hs+1−1

@@ -20,7 +20,7 @@ newtype IdE (e :: Effect) where

2020 IdE :: (forall m r. e m r) -> IdE e

2121

2222class (e :: Effect) :> (es :: [Effect]) where

23− -- | Get position of @e@ in @es@.

23+ -- | Get the position of @e@ in @es@.

2424 --

2525 -- /Note:/ GHC is kind enough to cache these values as they're top level CAFs,

2626 -- 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

160160-- Then forks will look like this:

161161--

162162-- Fork (baseIx: 10, unique: ...) [10,11]

163−-- (Fork (baseIx: 6, unique: ...) [6,7,8,9]

164−-- (Fork (baseIx: 2, unique: ...) [2,3,4,5]

163+-- (Fork (baseIx: 6, unique: ...) [6,7,8,9,..]

164+-- (Fork (baseIx: 2, unique: ...) [2,3,4,5,..]

165165-- NoFork))

166166--

167−-- and elements [0,1] are taken from the global environment.

167+-- and elements [0,1] are taken from the global environment ([0,1,..]).

168168--

169169-- We start with len: 12, we subtract baseIx: 10 and get n: 2, the number of

170170-- 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

22 ( -- * Sending commands

33 send

5− -- * Interpretation

5+ -- * Handling effects

6+ , RunIn

8+ -- ** Interpretation

69 , interpret

710 , interpretM

811 , interpretIO

912

10− -- * Reinterpretation

13+ -- ** Reinterpretation

1114 , reinterpret

1215 , reinterpretM

1316 , reinterpretIO

@@ -54,29 +57,36 @@ send op = readerEffectM $ \Interpreter{..} -> do

5457----------------------------------------

5558-- Interpretation

5659

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+

5764-- | Interpret a first order effect.

5865interpret

5966 :: (forall r es. HasCallStack => e (Eff es) r -> Eff baseEs r)

67+ -- ^ The effect handler

6068 -> Eff (e : baseEs) a

6169 -> Eff baseEs a

6270interpret interpreter m = unsafeEff $ \es -> do

6371 les <- forkEnv es

6472 runInterpreter es (Interpreter les $ \_ -> interpreter) m

6573

66−-- | Interpret a higher order effect with help of a natural transformation from

67−-- 'Eff' to 'Eff'.

74+-- | Interpret a higher order effect with help of a function running 'Eff'

75+-- computations in the local 'Eff' of an effect handler.

6876interpretM

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

7079 -> Eff (e : baseEs) a

7180 -> Eff baseEs a

7281interpretM interpreter m = unsafeEff $ \es -> do

7382 les <- forkEnv es

7483 runInterpreter es (Interpreter les $ \k -> interpreter $ unsafeEff_ . k) m

7584

76−-- | Interpret a higher order effect with help of a natural transformation from

77−-- 'Eff' to 'IO'.

85+-- | Interpret a higher order effect with help of a function running 'Eff'

86+-- computations in 'IO'.

7887interpretIO

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

8090 -> Eff (e : baseEs) a

8191 -> Eff baseEs a

8292interpretIO interpreter m = unsafeEff $ \es -> do

@@ -86,10 +96,12 @@ interpretIO interpreter m = unsafeEff $ \es -> do

8696----------------------------------------

8797-- Reinterpretation

8898

89−-- | Reinterpret local effects as a first order effect.

99+-- | Interpret a first order effect using local effects.

90100reinterpret

91101 :: (Eff localEs a -> Eff baseEs b)

102+ -- ^ Introduction of local effects

92103 -> (forall r es. HasCallStack => e (Eff es) r -> Eff localEs r)

104+ -- ^ The efect handler

93105 -> Eff (e : baseEs) a

94106 -> Eff baseEs b

95107reinterpret runLocal interpreter m = unsafeEff $ \es -> do

@@ -97,11 +109,13 @@ reinterpret runLocal interpreter m = unsafeEff $ \es -> do

97109 (`unEff` les0) . runLocal . unsafeEff $ \les -> do

98110 runInterpreter es (Interpreter les $ \_ -> interpreter) m

99111

100−-- | Reinterpret local effects as a higher order effect with help of a natural

101−-- transformation from 'Eff' to 'Eff'.

112+-- | Interpret a higher order effect using local effects with help of a function

113+-- running 'Eff' computations in the local 'Eff' of an effect handler.

102114reinterpretM

103115 :: (Eff localEs a -> Eff baseEs b)

104− -> (forall r es. HasCallStack => (forall t. Eff es t -> Eff localEs t) -> e (Eff es) r -> Eff localEs r)

116+ -- ^ Introduction of local effects

117+ -> (forall r es. HasCallStack => RunIn es (Eff localEs) -> e (Eff es) r -> Eff localEs r)

118+ -- ^ The effect handler

105119 -> Eff (e : baseEs) a

106120 -> Eff baseEs b

107121reinterpretM runLocal interpreter m = unsafeEff $ \es -> do

@@ -109,11 +123,13 @@ reinterpretM runLocal interpreter m = unsafeEff $ \es -> do

109123 (`unEff` les0) . runLocal . unsafeEff $ \les -> do

110124 runInterpreter es (Interpreter les $ \k -> interpreter $ unsafeEff_ . k) m

111125

112−-- | Reinterpret local effects as a higher order effect with help of a natural

113−-- transformation from 'Eff' to 'IO'.

126+-- | Interpret a higher order effect using local effects with help of a function

127+-- running 'Eff' computations in 'IO'.

114128reinterpretIO

115129 :: (Eff localEs a -> Eff baseEs b)

116− -> (forall r es. HasCallStack => (forall t. Eff es t -> IO t) -> e (Eff es) r -> Eff localEs r)

130+ -- ^ Introduction of local effects

131+ -> (forall r es. HasCallStack => RunIn es IO -> e (Eff es) r -> Eff localEs r)

132+ -- ^ The effect handler

117133 -> Eff (e : baseEs) a

118134 -> Eff baseEs b

119135reinterpretIO runLocal interpreter m = unsafeEff $ \es -> do