add docs for async effects + fix effect cleanup timing

Instead of cleaning before render we clean just before next effect
this allows us to skip cleaning of no new effect is triggered for
memoized effects

Author: rmorshea

docs/source/life-cycle-hooks.rst

@@ -163,7 +163,28 @@ Now a new connection will only be estalished if a new ``url`` is provided.
 Async Effects
 .............
 
-under construction...
+A behavior unique to IDOM's implementation of ``use_effect`` is that it natively
+supports ``async`` functions:
+
+.. code-block::
+
+    async def nonblocking_effect():
+        resource = await do_something_asynchronously()
+        return lambda: blocking_close(resource)
+
+    use_effect(nonblocking_effect)
+
+
+There are **three important subtleties** to note about using asynchronous effects:
+
+1. The cleanup function must be a normal synchronous function.
+
+2. Asynchronous effects which do not complete before the next effect is created
+   following a re-render will be cancelled. This means an
+   :class:`~asyncio.CancelledError` will be raised somewhere in the body of the effect.
+
+3. An asynchronous effect may occur any time after the update which added this effect
+   and before the next effect following a subsequent update.
 
 
 **Supplementary Hooks**

idom/core/hooks.py

@@ -125,6 +125,7 @@ def use_effect(
     """
     hook = current_hook()
     memoize = use_memo(args=args)
+    last_clean_callback = use_ref(None)
 
     def add_effect(function: _EffectApplyFunc) -> None:
 
@@ -149,9 +150,13 @@ def clean_future() -> None:
                 return clean_future
 
         def effect() -> None:
-            clean = sync_function()
+            if last_clean_callback.current is not None:
+                last_clean_callback.current()
+
+            clean = last_clean_callback.current = sync_function()
             if clean is not None:
-                hook.add_effect("will_render will_unmount", clean)
+                hook.add_effect("will_unmount", clean)
+
             return None
 
         return memoize(lambda: hook.add_effect("did_render", effect))
@@ -355,7 +360,6 @@ def current_hook() -> "LifeCycleHook":
 
 
 class _EventEffects(NamedTuple):
-    will_render: List[Callable[[], Any]]
     did_render: List[Callable[[], Any]]
     will_unmount: List[Callable[[], Any]]
 
@@ -391,7 +395,7 @@ def __init__(
         self._rendered_atleast_once = False
         self._current_state_index = 0
         self._state: Tuple[Any, ...] = ()
-        self._event_effects = _EventEffects([], [], [])
+        self._event_effects = _EventEffects([], [])
 
     def schedule_render(self) -> None:
         if self._is_rendering:
@@ -418,15 +422,6 @@ def add_effect(self, events: str, function: Callable[[], None]) -> None:
     def element_will_render(self) -> None:
         """The element is about to render"""
         self._is_rendering = True
-
-        for effect in self._event_effects.will_render:
-            try:
-                effect()
-            except Exception:
-                msg = f"Pre-render effect {effect} failed for {self.element}"
-                logger.exception(msg)
-
-        self._event_effects.will_render.clear()
         self._event_effects.will_unmount.clear()
 
     def element_did_render(self) -> None:

tests/test_core/test_hooks.py

@@ -285,19 +285,19 @@ def CheckNoEffectYet():
     assert effect_triggers_after_final_render.current
 
 
-async def test_use_effect_cleanup_occurs_on_will_render():
+async def test_use_effect_cleanup_occurs_before_next_effect():
     element_hook = HookCatcher()
     cleanup_triggered = idom.Ref(False)
-    cleanup_triggered_before_next_render = idom.Ref(False)
+    cleanup_triggered_before_next_effect = idom.Ref(False)
 
     @idom.element
     @element_hook.capture
     def ElementWithEffect():
-        if cleanup_triggered.current:
-            cleanup_triggered_before_next_render.current = True
-
         @idom.hooks.use_effect
         def effect():
+            if cleanup_triggered.current:
+                cleanup_triggered_before_next_effect.current = True
+
             def cleanup():
                 cleanup_triggered.current = True
 
@@ -314,7 +314,7 @@ def cleanup():
         await layout.render()
 
         assert cleanup_triggered.current
-        assert cleanup_triggered_before_next_render.current
+        assert cleanup_triggered_before_next_effect.current
 
 
 async def test_use_effect_cleanup_occurs_on_will_unmount():
@@ -352,7 +352,7 @@ def cleanup():
         assert cleanup_triggered_before_next_render.current
 
 
-async def test_use_effect_memoization():
+async def test_memoized_effect_on_recreated_if_args_change():
     element_hook = HookCatcher()
     set_state_callback = idom.Ref(None)
     effect_run_count = idom.Ref(0)
@@ -392,6 +392,44 @@ def effect():
         assert effect_run_count.current == 2
 
 
+async def test_memoized_effect_cleanup_only_triggered_before_new_effect():
+    element_hook = HookCatcher()
+    set_state_callback = idom.Ref(None)
+    cleanup_trigger_count = idom.Ref(0)
+
+    first_value = 1
+    second_value = 2
+
+    @idom.element
+    @element_hook.capture
+    def ElementWithEffect():
+        state, set_state_callback.current = idom.hooks.use_state(first_value)
+
+        @idom.hooks.use_effect(args=[state])
+        def effect():
+            def cleanup():
+                cleanup_trigger_count.current += 1
+
+            return cleanup
+
+        return idom.html.div()
+
+    async with idom.Layout(ElementWithEffect()) as layout:
+        await layout.render()
+
+        assert cleanup_trigger_count.current == 0
+
+        element_hook.schedule_render()
+        await layout.render()
+
+        assert cleanup_trigger_count.current == 0
+
+        set_state_callback.current(second_value)
+        await layout.render()
+
+        assert cleanup_trigger_count.current == 1
+
+
 async def test_use_async_effect():
     effect_ran = asyncio.Event()
 
@@ -481,7 +519,7 @@ def bad_effect():
     assert re.match("Post-render effect .*? failed for .*?", first_log_line)
 
 
-async def test_error_in_effect_pre_render_cleanup_is_gracefully_handled(caplog):
+async def test_error_in_effect_cleanup_is_gracefully_handled(caplog):
     element_hook = HookCatcher()
 
     @idom.element
@@ -502,7 +540,7 @@ def bad_cleanup():
         await layout.render()  # no error
 
     first_log_line = next(iter(caplog.records)).msg.split("\n", 1)[0]
-    assert re.match("Pre-render effect .*? failed for .*?", first_log_line)
+    assert re.match("Post-render effect .*? failed for .*?", first_log_line)
 
 
 async def test_error_in_effect_pre_unmount_cleanup_is_gracefully_handled(caplog):