Stowage/cpython
2
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-12-31 04:23:37 +00:00
Code Issues Projects Releases Packages Wiki Activity

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

Browse source 
* 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.

Co-authored-by: Carol Willing <carolcode@willingconsulting.com>
Co-authored-by: R Chintan Meher <meherrihaan@gmail.com>
This commit is contained in:
AN Long 2025-12-16 07:12:52 +09:00 • committed by GitHub
parent b6d708ff2c
commit 0978b9a7d5
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 72 additions and 14 deletions
Download patch file Download diff file Expand all files Collapse all files

86
Doc/library/multiprocessing.rst
View file

@ -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,6 +1432,9 @@ 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])
@ -1416,6 +1442,9 @@ object -- see :ref:`multiprocessing-managers`.
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,6 +1465,9 @@ 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.
@ -1443,6 +1475,8 @@ object -- see :ref:`multiprocessing-managers`.
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.