From fa6769dc34ea4a31172d345b1e740ad0b8887394 Mon Sep 17 00:00:00 2001 From: Guido van Rossum Date: Thu, 2 May 2013 16:35:23 -0700 Subject: [PATCH] Small corrections. --- pep-3156.txt | 37 ++++++++++++++++++++----------------- 1 file changed, 20 insertions(+), 17 deletions(-) diff --git a/pep-3156.txt b/pep-3156.txt index b79a1d72b..4645fbafb 100644 --- a/pep-3156.txt +++ b/pep-3156.txt @@ -360,8 +360,10 @@ Basic Callbacks ''''''''''''''' - ``call_soon(callback, *args)``. This schedules a callback to be - called as soon as possible. It guarantees that callbacks are called - in the order in which they were scheduled. + called as soon as possible. Returns a Handle representing the + callback, whose ``cancel()`` method can be used to cancel the + callback. It guarantees that callbacks are called in the order in + which they were scheduled. - ``call_later(delay, callback, *args)``. Arrange for ``callback(*args)`` to be called approximately ``delay`` seconds in @@ -371,9 +373,10 @@ Basic Callbacks time will be called in an undefined order. - ``call_at(when, callback, *args)``. This is like ``call_later()``, - but the time is expressed as an absolute time. There is a simple - equivalency: ``loop.call_later(delay, callback, *args)`` is the same - as ``loop.call_at(loop.time() + delay, callback, *args)``. + but the time is expressed as an absolute time. Returns a similar + Handle. There is a simple equivalency: ``loop.call_later(delay, + callback, *args)`` is the same as ``loop.call_at(loop.time() + + delay, callback, *args)``. Note: A previous version of this PEP defined a method named ``call_repeatedly()``, which promised to call a callback at regular @@ -785,11 +788,11 @@ Handles ------- The various methods for registering one-off callbacks -(``call_soon()``, ``call_later()`` and ``call_at()``) all return an -object representing the registration that can be used to cancel the -callback. This object is called a Handle (although its class name is -not necessarily ``Handle``). Handles are opaque and have only one -public method: +(``call_soon()``, ``call_later()``, ``call_at()`` and +``call_soon_threadsafe()``) all return an object representing the +registration that can be used to cancel the callback. This object is +called a Handle (although its class name is not necessarily +``Handle``). Handles are opaque and have only one public method: - ``cancel()``. Cancel the callback. @@ -834,10 +837,10 @@ public API is as follows, indicating the differences with PEP 3148: Difference with PEP 3148: The callback is never called immediately, and always in the context of the caller. (Typically, a context is a thread.) You can think of this as calling the callback through - ``call_soon()``. Note that the callback (unlike all other callbacks - defined in this PEP, and ignoring the convention from the section - "Callback Style" below) is always called with a single argument, the - Future object, and should not be a Handle object. + ``call_soon()``. Note that in order to match PEP 3148, the callback + (unlike all other callbacks defined in this PEP, and ignoring the + convention from the section "Callback Style" below) is always called + with a single argument, the Future object. - ``set_result(result)``. The Future must not be done (nor cancelled) already. This makes the Future done and schedules the callbacks. @@ -1312,9 +1315,9 @@ task's exception. Cancelling a task that's not done yet prevents its coroutine from completing. In this case a ``CancelledError`` exception is thrown -into the coroutine that it may catch to further handle cancellation. -If the exception is not caught, the generator will be properly -finalized anyway, as described in PEP 342. +into the coroutine, which it may catch to propagate cancellation to +other Futures. If the exception is not caught, the generator will be +properly finalized anyway, as described in PEP 342. Tasks are also useful for interoperating between coroutines and callback-based frameworks like Twisted. After converting a coroutine