Various small updates.

pep-3156.txt

@@ -120,16 +120,22 @@ object.  It is possible that ``get_event_loop()`` returns a different
 object depending on the current thread, or depending on some other
 notion of context.
 
-To set the current event loop, use ``set_event_loop(eventloop)``,
-where ``eventloop`` is an instance of the ``EventLoop`` class or
+To set the current event loop, use ``set_event_loop(event_loop)``,
+where ``event_loop`` is an instance of the ``EventLoop`` class or
 equivalent.  This uses the same notion of context as
 ``get_event_loop()``.
 
-To change the way ``get_event_loop()`` and ``set_event_loop()`` work
+For the benefit of unit tests and other special cases there's a third
+policy function: ``init_event_loop()``, which creates a new EventLoop
+instance and calls ``set_event_loop()`` with it.  TBD: Maybe we should
+have a ``create_default_event_loop_instance()`` function instead?
+
+To change the way the above three functions work
 (including their notion of context), call
 ``set_event_loop_policy(policy)``, where ``policy`` is an event loop
 policy object.  The policy object can be any object that has methods
-``get_event_loop()`` and ``set_event_loop(eventloop)`` behaving like
+``get_event_loop()``, ``set_event_loop(event_loop)``
+and ``init_event_loop()`` behaving like
 the functions described above.  The default event loop policy is an
 instance of the class ``DefaultEventLoopPolicy``.  The current event loop
 policy object can be retrieved by calling ``get_event_loop_policy()``.
@@ -219,7 +225,7 @@ Some methods in the standard conforming interface return Futures:
   ``run_in_executor()``, but other implementations may choose to
   implement their own DNS lookup.
 
-- ``getnameinfo(sockaddr, flags)``.  Similar to
+- ``getnameinfo(sockaddr, flags=0)``.  Similar to
   ``socket.getnameinfo()`` but returns a Future.  The Future's result
   on success will be a tuple ``(host, port)``.  Same implementation
   remarks as for ``getaddrinfo()``.
@@ -436,7 +442,9 @@ indicating the differences with PEP 3148:
   and ignoring the convention from the section "Callback Style" below)
   is always called with a single argument, the Future object.
 
-The internal methods defined in PEP 3148 are not supported.
+The internal methods defined in PEP 3148 are not supported.  (TBD:
+Maybe we do need to support these, in order to make it easy to write
+user code that returns a Future?)
 
 A ``tulip.Future`` object is not acceptable to the ``wait()`` and
 ``as_completed()`` functions in the ``concurrent.futures`` package.
@@ -446,6 +454,11 @@ when used in a coroutine.  This is implemented through the
 ``__iter__()`` interface on the Future.  See the section "Coroutines
 and the Scheduler" below.
 
+When a Future is garbage-collected, if it has an associated exception
+but neither ``result()`` nor ``exception()`` nor ``__iter__()`` has
+ever been called (or the latter hasn't raised the exception yet --
+details TBD), the exception should be logged.  TBD: At what level?
+
 In the future (pun intended) we may unify ``tulip.Future`` and
 ``concurrent.futures.Future``, e.g. by adding an ``__iter__()`` method
 to the latter that works with ``yield from``.  To prevent accidentally
@@ -737,6 +750,17 @@ implemented by the ``Task`` and ``Future`` classes using only the
 public interface of the event loop, so it will work with third-party
 event loop implementations, too.
 
+Sleeping
+--------
+
+TBD: ``yield sleep(seconds)``.  Can use ``sleep(0)`` to suspend to
+poll for I/O.
+
+Wait for First
+--------------
+
+TBD: Need an interface to wait for the first of a collection of Futures.
+
 Coroutines and Protocols
 ------------------------
 
@@ -762,6 +786,8 @@ any point where it is yielding to the scheduler (i.e., potentially at
 any ``yield from`` operation).  We need to spell out which exception
 is raised.
 
+Also TBD: timeouts.
+
 
 Open Issues
 ===========