From 4135c89395726024abddb7340a0c7a42c801f616 Mon Sep 17 00:00:00 2001 From: Antoine Pitrou Date: Tue, 7 Nov 2017 10:26:32 +0100 Subject: [PATCH] bpo-31950: Improve event loop policy doc (#4306) --- Doc/library/asyncio-eventloops.rst | 33 +++++++++++++++++++++++++++--- 1 file changed, 30 insertions(+), 3 deletions(-) diff --git a/Doc/library/asyncio-eventloops.rst b/Doc/library/asyncio-eventloops.rst index d74fcb1e07f..7970e9039df 100644 --- a/Doc/library/asyncio-eventloops.rst +++ b/Doc/library/asyncio-eventloops.rst @@ -148,10 +148,9 @@ process based on the calling context. A policy is an object implementing the :class:`AbstractEventLoopPolicy` interface. For most users of :mod:`asyncio`, policies never have to be dealt with -explicitly, since the default global policy is sufficient. +explicitly, since the default global policy is sufficient (see below). -The default policy defines context as the current thread, and manages an event -loop per thread that interacts with :mod:`asyncio`. The module-level functions +The module-level functions :func:`get_event_loop` and :func:`set_event_loop` provide convenient access to event loops managed by the default policy. @@ -189,6 +188,13 @@ An event loop policy must implement the following interface: context, :meth:`set_event_loop` must be called explicitly. +The default policy defines context as the current thread, and manages an event +loop per thread that interacts with :mod:`asyncio`. If the current thread +doesn't already have an event loop associated with it, the default policy's +:meth:`~AbstractEventLoopPolicy.get_event_loop` method creates one when +called from the main thread, but raises :exc:`RuntimeError` otherwise. + + Access to the global loop policy -------------------------------- @@ -200,3 +206,24 @@ Access to the global loop policy Set the current event loop policy. If *policy* is ``None``, the default policy is restored. + + +Customizing the event loop policy +--------------------------------- + +To implement a new event loop policy, it is recommended you subclass the +concrete default event loop policy :class:`DefaultEventLoopPolicy` +and override the methods for which you want to change behavior, for example:: + + class MyEventLoopPolicy(asyncio.DefaultEventLoopPolicy): + + def get_event_loop(self): + """Get the event loop. + + This may be None or an instance of EventLoop. + """ + loop = super().get_event_loop() + # Do something with loop ... + return loop + + asyncio.set_event_loop_policy(MyEventLoopPolicy())