https://github.com/python/cpython/commit/b8c313a41c411331c603bbda28048b2a3f4a2ab4 commit: b8c313a41c411331c603bbda28048b2a3f4a2ab4 branch: main author: Bénédikt Tran <[email protected]> committer: picnixz <[email protected]> date: 2025-02-23T10:35:08+01:00 summary:
gh-84559: improve What's New entry for `multiprocessing` start method changes (#128173) Co-authored-by: Gregory P. Smith <[email protected]> Co-authored-by: Stan Ulbrych <[email protected]> files: M Doc/library/multiprocessing.rst M Doc/whatsnew/3.14.rst diff --git a/Doc/library/multiprocessing.rst b/Doc/library/multiprocessing.rst index 783cb025826483..1b1c6d74e5197c 100644 --- a/Doc/library/multiprocessing.rst +++ b/Doc/library/multiprocessing.rst @@ -107,6 +107,8 @@ Contexts and start methods Depending on the platform, :mod:`multiprocessing` supports three ways to start a process. These *start methods* are + .. _multiprocessing-start-method-spawn: + *spawn* The parent process starts a fresh Python interpreter process. The child process will only inherit those resources necessary to run @@ -117,6 +119,8 @@ to start a process. These *start methods* are Available on POSIX and Windows platforms. The default on Windows and macOS. + .. _multiprocessing-start-method-fork: + *fork* The parent process uses :func:`os.fork` to fork the Python interpreter. The child process, when it begins, is effectively @@ -137,6 +141,8 @@ to start a process. These *start methods* are raise a :exc:`DeprecationWarning`. Use a different start method. See the :func:`os.fork` documentation for further explanation. + .. _multiprocessing-start-method-forkserver: + *forkserver* When the program starts and selects the *forkserver* start method, a server process is spawned. From then on, whenever a new process @@ -2987,6 +2993,9 @@ Beware of replacing :data:`sys.stdin` with a "file like object" For more information, see :issue:`5155`, :issue:`5313` and :issue:`5331` +.. _multiprocessing-programming-spawn: +.. _multiprocessing-programming-forkserver: + The *spawn* and *forkserver* start methods ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/Doc/whatsnew/3.14.rst b/Doc/whatsnew/3.14.rst index eee9bc865357ee..930fe718ac580a 100644 --- a/Doc/whatsnew/3.14.rst +++ b/Doc/whatsnew/3.14.rst @@ -70,6 +70,22 @@ Summary -- release highlights * :ref:`A new type of interpreter <whatsnew314-tail-call>` +Incompatible changes +==================== + +On platforms other than macOS and Windows, the default :ref:`start +method <multiprocessing-start-methods>` for :mod:`multiprocessing` +and :class:`~concurrent.futures.ProcessPoolExecutor` switches from +*fork* to *forkserver*. + +See :ref:`(1) <whatsnew314-concurrent-futures-start-method>` and +:ref:`(2) <whatsnew314-multiprocessing-start-method>` for details. + +If you encounter :exc:`NameError`\s or pickling errors coming out of +:mod:`multiprocessing` or :mod:`concurrent.futures`, see the +:ref:`forkserver restrictions <multiprocessing-programming-forkserver>`. + + New features ============ @@ -396,12 +412,26 @@ concurrent.futures same process) to Python code. This is separate from the proposed API in :pep:`734`. (Contributed by Eric Snow in :gh:`124548`.) -* The default ``ProcessPoolExecutor`` start method (see - :ref:`multiprocessing-start-methods`) changed from *fork* to *forkserver* on - platforms other than macOS & Windows. If you require the threading - incompatible *fork* start method you must explicitly request it by - supplying a *mp_context* to :class:`concurrent.futures.ProcessPoolExecutor`. - (Contributed by Gregory P. Smith in :gh:`84559`.) + +.. _whatsnew314-concurrent-futures-start-method: + +* The default :class:`~concurrent.futures.ProcessPoolExecutor` + :ref:`start method <multiprocessing-start-methods>` changed + from :ref:`fork <multiprocessing-start-method-fork>` to :ref:`forkserver + <multiprocessing-start-method-forkserver>` on platforms other than macOS and + Windows where it was already :ref:`spawn <multiprocessing-start-method-spawn>`. + + If the threading incompatible *fork* method is required, you must explicitly + request it by supplying a multiprocessing context *mp_context* to + :class:`~concurrent.futures.ProcessPoolExecutor`. + + See :ref:`forkserver restrictions <multiprocessing-programming-forkserver>` + for information and differences with the *fork* method and how this change + may affect existing code with mutable global shared variables and/or shared + objects that can not be automatically :mod:`pickled <pickle>`. + + (Contributed by Gregory P. Smith in :gh:`84559`.) + contextvars ----------- @@ -637,18 +667,30 @@ mimetypes multiprocessing --------------- -* The default start method (see :ref:`multiprocessing-start-methods`) changed - from *fork* to *forkserver* on platforms other than macOS & Windows where - it was already *spawn*. If you require the threading incompatible *fork* - start method you must explicitly request it using a context from - :func:`multiprocessing.get_context` (preferred) or change the default via - :func:`multiprocessing.set_start_method`. +.. _whatsnew314-multiprocessing-start-method: + +* The default :ref:`start method <multiprocessing-start-methods>` changed + from :ref:`fork <multiprocessing-start-method-fork>` to :ref:`forkserver + <multiprocessing-start-method-forkserver>` on platforms other than macOS and + Windows where it was already :ref:`spawn <multiprocessing-start-method-spawn>`. + + If the threading incompatible *fork* method is required, you must explicitly + request it via a context from :func:`multiprocessing.get_context` (preferred) + or change the default via :func:`multiprocessing.set_start_method`. + + See :ref:`forkserver restrictions <multiprocessing-programming-forkserver>` + for information and differences with the *fork* method and how this change + may affect existing code with mutable global shared variables and/or shared + objects that can not be automatically :mod:`pickled <pickle>`. + (Contributed by Gregory P. Smith in :gh:`84559`.) + * :mod:`multiprocessing`'s ``"forkserver"`` start method now authenticates its control socket to avoid solely relying on filesystem permissions to restrict what other processes could cause the forkserver to spawn workers and run code. (Contributed by Gregory P. Smith for :gh:`97514`.) + * The :ref:`multiprocessing proxy objects <multiprocessing-proxy_objects>` for *list* and *dict* types gain previously overlooked missing methods: _______________________________________________ Python-checkins mailing list -- [email protected] To unsubscribe send an email to [email protected] https://mail.python.org/mailman3/lists/python-checkins.python.org/ Member address: [email protected]
