Getting and Setting the Policy¶

The following functions can be used to get and set the policyfor the current process:

asyncio.get_event_loop_policy()¶

Return the current process-wide policy.

asyncio.set_event_loop_policy(policy)¶

Set the current process-wide policy topolicy.

Ifpolicy is set toNone, the default policy is restored.

Policy Objects¶

The abstract event loop policy base class is defined as follows:

classasyncio.AbstractEventLoopPolicy¶

An abstract base class for asyncio policies.

get_event_loop()¶

Get the event loop for the current context.

Return an event loop object implementing theAbstractEventLoop interface.

This method should never returnNone.

Changed in version 3.6.

set_event_loop(loop)¶

Set the event loop for the current context toloop.

new_event_loop()¶

Create and return a new event loop object.

This method should never returnNone.

get_child_watcher()¶

Get a child process watcher object.

Return a watcher object implementing theAbstractChildWatcher interface.

This function is Unix specific.

set_child_watcher(watcher)¶

Set the current child process watcher towatcher.

This function is Unix specific.

asyncio ships with the following built-in policies:

classasyncio.DefaultEventLoopPolicy¶

The default asyncio policy. UsesSelectorEventLoopon Unix andProactorEventLoop on Windows.

There is no need to install the default policy manually. asynciois configured to use the default policy automatically.

Changed in version 3.8:On Windows,ProactorEventLoop is now used by default.

Note

In Python versions 3.10.9, 3.11.1 and 3.12 theget_event_loop()method of the default asyncio policy emits aDeprecationWarningif there is no running event loop and no current loop is set.In some future Python release this will become an error.

classasyncio.WindowsSelectorEventLoopPolicy¶

An alternative event loop policy that uses theSelectorEventLoop event loop implementation.

Availability: Windows.

classasyncio.WindowsProactorEventLoopPolicy¶

An alternative event loop policy that uses theProactorEventLoop event loop implementation.

Availability: Windows.

Process Watchers¶

A process watcher allows customization of how an event loop monitorschild processes on Unix. Specifically, the event loop needs to knowwhen a child process has exited.

In asyncio, child processes are created withcreate_subprocess_exec() andloop.subprocess_exec()functions.

asyncio defines theAbstractChildWatcher abstract base class, which childwatchers should implement, and has four different implementations:ThreadedChildWatcher (configured to be used by default),MultiLoopChildWatcher,SafeChildWatcher, andFastChildWatcher.

See also theSubprocess and Threadssection.

The following two functions can be used to customize the child process watcherimplementation used by the asyncio event loop:

asyncio.get_child_watcher()¶

Return the current child watcher for the current policy.

asyncio.set_child_watcher(watcher)¶

Set the current child watcher towatcher for the currentpolicy.watcher must implement methods defined in theAbstractChildWatcher base class.

classasyncio.AbstractChildWatcher¶

add_child_handler(pid,callback,*args)¶

Register a new child handler.

Arrange forcallback(pid,returncode,*args) to be calledwhen a process with PID equal topid terminates. Specifyinganother callback for the same process replaces the previoushandler.

Thecallback callable must be thread-safe.

remove_child_handler(pid)¶

Removes the handler for process with PID equal topid.

The function returnsTrue if the handler was successfullyremoved,False if there was nothing to remove.

attach_loop(loop)¶

Attach the watcher to an event loop.

If the watcher was previously attached to an event loop, thenit is first detached before attaching to the new loop.

Note: loop may beNone.

is_active()¶

ReturnTrue if the watcher is ready to use.

Spawning a subprocess withinactive current child watcher raisesRuntimeError.

New in version 3.8.

close()¶

Close the watcher.

This method has to be called to ensure that underlyingresources are cleaned-up.

classasyncio.ThreadedChildWatcher¶

This implementation starts a new waiting thread for every subprocess spawn.

It works reliably even when the asyncio event loop is run in a non-main OS thread.

There is no noticeable overhead when handling a big number of children (O(1) eachtime a child terminates), but starting a thread per process requires extra memory.

This watcher is used by default.

New in version 3.8.

classasyncio.MultiLoopChildWatcher¶

This implementation registers aSIGCHLD signal handler oninstantiation. That can break third-party code that installs a custom handler forSIGCHLD signal.

The watcher avoids disrupting other code spawning processesby polling every process explicitly on aSIGCHLD signal.

There is no limitation for running subprocesses from different threads once thewatcher is installed.

The solution is safe but it has a significant overhead whenhandling a big number of processes (O(n) each time aSIGCHLD is received).

New in version 3.8.

classasyncio.SafeChildWatcher¶

This implementation uses active event loop from the main thread to handleSIGCHLD signal. If the main thread has no running event loop anotherthread cannot spawn a subprocess (RuntimeError is raised).

The watcher avoids disrupting other code spawning processesby polling every process explicitly on aSIGCHLD signal.

This solution is as safe asMultiLoopChildWatcher and has the sameO(n)complexity but requires a running event loop in the main thread to work.

classasyncio.FastChildWatcher¶

This implementation reaps every terminated processes by callingos.waitpid(-1) directly, possibly breaking other code spawningprocesses and waiting for their termination.

There is no noticeable overhead when handling a big number ofchildren (O(1) each time a child terminates).

This solution requires a running event loop in the main thread to work, asSafeChildWatcher.

classasyncio.PidfdChildWatcher¶

This implementation polls process file descriptors (pidfds) to await childprocess termination. In some respects,PidfdChildWatcher is a“Goldilocks” child watcher implementation. It doesn’t require signals orthreads, doesn’t interfere with any processes launched outside the eventloop, and scales linearly with the number of subprocesses launched by theevent loop. The main disadvantage is that pidfds are specific to Linux, andonly work on recent (5.3+) kernels.

New in version 3.9.

Custom Policies¶

To implement a new event loop policy, it is recommended to subclassDefaultEventLoopPolicy and override the methods for whichcustom behavior is wanted, e.g.:

classMyEventLoopPolicy(asyncio.DefaultEventLoopPolicy):defget_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 ...returnloopasyncio.set_event_loop_policy(MyEventLoopPolicy())