[3.12] gh-100228: Document the os.fork threads DeprecationWarning. (G…

…H-109767) (#109773)

* gh-100228: Document the os.fork threads DeprecationWarning. (GH-109767)

Document the `os.fork` posix threads detected `DeprecationWarning` in 3.12 What's New, os, multiprocessing, and concurrent.futures docs.

Many reviews and doc cleanup edits by Adam & Hugo. 🥳

(cherry picked from commit 5e7ea95d9d5c3b80a67ffbeebd76ce4fc327dd8e)

Co-authored-by: Gregory P. Smith <greg@krypto.org>
Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>

* link to the discussion thread from whatsnew

Include the link to the discussion in the what's new text per @malemberg's comment on. python/cpython#109767

(i'll follow up with a PR to main to include this edit there as well)

---------

Co-authored-by: Gregory P. Smith <greg@krypto.org>
Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>

CPython-sync-commit: 62df559448362f9a4291661d64aee30474dec025

.pot/library/concurrent.futures.pot

@@ -8,7 +8,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: Python 3.12\n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2023-06-21 00:18+0200\n"
+"POT-Creation-Date: 2023-09-24 21:54+0000\n"
 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
 "Language-Team: LANGUAGE <LL@li.org>\n"
@@ -201,197 +201,201 @@ msgstr ""
 msgid "The *max_tasks_per_child* argument was added to allow users to control the lifetime of workers in the pool."
 msgstr ""
 
-#: ../../library/concurrent.futures.rst:299
+#: ../../library/concurrent.futures.rst:296
+msgid "On POSIX systems, if your application has multiple threads and the :mod:`multiprocessing` context uses the ``\"fork\"`` start method: The :func:`os.fork` function called internally to spawn workers may raise a :exc:`DeprecationWarning`. Pass a *mp_context* configured to use a different start method. See the :func:`os.fork` documentation for further explanation."
+msgstr ""
+
+#: ../../library/concurrent.futures.rst:307
 msgid "ProcessPoolExecutor Example"
 msgstr ""
 
-#: ../../library/concurrent.futures.rst:337
+#: ../../library/concurrent.futures.rst:345
 msgid "Future Objects"
 msgstr ""
 
-#: ../../library/concurrent.futures.rst:339
+#: ../../library/concurrent.futures.rst:347
 msgid "The :class:`Future` class encapsulates the asynchronous execution of a callable. :class:`Future` instances are created by :meth:`Executor.submit`."
 msgstr ""
 
-#: ../../library/concurrent.futures.rst:344
+#: ../../library/concurrent.futures.rst:352
 msgid "Encapsulates the asynchronous execution of a callable.  :class:`Future` instances are created by :meth:`Executor.submit` and should not be created directly except for testing."
 msgstr ""
 
-#: ../../library/concurrent.futures.rst:350
+#: ../../library/concurrent.futures.rst:358
 msgid "Attempt to cancel the call.  If the call is currently being executed or finished running and cannot be cancelled then the method will return ``False``, otherwise the call will be cancelled and the method will return ``True``."
 msgstr ""
 
-#: ../../library/concurrent.futures.rst:357
+#: ../../library/concurrent.futures.rst:365
 msgid "Return ``True`` if the call was successfully cancelled."
 msgstr ""
 
-#: ../../library/concurrent.futures.rst:361
+#: ../../library/concurrent.futures.rst:369
 msgid "Return ``True`` if the call is currently being executed and cannot be cancelled."
 msgstr ""
 
-#: ../../library/concurrent.futures.rst:366
+#: ../../library/concurrent.futures.rst:374
 msgid "Return ``True`` if the call was successfully cancelled or finished running."
 msgstr ""
 
-#: ../../library/concurrent.futures.rst:371
+#: ../../library/concurrent.futures.rst:379
 msgid "Return the value returned by the call. If the call hasn't yet completed then this method will wait up to *timeout* seconds.  If the call hasn't completed in *timeout* seconds, then a :exc:`TimeoutError` will be raised. *timeout* can be an int or float.  If *timeout* is not specified or ``None``, there is no limit to the wait time."
 msgstr ""
 
-#: ../../library/concurrent.futures.rst:378
-#: ../../library/concurrent.futures.rst:392
+#: ../../library/concurrent.futures.rst:386
+#: ../../library/concurrent.futures.rst:400
 msgid "If the future is cancelled before completing then :exc:`.CancelledError` will be raised."
 msgstr ""
 
-#: ../../library/concurrent.futures.rst:381
+#: ../../library/concurrent.futures.rst:389
 msgid "If the call raised an exception, this method will raise the same exception."
 msgstr ""
 
-#: ../../library/concurrent.futures.rst:385
+#: ../../library/concurrent.futures.rst:393
 msgid "Return the exception raised by the call.  If the call hasn't yet completed then this method will wait up to *timeout* seconds.  If the call hasn't completed in *timeout* seconds, then a :exc:`TimeoutError` will be raised.  *timeout* can be an int or float.  If *timeout* is not specified or ``None``, there is no limit to the wait time."
 msgstr ""
 
-#: ../../library/concurrent.futures.rst:395
+#: ../../library/concurrent.futures.rst:403
 msgid "If the call completed without raising, ``None`` is returned."
 msgstr ""
 
-#: ../../library/concurrent.futures.rst:399
+#: ../../library/concurrent.futures.rst:407
 msgid "Attaches the callable *fn* to the future.  *fn* will be called, with the future as its only argument, when the future is cancelled or finishes running."
 msgstr ""
 
-#: ../../library/concurrent.futures.rst:403
+#: ../../library/concurrent.futures.rst:411
 msgid "Added callables are called in the order that they were added and are always called in a thread belonging to the process that added them.  If the callable raises an :exc:`Exception` subclass, it will be logged and ignored.  If the callable raises a :exc:`BaseException` subclass, the behavior is undefined."
 msgstr ""
 
-#: ../../library/concurrent.futures.rst:409
+#: ../../library/concurrent.futures.rst:417
 msgid "If the future has already completed or been cancelled, *fn* will be called immediately."
 msgstr ""
 
-#: ../../library/concurrent.futures.rst:412
+#: ../../library/concurrent.futures.rst:420
 msgid "The following :class:`Future` methods are meant for use in unit tests and :class:`Executor` implementations."
 msgstr ""
 
-#: ../../library/concurrent.futures.rst:417
+#: ../../library/concurrent.futures.rst:425
 msgid "This method should only be called by :class:`Executor` implementations before executing the work associated with the :class:`Future` and by unit tests."
 msgstr ""
 
-#: ../../library/concurrent.futures.rst:421
+#: ../../library/concurrent.futures.rst:429
 msgid "If the method returns ``False`` then the :class:`Future` was cancelled, i.e. :meth:`Future.cancel` was called and returned ``True``.  Any threads waiting on the :class:`Future` completing (i.e. through :func:`as_completed` or :func:`wait`) will be woken up."
 msgstr ""
 
-#: ../../library/concurrent.futures.rst:426
+#: ../../library/concurrent.futures.rst:434
 msgid "If the method returns ``True`` then the :class:`Future` was not cancelled and has been put in the running state, i.e. calls to :meth:`Future.running` will return ``True``."
 msgstr ""
 
-#: ../../library/concurrent.futures.rst:430
+#: ../../library/concurrent.futures.rst:438
 msgid "This method can only be called once and cannot be called after :meth:`Future.set_result` or :meth:`Future.set_exception` have been called."
 msgstr ""
 
-#: ../../library/concurrent.futures.rst:436
+#: ../../library/concurrent.futures.rst:444
 msgid "Sets the result of the work associated with the :class:`Future` to *result*."
 msgstr ""
 
-#: ../../library/concurrent.futures.rst:439
-#: ../../library/concurrent.futures.rst:452
+#: ../../library/concurrent.futures.rst:447
+#: ../../library/concurrent.futures.rst:460
 msgid "This method should only be used by :class:`Executor` implementations and unit tests."
 msgstr ""
 
-#: ../../library/concurrent.futures.rst:442
-#: ../../library/concurrent.futures.rst:455
+#: ../../library/concurrent.futures.rst:450
+#: ../../library/concurrent.futures.rst:463
 msgid "This method raises :exc:`concurrent.futures.InvalidStateError` if the :class:`Future` is already done."
 msgstr ""
 
-#: ../../library/concurrent.futures.rst:449
+#: ../../library/concurrent.futures.rst:457
 msgid "Sets the result of the work associated with the :class:`Future` to the :class:`Exception` *exception*."
 msgstr ""
 
-#: ../../library/concurrent.futures.rst:461
+#: ../../library/concurrent.futures.rst:469
 msgid "Module Functions"
 msgstr ""
 
-#: ../../library/concurrent.futures.rst:465
+#: ../../library/concurrent.futures.rst:473
 msgid "Wait for the :class:`Future` instances (possibly created by different :class:`Executor` instances) given by *fs* to complete. Duplicate futures given to *fs* are removed and will be returned only once. Returns a named 2-tuple of sets.  The first set, named ``done``, contains the futures that completed (finished or cancelled futures) before the wait completed.  The second set, named ``not_done``, contains the futures that did not complete (pending or running futures)."
 msgstr ""
 
-#: ../../library/concurrent.futures.rst:473
+#: ../../library/concurrent.futures.rst:481
 msgid "*timeout* can be used to control the maximum number of seconds to wait before returning.  *timeout* can be an int or float.  If *timeout* is not specified or ``None``, there is no limit to the wait time."
 msgstr ""
 
-#: ../../library/concurrent.futures.rst:477
+#: ../../library/concurrent.futures.rst:485
 msgid "*return_when* indicates when this function should return.  It must be one of the following constants:"
 msgstr ""
 
-#: ../../library/concurrent.futures.rst:483
+#: ../../library/concurrent.futures.rst:491
 msgid "Constant"
 msgstr ""
 
-#: ../../library/concurrent.futures.rst:483
+#: ../../library/concurrent.futures.rst:491
 msgid "Description"
 msgstr ""
 
-#: ../../library/concurrent.futures.rst:485
+#: ../../library/concurrent.futures.rst:493
 msgid ":const:`FIRST_COMPLETED`"
 msgstr ""
 
-#: ../../library/concurrent.futures.rst:485
+#: ../../library/concurrent.futures.rst:493
 msgid "The function will return when any future finishes or is cancelled."
 msgstr ""
 
-#: ../../library/concurrent.futures.rst:488
+#: ../../library/concurrent.futures.rst:496
 msgid ":const:`FIRST_EXCEPTION`"
 msgstr ""
 
-#: ../../library/concurrent.futures.rst:488
+#: ../../library/concurrent.futures.rst:496
 msgid "The function will return when any future finishes by raising an exception.  If no future raises an exception then it is equivalent to :const:`ALL_COMPLETED`."
 msgstr ""
 
-#: ../../library/concurrent.futures.rst:494
+#: ../../library/concurrent.futures.rst:502
 msgid ":const:`ALL_COMPLETED`"
 msgstr ""
 
-#: ../../library/concurrent.futures.rst:494
+#: ../../library/concurrent.futures.rst:502
 msgid "The function will return when all futures finish or are cancelled."
 msgstr ""
 
-#: ../../library/concurrent.futures.rst:500
+#: ../../library/concurrent.futures.rst:508
 msgid "Returns an iterator over the :class:`Future` instances (possibly created by different :class:`Executor` instances) given by *fs* that yields futures as they complete (finished or cancelled futures). Any futures given by *fs* that are duplicated will be returned once. Any futures that completed before :func:`as_completed` is called will be yielded first.  The returned iterator raises a :exc:`TimeoutError` if :meth:`~iterator.__next__` is called and the result isn't available after *timeout* seconds from the original call to :func:`as_completed`.  *timeout* can be an int or float. If *timeout* is not specified or ``None``, there is no limit to the wait time."
 msgstr ""
 
-#: ../../library/concurrent.futures.rst:514
+#: ../../library/concurrent.futures.rst:522
 msgid ":pep:`3148` -- futures - execute computations asynchronously"
 msgstr ""
 
-#: ../../library/concurrent.futures.rst:514
+#: ../../library/concurrent.futures.rst:522
 msgid "The proposal which described this feature for inclusion in the Python standard library."
 msgstr ""
 
-#: ../../library/concurrent.futures.rst:519
+#: ../../library/concurrent.futures.rst:527
 msgid "Exception classes"
 msgstr ""
 
-#: ../../library/concurrent.futures.rst:525
+#: ../../library/concurrent.futures.rst:533
 msgid "Raised when a future is cancelled."
 msgstr ""
 
-#: ../../library/concurrent.futures.rst:529
+#: ../../library/concurrent.futures.rst:537
 msgid "A deprecated alias of :exc:`TimeoutError`, raised when a future operation exceeds the given timeout."
 msgstr ""
 
-#: ../../library/concurrent.futures.rst:534
+#: ../../library/concurrent.futures.rst:542
 msgid "This class was made an alias of :exc:`TimeoutError`."
 msgstr ""
 
-#: ../../library/concurrent.futures.rst:539
+#: ../../library/concurrent.futures.rst:547
 msgid "Derived from :exc:`RuntimeError`, this exception class is raised when an executor is broken for some reason, and cannot be used to submit or execute new tasks."
 msgstr ""
 
-#: ../../library/concurrent.futures.rst:547
+#: ../../library/concurrent.futures.rst:555
 msgid "Raised when an operation is performed on a future that is not allowed in the current state."
 msgstr ""
 
-#: ../../library/concurrent.futures.rst:556
+#: ../../library/concurrent.futures.rst:564
 msgid "Derived from :exc:`~concurrent.futures.BrokenExecutor`, this exception class is raised when one of the workers of a :class:`ThreadPoolExecutor` has failed initializing."
 msgstr ""
 
-#: ../../library/concurrent.futures.rst:566
+#: ../../library/concurrent.futures.rst:574
 msgid "Derived from :exc:`~concurrent.futures.BrokenExecutor` (formerly :exc:`RuntimeError`), this exception class is raised when one of the workers of a :class:`ProcessPoolExecutor` has terminated in a non-clean fashion (for example, if it was killed from the outside)."
 msgstr ""