Add docs and update news

Co-Authored-By: oremanj <[email protected]>

Author: graingert

docs/source/reference-lowlevel.rst

@@ -377,6 +377,40 @@ These transitions are accomplished using two function decorators:
    poorly-timed :exc:`KeyboardInterrupt` could leave the lock in an
    inconsistent state and cause a deadlock.
 
+   Since KeyboardInterrupt protection is tracked per code object, any attempt to
+   conditionally protect the same block of code in different ways is unlikely to behave
+   how you expect. If you try to conditionally protect a closure, it will be
+   unconditionally protected instead::
+
+       def example(protect: bool) -> bool:
+           def inner() -> bool:
+               return trio.lowlevel.currently_ki_protected()
+           if protect:
+               inner = trio.lowlevel.enable_ki_protection(inner)
+           return inner()
+
+       assert example(False) == False
+       assert example(True) == True  # once protected ...
+       assert example(False) == True  # ... always protected
+
+   If you really need conditional protection, you can achieve it by giving each
+   KI-protected instance of the closure its own code object::
+
+       def example(protect: bool) -> bool:
+           def inner() -> bool:
+               return trio.lowlevel.currently_ki_protected()
+           if protect:
+               inner.__code__ = inner.__code__.replace()
+               inner = trio.lowlevel.enable_ki_protection(inner)
+           return inner()
+
+       assert example(False) == False
+       assert example(True) == True
+       assert example(False) == False
+
+   (This isn't done by default because it carries some memory overhead and reduces
+   the potential for specializing optimizations in recent versions of CPython.)
+
 .. autofunction:: currently_ki_protected
 
 

newsfragments/3108.bugfix.rst

@@ -1,5 +1,23 @@
 Rework KeyboardInterrupt protection to track code objects, rather than frames,
-as protected or not. This should substantially reduce its overhead, and also fixes
-an issue with the previous implementation: locals' lifetimes will no longer be
-extended by materialization in the ``frame.f_locals`` dictionary that the previous
-KI protection logic needed to access to do its work.
+as protected or not. The new implementation no longer needs to access
+``frame.f_locals`` dictionaries, so it won't artificially extend the lifetime of
+local variables. Since KeyboardInterrupt protection is now imposed statically
+(when a protected function is defined) rather than each time the function runs,
+its previously-noticeable performance overhead should now be near zero.
+The lack of a call-time wrapper has some other benefits as well:
+
+* :func:`inspect.iscoroutinefunction` and the like now give correct answers when
+  called on KI-protected functions.
+
+* Calling a synchronous KI-protected function no longer pushes an additional stack
+  frame, so tracebacks are clearer.
+
+* A synchronous KI-protected function invoked from C code (such as a weakref
+  finalizer) is now guaranteed to start executing; previously there would be a brief
+  window in which KeyboardInterrupt could be raised before the protection was
+  established.
+
+One minor drawback of the new approach is that it is no longer possible to apply
+different KI protection rules to different instances of the same closure. See the
+documentation of `@enable_ki_protection <trio.lowlevel.enable_ki_protection>`
+for more details and a workaround.