revise and document cancellation semantics

in short, cancellable threads always use system tasks. normal threads use the host task, unless passed a token

docs/source/reference-core.rst

@@ -1823,9 +1823,20 @@ to spawn a child thread, and then use a :ref:`memory channel
 
 .. literalinclude:: reference-core/from-thread-example.py
 
+.. note::
+
+   The ``from_thread.run*`` functions reuse the host task that called
+   :func:`trio.to_thread.run_sync` to run your provided function in the typical case,
+   namely when ``cancellable=False`` so Trio can be sure that the task will always be
+   around to perform the work. If you pass ``cancellable=True`` at the outset, or if
+   you provide a :class:`~trio.lowlevel.TrioToken` when calling back in to Trio, your
+   functions will be executed in a new system task. Therefore, the
+   :func:`~trio.lowlevel.current_task`, :func:`current_effective_deadline`, or other
+   task-tree specific values may differ depending on keyword argument values.
+
 You can also use :func:`trio.from_thread.check_cancelled` to check for cancellation from
 a thread that was spawned by :func:`trio.to_thread.run_sync`. If the call to
-:func:`~trio.to_thread.run_sync` was cancelled, then
+:func:`~trio.to_thread.run_sync` was cancelled (even if ``cancellable=False``!), then
 :func:`~trio.from_thread.check_cancelled` will raise :func:`trio.Cancelled`.
 It's like ``trio.from_thread.run(trio.sleep, 0)``, but much faster.
 

trio/_tests/test_threads.py

@@ -933,12 +933,14 @@ async def async_time_bomb():
 async def test_from_thread_check_cancelled():
     q = stdlib_queue.Queue()
 
-    async def child(cancellable):
+    async def child(cancellable, scope):
+      with scope:
         record.append("start")
         try:
             return await to_thread_run_sync(f, cancellable=cancellable)
         except _core.Cancelled:
             record.append("cancel")
+            raise
         finally:
             record.append("exit")
 
@@ -956,7 +958,7 @@ def f():
     record = []
     ev = threading.Event()
     async with _core.open_nursery() as nursery:
-        nursery.start_soon(child, False)
+        nursery.start_soon(child, False, _core.CancelScope())
         await wait_all_tasks_blocked()
         assert record[0] == "start"
         assert q.get(timeout=1) == "Not Cancelled"
@@ -968,14 +970,15 @@ def f():
     # the appropriate cancel scope
     record = []
     ev = threading.Event()
+    scope = _core.CancelScope()  # Nursery cancel scope gives false positives
     async with _core.open_nursery() as nursery:
-        nursery.start_soon(child, False)
+        nursery.start_soon(child, False, scope)
         await wait_all_tasks_blocked()
         assert record[0] == "start"
         assert q.get(timeout=1) == "Not Cancelled"
-        nursery.cancel_scope.cancel()
+        scope.cancel()
         ev.set()
-    assert nursery.cancel_scope.cancelled_caught
+    assert scope.cancelled_caught
     assert "cancel" in record
     assert record[-1] == "exit"
 
@@ -992,13 +995,14 @@ def f():  # noqa: F811
 
     record = []
     ev = threading.Event()
+    scope = _core.CancelScope()
     async with _core.open_nursery() as nursery:
-        nursery.start_soon(child, True)
+        nursery.start_soon(child, True, scope)
         await wait_all_tasks_blocked()
         assert record[0] == "start"
-        nursery.cancel_scope.cancel()
+        scope.cancel()
         ev.set()
-    assert nursery.cancel_scope.cancelled_caught
+    assert scope.cancelled_caught
     assert "cancel" in record
     assert record[-1] == "exit"
     assert q.get(timeout=1) == "Cancelled"

trio/_tests/verify_types_darwin.json

@@ -40,7 +40,7 @@
     ],
     "exportedSymbolCounts": {
       "withAmbiguousType": 0,
-      "withKnownType": 631,
+      "withKnownType": 630,
       "withUnknownType": 0
     },
     "ignoreUnknownTypesFromImports": true,

trio/_tests/verify_types_linux.json

@@ -28,7 +28,7 @@
     ],
     "exportedSymbolCounts": {
       "withAmbiguousType": 0,
-      "withKnownType": 628,
+      "withKnownType": 627,
       "withUnknownType": 0
     },
     "ignoreUnknownTypesFromImports": true,

trio/_tests/verify_types_windows.json

@@ -64,7 +64,7 @@
     ],
     "exportedSymbolCounts": {
       "withAmbiguousType": 0,
-      "withKnownType": 631,
+      "withKnownType": 630,
       "withUnknownType": 0
     },
     "ignoreUnknownTypesFromImports": true,