Update docs for Handle, add Timer.

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
 -------