[3.14] gh-85222: Document the global start method side effect in multiprocessing (GH-136426) (#142770)

gh-85222: Document the global start method side effect in multiprocessing (GH-136426)

* Document the ctx parameter in some types in multiprocessing.
* Reduce duplication while still linking to the central explanation from API points with the side effect.
(cherry picked from commit 0978b9a)

Co-authored-by: AN Long <[email protected]>
Co-authored-by: Carol Willing <[email protected]>
Co-authored-by: R Chintan Meher <[email protected]>

Author: 4 people

Doc/library/multiprocessing.rst

@@ -521,6 +521,21 @@ Reference
 The :mod:`multiprocessing` package mostly replicates the API of the
 :mod:`threading` module.
 
+.. _global-start-method:
+
+Global start method
+^^^^^^^^^^^^^^^^^^^
+
+Python supports several ways to create and initialize a process.
+The global start method sets the default mechanism for creating a process.
+
+Several multiprocessing functions and methods that may also instantiate
+certain objects will implicitly set the global start method to the system's default,
+if it hasn’t been set already. The global start method can only be set once.
+If you need to change the start method from the system default, you must
+proactively set the global start method before calling functions or methods,
+or creating these objects.
+
 
 :class:`Process` and exceptions
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -910,6 +925,9 @@ For an example of the usage of queues for interprocess communication see
    locks/semaphores.  When a process first puts an item on the queue a feeder
    thread is started which transfers objects from a buffer into the pipe.
 
+   Instantiating this class may set the global start method. See
+   :ref:`global-start-method` for more details.
+
    The usual :exc:`queue.Empty` and :exc:`queue.Full` exceptions from the
    standard library's :mod:`queue` module are raised to signal timeouts.
 
@@ -1025,6 +1043,9 @@ For an example of the usage of queues for interprocess communication see
 
    It is a simplified :class:`Queue` type, very close to a locked :class:`Pipe`.
 
+   Instantiating this class may set the global start method. See
+   :ref:`global-start-method` for more details.
+
    .. method:: close()
 
       Close the queue: release internal resources.
@@ -1055,6 +1076,9 @@ For an example of the usage of queues for interprocess communication see
    :class:`JoinableQueue`, a :class:`Queue` subclass, is a queue which
    additionally has :meth:`task_done` and :meth:`join` methods.
 
+   Instantiating this class may set the global start method. See
+   :ref:`global-start-method` for more details.
+
    .. method:: task_done()
 
       Indicate that a formerly enqueued task is complete. Used by queue
@@ -1167,8 +1191,8 @@ Miscellaneous
    :mod:`multiprocessing` module.
 
    If *method* is ``None`` then the default context is returned. Note that if
-   the global start method has not been set, this will set it to the
-   default method.
+   the global start method has not been set, this will set it to the system default
+   See :ref:`global-start-method` for more details.
    Otherwise *method* should be ``'fork'``, ``'spawn'``,
    ``'forkserver'``.  :exc:`ValueError` is raised if the specified
    start method is not available.  See :ref:`multiprocessing-start-methods`.
@@ -1179,10 +1203,9 @@ Miscellaneous
 
    Return the name of start method used for starting processes.
 
-   If the global start method has not been set and *allow_none* is
-   ``False``, then the start method is set to the default and the name
-   is returned. If the start method has not been set and *allow_none* is
-   ``True`` then ``None`` is returned.
+   If the global start method is not set and *allow_none* is ``False``, the global start
+   method is set to the default, and its name is returned. See
+   :ref:`global-start-method` for more details.
 
    The return value can be ``'fork'``, ``'spawn'``, ``'forkserver'``
    or ``None``.  See :ref:`multiprocessing-start-methods`.
@@ -1409,13 +1432,19 @@ object -- see :ref:`multiprocessing-managers`.
 
    A barrier object: a clone of :class:`threading.Barrier`.
 
+   Instantiating this class may set the global start method. See
+   :ref:`global-start-method` for more details.
+
    .. versionadded:: 3.3
 
 .. class:: BoundedSemaphore([value])
 
    A bounded semaphore object: a close analog of
    :class:`threading.BoundedSemaphore`.
 
+   Instantiating this class may set the global start method. See
+   :ref:`global-start-method` for more details.
+
    A solitary difference from its close analog exists: its ``acquire`` method's
    first argument is named *block*, as is consistent with :meth:`Lock.acquire`.
 
@@ -1436,13 +1465,18 @@ object -- see :ref:`multiprocessing-managers`.
    If *lock* is specified then it should be a :class:`Lock` or :class:`RLock`
    object from :mod:`multiprocessing`.
 
+   Instantiating this class may set the global start method. See
+   :ref:`global-start-method` for more details.
+
    .. versionchanged:: 3.3
       The :meth:`~threading.Condition.wait_for` method was added.
 
 .. class:: Event()
 
    A clone of :class:`threading.Event`.
 
+   Instantiating this class may set the global start method. See
+   :ref:`global-start-method` for more details.
 
 .. class:: Lock()
 
@@ -1458,6 +1492,9 @@ object -- see :ref:`multiprocessing-managers`.
    instance of ``multiprocessing.synchronize.Lock`` initialized with a
    default context.
 
+   Instantiating this class may set the global start method. See
+   :ref:`global-start-method` for more details.
+
    :class:`Lock` supports the :term:`context manager` protocol and thus may be
    used in :keyword:`with` statements.
 
@@ -1515,6 +1552,9 @@ object -- see :ref:`multiprocessing-managers`.
    instance of ``multiprocessing.synchronize.RLock`` initialized with a
    default context.
 
+   Instantiating this class may set the global start method. See
+   :ref:`global-start-method` for more details.
+
    :class:`RLock` supports the :term:`context manager` protocol and thus may be
    used in :keyword:`with` statements.
 
@@ -1574,6 +1614,9 @@ object -- see :ref:`multiprocessing-managers`.
 
    A semaphore object: a close analog of :class:`threading.Semaphore`.
 
+   Instantiating this class may set the global start method. See
+   :ref:`global-start-method` for more details.
+
    A solitary difference from its close analog exists: its ``acquire`` method's
    first argument is named *block*, as is consistent with :meth:`Lock.acquire`.
 
@@ -1718,7 +1761,7 @@ processes.
    attributes which allow one to use it to store and retrieve strings -- see
    documentation for :mod:`ctypes`.
 
-.. function:: Array(typecode_or_type, size_or_initializer, *, lock=True)
+.. function:: Array(typecode_or_type, size_or_initializer, *, lock=True, ctx=None)
 
    The same as :func:`RawArray` except that depending on the value of *lock* a
    process-safe synchronization wrapper may be returned instead of a raw ctypes
@@ -1732,9 +1775,13 @@ processes.
    automatically protected by a lock, so it will not necessarily be
    "process-safe".
 
-   Note that *lock* is a keyword-only argument.
+   *ctx* is a context object, or ``None`` (use the current context). If ``None``,
+   calling this may set the global start method. See
+   :ref:`global-start-method` for more details.
 
-.. function:: Value(typecode_or_type, *args, lock=True)
+   Note that *lock* and *ctx* are keyword-only parameters.
+
+.. function:: Value(typecode_or_type, *args, lock=True, ctx=None)
 
    The same as :func:`RawValue` except that depending on the value of *lock* a
    process-safe synchronization wrapper may be returned instead of a raw ctypes
@@ -1747,19 +1794,27 @@ processes.
    automatically protected by a lock, so it will not necessarily be
    "process-safe".
 
-   Note that *lock* is a keyword-only argument.
+   *ctx* is a context object, or ``None`` (use the current context). If ``None``,
+   calling this may set the global start method. See
+   :ref:`global-start-method` for more details.
+
+   Note that *lock* and *ctx* are keyword-only parameters.
 
 .. function:: copy(obj)
 
    Return a ctypes object allocated from shared memory which is a copy of the
    ctypes object *obj*.
 
-.. function:: synchronized(obj[, lock])
+.. function:: synchronized(obj, lock=None, ctx=None)
 
    Return a process-safe wrapper object for a ctypes object which uses *lock* to
    synchronize access.  If *lock* is ``None`` (the default) then a
    :class:`multiprocessing.RLock` object is created automatically.
 
+   *ctx* is a context object, or ``None`` (use the current context). If ``None``,
+   calling this may set the global start method. See
+   :ref:`global-start-method` for more details.
+
    A synchronized wrapper will have two methods in addition to those of the
    object it wraps: :meth:`get_obj` returns the wrapped object and
    :meth:`get_lock` returns the lock object used for synchronization.
@@ -1877,8 +1932,9 @@ their parent process exits.  The manager classes are defined in the
    *serializer* must be ``'pickle'`` (use :mod:`pickle` serialization) or
    ``'xmlrpclib'`` (use :mod:`xmlrpc.client` serialization).
 
-   *ctx* is a context object, or ``None`` (use the current context). See the
-   :func:`get_context` function.
+   *ctx* is a context object, or ``None`` (use the current context). If ``None``,
+   calling this may set the global start method. See
+   :ref:`global-start-method` for more details.
 
    *shutdown_timeout* is a timeout in seconds used to wait until the process
    used by the manager completes in the :meth:`shutdown` method. If the
@@ -2371,7 +2427,9 @@ with the :class:`Pool` class.
    the worker processes.  Usually a pool is created using the
    function :func:`multiprocessing.Pool` or the :meth:`Pool` method
    of a context object.  In both cases *context* is set
-   appropriately.
+   appropriately. If ``None``, calling this function will have the side effect
+   of setting the current global start method if it has not been set already.
+   See the :func:`get_context` function.
 
    Note that the methods of the pool object should only be called by
    the process which created the pool.