From 455dd3f556c86f7c2774cda75d19c722fc34fa9c Mon Sep 17 00:00:00 2001 From: Guido van Rossum Date: Fri, 26 Apr 2013 20:33:04 -0700 Subject: [PATCH] Update docs for Handle, add Timer. --- pep-3156.txt | 29 ++++++++++++++++++++--------- 1 file changed, 20 insertions(+), 9 deletions(-) diff --git a/pep-3156.txt b/pep-3156.txt index ad0278cda..b4b7be709 100644 --- a/pep-3156.txt +++ b/pep-3156.txt @@ -770,8 +770,13 @@ cancel the callback. For want of a better name this object is called a ``Handle``, although the user never needs to instantiate instances of this class. There is one public method: -- ``cancel()``. Attempt to cancel the callback. - TBD: Exact specification. +- ``cancel()``. Cancel the callback. This just sets the + ``cancelled`` attribute. The event loop must check this. + +- ``run()``. Call the callback with the specified arguments. If this + raises an exception, it is logged and the function returns normally. + This always returns None. Note that this ignores the ``cancelled`` + attribute (i.e., a cancelled ``Handle`` can still be called). Read-only public attributes: @@ -783,15 +788,21 @@ Read-only public attributes: Note that some callbacks (e.g. those registered with ``call_later()``) are meant to be called only once. Others (e.g. those registered with -``add_reader()``) are meant to be called multiple times. +``call_repeatedly()`` or ``add_reader()``) are meant to be called +multiple times. -TBD: An API to call the callback (encapsulating the exception handling -necessary)? Should it record how many times it has been called? -Maybe this API should just be ``__call__()``? (But it should suppress -exceptions.) +The Timer Subclass +'''''''''''''''''' -TBD: Public attribute recording the realtime value when the callback -is scheduled? (Since this is needed anyway for storing it in a heap.) +``Timer`` is a subclass of ``Handle`` returned by ``call_later()`` and +``call_repeatedly()``. + +It has one additional read-only public attribute: + +- ``when``, the real time when the callback is next scheduled to be + called. + +``Timer`` objects are ordered by their ``when`` field. Futures -------