@@ -40,8 +40,8 @@ import Effectful.Internal.Effect
4040
4141type role Env nominal
4242
43−-- | A thread local, mutable, strict (elements are kept in weak head normal
44−-- form), extensible record indexed by data types of kind 'Effect'.
43+-- | A strict (WHNF), thread local, mutable, extensible record indexed by types
44+-- of kind 'Effect'.
4545--
4646-- Supports forking, i.e. introduction of local branches for encapsulation of
4747-- data specific to effect interpreters.
@@ -56,6 +56,58 @@ type role Env nominal
5656--
5757-- - Modification of a specific element: /O(1)/.
5858--
59+-- Here's an example of how the environment might look:
60+--
61+-- @
62+-- e00 - e01 - e05 - e07 (*)
63+-- | | |
64+-- | e06 e08 - e09
65+-- |
66+-- e02 - e03
67+-- |
68+-- e04
69+-- @
70+--
71+-- The point of execution is currently at (*), i.e. the mainline. Moreover,
72+-- currently:
73+--
74+-- - Mainline sees @[e00, e01, e05, e07]@.
75+--
76+-- - @e01@ is an interpreted effect, its handler sees @[e00, e02, e03]@.
77+--
78+-- - @e03@ is an interpreted effect, its handler sees @[e00, e02, e04]@.
79+--
80+-- - @e05@ is an interpreted effect, its handler sees @[e00, e01, e06]@.
81+--
82+-- - @e07@ is an interpreted effect, its handler sees @[e00, e01, e05, e08,
83+-- e09]@.
84+--
85+-- If an operation from @e01@ is invoked, the environment in the middle of
86+-- handling it might look like this:
87+--
88+-- @
89+-- e00 - e01 - e05 - e07
90+-- | | |
91+-- | e06 e08 - e09
92+-- |
93+-- e02 - e03 - e10 (*)
94+-- | |
95+-- e04 e11
96+-- |
97+-- e12
98+-- @
99+--
100+-- The point of execution is at (*), i.e. inside the handler of @e01@. The
101+-- handler needed to introduce @e10@ (which introduced @e11@, which in turn
102+-- introduced @e12@), so its local environment was temporarily extended with
103+-- it. Moreover, currently:
104+--
105+-- - Handler of @e01@ sees @[e00, e02, e03, e10]@.
106+--
107+-- - Handler of @e10@ sees @[e00, e02, e03, e11]@.
108+--
109+-- - Handler of @e11@ sees @[e00, e02, e03, e12]@.
110+--
59111data Env (es :: [Effect]) = Env
60112 { _forks :: Forks
61113 , _globalRef :: IORef EnvRef