From 68a14ef3ce33ebee9b4d80327672e4d8e7cd366d Mon Sep 17 00:00:00 2001 From: "Nathaniel J. Smith" Date: Mon, 4 Sep 2017 02:07:52 -0700 Subject: [PATCH] Small doc tweaks --- docs/source/reference-hazmat.rst | 10 +++++----- trio/_core/_traps.py | 3 ++- 2 files changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/source/reference-hazmat.rst b/docs/source/reference-hazmat.rst index abc3eeb22..565e2eacd 100644 --- a/docs/source/reference-hazmat.rst +++ b/docs/source/reference-hazmat.rst @@ -403,11 +403,11 @@ Low-level blocking .. autofunction:: reschedule Here's an example lock class implemented using -:func:`wait_task_rescheduled` directly. This implementation has a number -of flaws, including lack of fairness, O(n) cancellation, missing error -checking, failure to insert a checkpoint on the non-blocking path, -etc. If you really want to implement your own lock, then you should -study the implementation of :class:`trio.Lock` and use +:func:`wait_task_rescheduled` directly. This implementation has a +number of flaws, including lack of fairness, O(n) cancellation, +missing error checking, failure to insert a checkpoint on the +non-blocking path, etc. If you really want to implement your own lock, +then you should study the implementation of :class:`trio.Lock` and use :class:`ParkingLot`, which handles some of these issues for you. But this does serve to illustrate the basic structure of the :func:`wait_task_rescheduled` API:: diff --git a/trio/_core/_traps.py b/trio/_core/_traps.py index 2914b7274..d15303676 100644 --- a/trio/_core/_traps.py +++ b/trio/_core/_traps.py @@ -75,7 +75,8 @@ def wait_task_rescheduled(abort_func): """Put the current task to sleep, with cancellation support. This is the lowest-level API for blocking in trio. Every time a - :class:`~trio.hazmat.Task` blocks, it does so by calling this function. + :class:`~trio.hazmat.Task` blocks, it does so by calling this function + (usually indirectly via some higher-level API). This is a tricky interface with no guard rails. If you can use :class:`ParkingLot` or the built-in I/O wait functions instead, then you