Address PR review

Co-authored-by: Joshua Oreman <[email protected]>

Author: A5rocks

docs/source/reference-lowlevel.rst

@@ -58,28 +58,48 @@ Global statistics
 
 .. _trio_contexts:
 
-The current Trio context
-------------------------
-
-There are two different types of contexts in :mod:`trio`. Here are the
-semantics presented as a handy table. Choose the right function for
-your needs.
-
-+---------------------------------+-----------------------------------+------------------------------------+
-| situation                       | :func:`trio.lowlevel.in_trio_run` | :func:`trio.lowlevel.in_trio_task` |
-+=================================+===================================+====================================+
-| inside a running async function | `True`                            | `True`                             |
-+---------------------------------+-----------------------------------+------------------------------------+
-| without a running Trio loop     | `False`                           | `False`                            |
-+---------------------------------+-----------------------------------+------------------------------------+
-| in a guest run's host loop      | `True`                            | `False`                            |
-+---------------------------------+-----------------------------------+------------------------------------+
-| inside an instrument call       | depends                           | depends                            |
-+---------------------------------+-----------------------------------+------------------------------------+
-| :func:`trio.to_thread.run_sync` | `False`                           | `False`                            |
-+---------------------------------+-----------------------------------+------------------------------------+
-| inside an abort function        | `True`                            | `True`                             |
-+---------------------------------+-----------------------------------+------------------------------------+
+Checking for Trio
+-----------------
+
+If you want to interact with an active Trio run -- perhaps you need to
+know the :func:`~trio.current_time` or the
+:func:`~trio.lowlevel.current_task` -- then Trio needs to have certain
+state available to it or else you will get a
+``RuntimeError("must be called from async context")``.
+This requires that you either be:
+
+* indirectly inside (and on the same thread as) a call to
+  :func:`trio.run`, for run-level information such as the
+  :func:`~trio.current_time` or :func:`~trio.lowlevel.current_clock`.
+
+* indirectly inside a Trio task, for task-level information such as
+  the :func:`~trio.lowlevel.current_task` or
+  :func:`~trio.current_effective_deadline`.
+
+Internally, this state is provided by thread-local variables tracking
+the current run and the current task. Sometimes, it's useful to know
+in advance whether a call will fail or to have dynamic information for
+safeguards against running something inside or outside Trio. To do so,
+call :func:`trio.lowlevel.in_trio_run` or
+:func:`trio.lowlevel.in_trio_task`, which will provide answers
+according to the following table.
+
+
++--------------------------------------------------------+-----------------------------------+------------------------------------+
+| situation                                              | :func:`trio.lowlevel.in_trio_run` | :func:`trio.lowlevel.in_trio_task` |
++========================================================+===================================+====================================+
+| inside a Trio-flavored async function                  | `True`                            | `True`                             |
++--------------------------------------------------------+-----------------------------------+------------------------------------+
+| in a thread without an active call to :func:`trio.run` | `False`                           | `False`                            |
++--------------------------------------------------------+-----------------------------------+------------------------------------+
+| in a guest run's host loop                             | `True`                            | `False`                            |
++--------------------------------------------------------+-----------------------------------+------------------------------------+
+| inside an instrument call                              | depends                           | depends                            |
++--------------------------------------------------------+-----------------------------------+------------------------------------+
+| in a thread created by :func:`trio.to_thread.run_sync` | `False`                           | `False`                            |
++--------------------------------------------------------+-----------------------------------+------------------------------------+
+| inside an abort function                               | `True`                            | `True`                             |
++--------------------------------------------------------+-----------------------------------+------------------------------------+
 
 .. autofunction:: in_trio_run
 

src/trio/_core/_run.py

@@ -2832,8 +2832,9 @@ def unrolled_run(
     except BaseException as exc:
         raise TrioInternalError("internal error in Trio - please file a bug!") from exc
     finally:
-        GLOBAL_RUN_CONTEXT.__dict__.clear()
         runner.close()
+        GLOBAL_RUN_CONTEXT.__dict__.clear()
+
         # Have to do this after runner.close() has disabled KI protection,
         # because otherwise there's a race where ki_pending could get set
         # after we check it.
@@ -2954,16 +2955,18 @@ async def checkpoint_if_cancelled() -> None:
 
 def in_trio_run() -> bool:
     """Check whether we are in a Trio run.
+    This returns `True` if and only if :func:`~trio.current_time` will succeed.
 
-    See also :ref:`the different types of contexts <trio_contexts>`.
+    See also the discussion of differing ways of :ref:`detecting Trio <trio_contexts>`.
     """
     return hasattr(GLOBAL_RUN_CONTEXT, "runner")
 
 
 def in_trio_task() -> bool:
     """Check whether we are in a Trio task.
+    This returns `True` if and only if :func:`~trio.lowlevel.current_task` will succeed.
 
-    See also :ref:`the different types of contexts <trio_contexts>`.
+    See also the discussion of differing ways of :ref:`detecting Trio <trio_contexts>`.
     """
     return hasattr(GLOBAL_RUN_CONTEXT, "task")
 

src/trio/_core/_tests/test_instrumentation.py

@@ -275,17 +275,16 @@ class Instrument(_abc.Instrument):
         pass
 
     hooks = {
-        # category 1
+        # not run in task context
         "after_io_wait": (True, False),
         "before_io_wait": (True, False),
         "before_run": (True, False),
-        # category 2
-        "after_run": (False, False),
-        # category 3
+        "after_run": (True, False),
+        # run in task context
         "before_task_step": (True, True),
         "after_task_step": (True, True),
         "task_exited": (True, True),
-        # category 4
+        # depends
         "task_scheduled": (True, None),
         "task_spawned": (True, None),
     }