8000 GH-120804: add docs for removal for asyncio child watchers (#120895) · python/cpython@18b6ca9 · GitHub
[go: up one dir, main page]
Skip to content

Commit 18b6ca9

Browse files
kumaraditya303AlexWaygood
kumaraditya303
and
AlexWaygood
authored
GH-120804: add docs for removal for asyncio child watchers (#120895)
Co-authored-by: Alex Waygood <alex.waygood@gmail.com>
1 parent 9d2e1ea commit 18b6ca9

File tree

7 files changed

+31
-214
lines changed

7 files changed

+31
-214
lines changed

‎Doc/library/asyncio-platforms.rst

Lines changed: 0 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -77,11 +77,6 @@ Subprocess Support on Windows
7777
On Windows, the default event loop :class:`ProactorEventLoop` supports
7878
subprocesses, whereas :class:`SelectorEventLoop` does not.
7979

80-
The :meth:`policy.set_child_watcher()
81-
<AbstractEventLoopPolicy.set_child_watcher>` function is also
82-
not supported, as :class:`ProactorEventLoop` has a different mechanism
83-
to watch child processes.
84-
8580

8681
macOS
8782
=====

‎Doc/library/asyncio-policy.rst

Lines changed: 0 additions & 185 deletions
Original file line numberDiff line numberDiff line change
@@ -79,25 +79,6 @@ The abstract event loop policy base class is defined as follows:
7979

8080
This method should never return ``None``.
8181

82-
.. method:: get_child_watcher()
83-
84-
Get a child process watcher object.
85-
86-
Return a watcher object implementing the
87-
:class:`AbstractChildWatcher` interface.
88-
89-
This function is Unix specific.
90-
91-
.. deprecated:: 3.12
92-
93-
.. method:: set_child_watcher(watcher)
94-
95-
Set the current child process watcher to *watcher*.
96-
97-
This function is Unix specific.
98-
99-
.. deprecated:: 3.12
100-
10182

10283
.. _asyncio-policy-builtin:
10384

@@ -139,172 +120,6 @@ asyncio ships with the following built-in policies:
139120
.. availability:: Windows.
140121

141122

142-
.. _asyncio-watchers:
143-
144-
Process Watchers
145-
================
146-
147-
A process watcher allows customization of how an event loop monitors
148-
child processes on Unix. Specifically, the event loop needs to know
149-
when a child process has exited.
150-
151-
In asyncio, child processes are created with
152-
:func:`create_subprocess_exec` and :meth:`loop.subprocess_exec`
153-
functions.
154-
155-
asyncio defines the :class:`AbstractChildWatcher` abstract base class, which child
156-
watchers should implement, and has four different implementations:
157-
:class:`ThreadedChildWatcher` (configured to be used by default),
158-
:class:`MultiLoopChildWatcher`, :class:`SafeChildWatcher`, and
159-
:class:`FastChildWatcher`.
160-
161-
See also the :ref:`Subprocess and Threads <asyncio-subprocess-threads>`
162-
section.
163-
164-
The following two functions can be used to customize the child process watcher
165-
implementation used by the asyncio event loop:
166-
167-
.. function:: get_child_watcher()
168-
169-
Return the current child watcher for the current policy.
170-
171-
.. deprecated:: 3.12
172-
173-
.. function:: set_child_watcher(watcher)
174-
175-
Set the current child watcher to *watcher* for the current
176-
policy. *watcher* must implement methods defined in the
177-
:class:`AbstractChildWatcher` base class.
178-
179-
.. deprecated:: 3.12
180-
181-
.. note::
182-
Third-party event loops implementations might not support
183-
custom child watchers. For such event loops, using
184-
:func:`set_child_watcher` might be prohibited or have no effect.
185-
186-
.. class:: AbstractChildWatcher
187-
188-
.. method:: add_child_handler(pid, callback, *args)
189-
190-
Register a new child handler.
191-
192-
Arrange for ``callback(pid, returncode, *args)`` to be called
193-
when a process with PID equal to *pid* terminates. Specifying
194-
another callback for the same process replaces the previous
195-
handler.
196-
197-
The *callback* callable must be thread-safe.
198-
199-
.. method:: remove_child_handler(pid)
200-
201-
Removes the handler for process with PID equal to *pid*.
202-
203-
The function returns ``True`` if the handler was successfully
204-
removed, ``False`` if there was nothing to remove.
205-
206-
.. method:: attach_loop(loop)
207-
208-
Attach the watcher to an event loop.
209-
210-
If the watcher was previously attached to an event loop, then
211-
it is first detached before attaching to the new loop.
212-
213-
Note: loop may be ``None``.
214-
215-
.. method:: is_active()
216-
217-
Return ``True`` if the watcher is ready to use.
218-
219-
Spawning a subprocess with *inactive* current child watcher raises
220-
:exc:`RuntimeError`.
221-
222-
.. versionadded:: 3.8
223-
224-
.. method:: close()
225-
226-
Close the watcher.
227-
228-
This method has to be called to ensure that underlying
229-
resources are cleaned-up.
230-
231-
.. deprecated:: 3.12
232-
233-
234-
.. class:: ThreadedChildWatcher
235-
236-
This implementation starts a new waiting thread for every subprocess spawn.
237-
238-
It works reliably even when the asyncio event loop is run in a non-main OS thread.
239-
240-
There is no noticeable overhead when handling a big number of children (*O*\ (1) each
241-
time a child terminates), but starting a thread per process requires extra memory.
242-
243-
This watcher is used by default.
244-
245-
.. versionadded:: 3.8
246-
247-
.. class:: MultiLoopChildWatcher
248-
249-
This implementation registers a :py:data:`SIGCHLD` signal handler on
250-
instantiation. That can break third-party code that installs a custom handler for
251-
:py:data:`SIGCHLD` signal.
252-
253-
The watcher avoids disrupting other code spawning processes
254-
by polling every process explicitly on a :py:data:`SIGCHLD` signal.
255-
256-
There is no limitation for running subprocesses from different threads once the
257-
watcher is installed.
258-
259-
The solution is safe but it has a significant overhead when
260-
handling a big number of processes (*O*\ (*n*) each time a
261-
:py:data:`SIGCHLD` is received).
262-
263-
.. versionadded:: 3.8
264-
265-
.. deprecated:: 3.12
266-
267-
.. class:: SafeChildWatcher
268-
269-
This implementation uses active event loop from the main thread to handle
270-
:py:data:`SIGCHLD` signal. If the main thread has no running event loop another
271-
thread cannot spawn a subprocess (:exc:`RuntimeError` is raised).
272-
273-
The watcher avoids disrupting other code spawning processes
274-
by polling every process explicitly on a :py:data:`SIGCHLD` signal.
275-
276-
This solution is as safe as :class:`MultiLoopChildWatcher` and has the same *O*\ (*n*)
277-
complexity but requires a running event loop in the main thread to work.
278-
279-
.. deprecated:: 3.12
280-
281-
.. class:: FastChildWatcher
282-
283-
This implementation reaps every terminated processes by calling
284-
``os.waitpid(-1)`` directly, possibly breaking other code spawning
285-
processes and waiting for their termination.
286-
287-
There is no noticeable overhead when handling a big number of
288-
children (*O*\ (1) each time a child terminates).
289-
290-
This solution requires a running event loop in the main thread to work, as
291-
:class:`SafeChildWatcher`.
292-
293-
.. deprecated:: 3.12
294-
295-
.. class:: PidfdChildWatcher
296-
297-
This implementation polls process file descriptors (pidfds) to await child
298-
process termination. In some respects, :class:`PidfdChildWatcher` is a
299-
"Goldilocks" child watcher implementation. It doesn't require signals or
300-
threads, doesn't interfere with any processes launched outside the event
301-
loop, and scales linearly with the number of subprocesses launched by the
302-
event loop. The main disadvantage is that pidfds are specific to Linux, and
303-
only work on recent (5.3+) kernels.
304-
305-
.. versionadded:: 3.9
306-
307-
308123
.. _asyncio-custom-policies:
309124

310125
Custom Policies

‎Doc/library/asyncio-subprocess.rst

Lines changed: 0 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -316,18 +316,6 @@ default.
316316
On Windows subprocesses are provided by :class:`ProactorEventLoop` only (default),
317317
:class:`SelectorEventLoop` has no subprocess support.
318318

319-
On UNIX *child watchers* are used for subprocess finish waiting, see
320-
:ref:`asyncio-watchers` for more info.
321-
322-
323-
.. versionchanged:: 3.8
324-
325-
UNIX switched to use :class:`ThreadedChildWatcher` for spawning subprocesses from
326-
different threads without any limitation.
327-
328-
Spawning a subprocess with *inactive* current child watcher raises
329-
:exc:`RuntimeError`.
330-
331319
Note that alternative event loop implementations might have own limitations;
332320
please refer to their documentation.
333321

‎Doc/tools/.nitignore

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,6 @@ Doc/howto/descriptor.rst
1717
Doc/howto/enum.rst
1818
Doc/library/ast.rst
1919
Doc/library/asyncio-extending.rst
20-
Doc/library/asyncio-policy.rst
2120
Doc/library/asyncio-subprocess.rst
2221
Doc/library/collections.rst
2322
Doc/library/dbm.rst

‎Doc/whatsnew/3.12.rst

Lines changed: 10 additions & 10 deletions
* :mod:`asyncio`:
Original file line numberDiff line numberDiff line change
@@ -652,14 +652,14 @@ asyncio
652652
making some use-cases 2x to 5x faster.
653653
(Contributed by Jacob Bower & Itamar Oren in :gh:`102853`, :gh:`104140`, and :gh:`104138`)
654654

655-
* On Linux, :mod:`asyncio` uses :class:`asyncio.PidfdChildWatcher` by default
655+
* On Linux, :mod:`asyncio` uses :class:`!asyncio.PidfdChildWatcher` by default
656656
if :func:`os.pidfd_open` is available and functional instead of
657-
:class:`asyncio.ThreadedChildWatcher`.
657+
:class:`!asyncio.ThreadedChildWatcher`.
658658
(Contributed by Kumar Aditya in :gh:`98024`.)
659659

660660
* The event loop now uses the best available child watcher for each platform
661-
(:class:`asyncio.PidfdChildWatcher` if supported and
662-
:class:`asyncio.ThreadedChildWatcher` otherwise), so manually
661+
(:class:`!asyncio.PidfdChildWatcher` if supported and
662+
:class:`!asyncio.ThreadedChildWatcher` otherwise), so manually
663663
configuring a child watcher is not recommended.
664664
(Contributed by Kumar Aditya in :gh:`94597`.)
665665

@@ -1162,15 +1162,15 @@ Deprecated
11621162

11631163
11641164

1165-
* The child watcher classes :class:`asyncio.MultiLoopChildWatcher`,
1166-
:class:`asyncio.FastChildWatcher`, :class:`asyncio.AbstractChildWatcher`
1167-
and :class:`asyncio.SafeChildWatcher` are deprecated and
1165+
* The child watcher classes :class:`!asyncio.MultiLoopChildWatcher`,
1166+
:class:`!asyncio.FastChildWatcher`, :class:`!asyncio.AbstractChildWatcher`
1167+
and :class:`!asyncio.SafeChildWatcher` are deprecated and
11681168
will be removed in Python 3.14.
11691169
(Contributed by Kumar Aditya in :gh:`94597`.)
11701170

1171-
* :func:`asyncio.set_child_watcher`, :func:`asyncio.get_child_watcher`,
1172-
:meth:`asyncio.AbstractEventLoopPolicy.set_child_watcher` and
1173-
:meth:`asyncio.AbstractEventLoopPolicy.get_child_watcher` are deprecated
1171+
* :func:`!asyncio.set_child_watcher`, :func:`!asyncio.get_child_watcher`,
1172+
:meth:`!asyncio.AbstractEventLoopPolicy.set_child_watcher` and
1173+
:meth:`!asyncio.AbstractEventLoopPolicy.get_child_watcher` are deprecated
11741174
and will be removed in Python 3.14.
11751175
(Contributed by Kumar Aditya in :gh:`94597`.)
11761176

‎Doc/whatsnew/3.14.rst

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -173,6 +173,26 @@ ast
173173

174174
(Contributed by Alex Waygood in :gh:`119562`.)
175175

176+
asyncio
177+
-------
178+
179+
* Remove the following classes and functions. They were all deprecated and
180+
emitted deprecation warnings since Python 3.12:
181+
182+
* :class:`!asyncio.AbstractChildWatcher`
183+
* :class:`!asyncio.SafeChildWatcher`
184+
* :class:`!asyncio.MultiLoopChildWatcher`
185+
* :class:`!asyncio.FastChildWatcher`
186+
* :class:`!asyncio.ThreadedChildWatcher`
187+
* :class:`!asyncio.PidfdChildWatcher`
188+
* :meth:`!asyncio.AbstractEventLoopPolicy.get_child_watcher`
189+
* :meth:`!asyncio.AbstractEventLoopPolicy.set_child_watcher`
190+
* :func:`!asyncio.get_child_watcher`
191+
* :func:`!asyncio.set_child_watcher`
192+
193+
(Contributed by Kumar Aditya in :gh:`120804`.)
194+
195+
176196
collections.abc
177197
---------------
178198

‎Doc/whatsnew/3.9.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -352,7 +352,7 @@ that schedules a shutdown for the default executor that waits on the
352352
:func:`asyncio.run` has been updated to use the new :term:`coroutine`.
353353
(Contributed by Kyle Stanley in :issue:`34037`.)
354354

355-
Added :class:`asyncio.PidfdChildWatcher`, a Linux-specific child watcher
355+
Added :class:`!asyncio.PidfdChildWatcher`, a Linux-specific child watcher
356356
implementation that polls process file descriptors. (:issue:`38692`)
357357

358358
Added a new :term:`coroutine` :func:`asyncio.to_thread`. It is mainly used for

0 commit comments

Comments
 (0)
0