Somewhat rambling changes to event loop policy.

pep-3156.txt

@@ -165,50 +165,53 @@ Event Loop Policy: Getting and Setting the Current Event Loop
 -------------------------------------------------------------
 
 Event loop management is controlled by an event loop policy, which is
-a global (per-process) state.  There is a default policy, and an API
-to change the policy.  The policy defines the notion of context; the
-default policy's notion of context is defined as the current thread.
+a global (per-process) object.  There is a default policy, and an API
+to change the policy.  A policy defines the notion of context; a
+policy manages a separate event loop per context.  The default
+policy's notion of context is defined as the current thread.
 
 Certain platforms or programming frameworks may change the default
 policy to something more suitable to the expectations of the users of
 that platform or framework.  Such platforms or frameworks must
 document their policy and at what point during their initialization
-sequence the policy is set. in order to avoid undefined behavior when
+sequence the policy is set, in order to avoid undefined behavior when
 multiple active frameworks want to override the default policy.
 
-An event loop policy may but does not have to enforce that there is
-only one event loop in existence.  The default event loop policy does
-not enforce this, but it does enforce that there is only one event
-loop per thread (as far as ``get_event_loop()`` is concerned).
+To get the event loop for current context, use ``get_event_loop()``.
+This returns an event loop object implementing the interface specified
+below, or raises an exception in case no event loop has been set for
+the current context and the current policy does not specify to create
+one.  It should never return ``None``.
 
-To get the current event loop, use ``get_event_loop()``.  This returns
-an event loop object implementing the interface specified below, or
-``None`` in case no current event loop has been set and the current
-policy does not specify how to create one for the current context.  It
-is expected that ``get_event_loop()`` returns a different object
-depending on the context, and the default policy will only create a
-default event loop in the main thread; in other threads an event loop
-must be explicitly set (but other policies may behave differently).
-Event loop creation is lazy; i.e. the first call to
-``get_event_loop()`` creates an event loop instance if necessary and
-specified by the current policy.
+To set the event loop for the current context, use
+``set_event_loop(event_loop)``, where ``event_loop`` is an event loop
+object.  It is okay to set the current event loop to ``None``, in
+which case subsequent calls to ``get_event_loop()`` will raise an
+exception.  This is useful for testing code that should not depend on
+the existence of a default event loop.
 
-To set the current event loop, use ``set_event_loop(event_loop)``,
-where ``event_loop`` is an event loop object.  It is allowed to set
-the current event loop to ``None`` (although under the default policy,
-if the main thread's current event loop is set to ``None``, and
-``get_event_loop()`` is called subsequently, it will create a new
-event loop instance.
+It is expected that ``get_event_loop()`` returns a different event
+loop object depending on the context (in fact, this is the definition
+of context).  It may create a new event loop object if none is set and
+creation is allowed by the policy.  The default policy will create a
+new event loop only in the main thread, and only if
+``get_event_loop()`` is called before ``set_event_loop()`` is ever
+called.  (To reset this state, reset the policy.)  In other threads an
+event loop must be explicitly set.  Other policies may behave
+differently.  Event loop by the default policy creation is lazy;
+i.e. the first call to ``get_event_loop()`` creates an event loop
+instance if necessary and specified by the current policy.
 
 For the benefit of unit tests and other special cases there's a third
 policy function: ``new_event_loop()``, which creates and returns a new
 event loop object according to the policy's default rules.  To make
-this the current event loop, you must call ``set_event_loop()``.
+this the current event loop, you must call ``set_event_loop()`` with
+it.
 
-To change the event loop policy, call
-``set_event_loop_policy(policy)``, where ``policy`` is an event loop
-policy object or ``None``.  The policy object must be an object that
-has methods ``get_event_loop()``, ``set_event_loop(loop)`` and
+To change the event loop policy,
+call ``set_event_loop_policy(policy)``, where ``policy`` is an event
+loop policy object or ``None``.  The policy object must be an object
+that has methods ``get_event_loop()``, ``set_event_loop(loop)`` and
 ``new_event_loop()``, all behaving like the functions described above.
 Passing a policy value of ``None`` restores the default event loop
 policy (overriding the alternate default set by the platform or