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
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.
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.
: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
: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`.
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`.
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`.
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.
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()
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.
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.
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`.
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
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
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.
*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
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.
projects / thirdparty / Python / cpython.git / commitdiff
