Skip to content

Commit 306a21f

Browse files
committed
Doc: Explain that multiprocessing only supports unpicklable functions through the fork method
In multiprocessing and concurrent.futures's documentations, as well as the release notes for Python 3.14. This moves the paragraph in 3.14's release notes from the deprecations section to 'Porting to Python 3.14' because it is a breaking change, which follows a deprecation in Python 3.12. This explicitly mentions `PicklingError` in this section, so it is easy to find for somehow who gets the error and searches its name through the page.
1 parent e924bb6 commit 306a21f

File tree

3 files changed

+22
-9
lines changed

3 files changed

+22
-9
lines changed

Doc/library/concurrent.futures.rst

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -412,7 +412,8 @@ to a :class:`ProcessPoolExecutor` will result in deadlock.
412412
.. versionchanged:: 3.14
413413
The default process start method (see
414414
:ref:`multiprocessing-start-methods`) changed away from *fork*. If you
415-
require the *fork* start method for :class:`ProcessPoolExecutor` you must
415+
require the *fork* start method for :class:`ProcessPoolExecutor` or need to run
416+
:ref:`unpicklable functions <pickle-picklable>`, you must
416417
explicitly pass ``mp_context=multiprocessing.get_context("fork")``.
417418

418419
.. _processpoolexecutor-example:

Doc/library/multiprocessing.rst

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -115,6 +115,8 @@ to start a process. These *start methods* are
115115
will not be inherited. Starting a process using this method is
116116
rather slow compared to using *fork* or *forkserver*.
117117

118+
Functions run with this method must be :ref:`picklable <pickle-picklable>`.
119+
118120
Available on POSIX and Windows platforms. The default on Windows and macOS.
119121

120122
*fork*
@@ -124,6 +126,9 @@ to start a process. These *start methods* are
124126
inherited by the child process. Note that safely forking a
125127
multithreaded process is problematic.
126128

129+
Functions run with this method do *not* need to be
130+
:ref:`picklable <pickle-picklable>`.
131+
127132
Available on POSIX systems.
128133

129134
.. versionchanged:: 3.14
@@ -146,6 +151,8 @@ to start a process. These *start methods* are
146151
side-effect so it is generally safe for it to use :func:`os.fork`.
147152
No unnecessary resources are inherited.
148153

154+
Functions run with this method must be :ref:`picklable <pickle-picklable>`.
155+
149156
Available on POSIX platforms which support passing file descriptors over
150157
Unix pipes such as Linux. The default on those.
151158

Doc/whatsnew/3.14.rst

Lines changed: 13 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -451,14 +451,6 @@ Deprecated
451451
as a single positional argument.
452452
(Contributed by Serhiy Storchaka in :gh:`109218`.)
453453

454-
* :mod:`multiprocessing` and :mod:`concurrent.futures`:
455-
The default start method (see :ref:`multiprocessing-start-methods`) changed
456-
away from *fork* to *forkserver* on platforms where it was not already
457-
*spawn* (Windows & macOS). If you require the threading incompatible *fork*
458-
start method you must explicitly specify it when using :mod:`multiprocessing`
459-
or :mod:`concurrent.futures` APIs.
460-
(Contributed by Gregory P. Smith in :gh:`84559`.)
461-
462454
* :mod:`os`:
463455
:term:`Soft deprecate <soft deprecated>` :func:`os.popen` and
464456
:func:`os.spawn* <os.spawnl>` functions. They should no longer be used to
@@ -625,6 +617,8 @@ Others
625617
:meth:`~object.__index__`. (Contributed by Mark Dickinson in :gh:`119743`.)
626618

627619

620+
.. _whatsnew314-porting-to-python314:
621+
628622
Porting to Python 3.14
629623
======================
630624

@@ -643,6 +637,17 @@ Changes in the Python API
643637
This temporary change affects other threads.
644638
(Contributed by Serhiy Storchaka in :gh:`69998`.)
645639

640+
* :mod:`multiprocessing` and :mod:`concurrent.futures`:
641+
The default start method (see :ref:`multiprocessing-start-methods`) changed
642+
away from *fork* to *forkserver* on platforms where it was not already
643+
*spawn* (Windows & macOS). If you require the threading incompatible *fork*,
644+
which can run :ref:`unpicklable functions <pickle-picklable>`,
645+
start method you must explicitly specify it when using :mod:`multiprocessing`
646+
or :mod:`concurrent.futures` APIs.
647+
Code running pickable functions on these platforms without explicitly opting
648+
into the *fork* method will now raise :exc:`pickle.PicklingError`.
649+
(Contributed by Gregory P. Smith in :gh:`84559`.)
650+
646651

647652
Build changes
648653
=============

0 commit comments

Comments
 (0)