diff --git a/Doc/library/multiprocessing.rst b/Doc/library/multiprocessing.rst --- a/Doc/library/multiprocessing.rst +++ b/Doc/library/multiprocessing.rst @@ -863,7 +863,7 @@ object -- see :ref:`multiprocessing-mana .. class:: Condition([lock]) - A condition variable: a clone of :class:`threading.Condition`. + A condition variable: an alias for :class:`threading.Condition`. If *lock* is specified then it should be a :class:`Lock` or :class:`RLock` object from :mod:`multiprocessing`. diff --git a/Doc/library/threading.rst b/Doc/library/threading.rst --- a/Doc/library/threading.rst +++ b/Doc/library/threading.rst @@ -21,7 +21,7 @@ The :mod:`dummy_threading` module is pro supported by this module. -This module defines the following functions and objects: +This module defines the following functions: .. function:: active_count() @@ -30,16 +30,6 @@ This module defines the following functi count is equal to the length of the list returned by :func:`.enumerate`. -.. function:: Condition() - :noindex: - - A factory function that returns a new condition variable object. A condition - variable allows one or more threads to wait until they are notified by another - thread. - - See :ref:`condition-objects`. - - .. function:: current_thread() Return the current :class:`Thread` object, corresponding to the caller's thread @@ -67,89 +57,6 @@ This module defines the following functi and threads that have not yet been started. -.. function:: Event() - :noindex: - - A factory function that returns a new event object. An event manages a flag - that can be set to true with the :meth:`~Event.set` method and reset to false - with the :meth:`clear` method. The :meth:`wait` method blocks until the flag - is true. - - See :ref:`event-objects`. - - -.. class:: local - - A class that represents thread-local data. Thread-local data are data whose - values are thread specific. To manage thread-local data, just create an - instance of :class:`local` (or a subclass) and store attributes on it:: - - mydata = threading.local() - mydata.x = 1 - - The instance's values will be different for separate threads. - - For more details and extensive examples, see the documentation string of the - :mod:`_threading_local` module. - - -.. function:: Lock() - - A factory function that returns a new primitive lock object. Once a thread has - acquired it, subsequent attempts to acquire it block, until it is released; any - thread may release it. - - See :ref:`lock-objects`. - - -.. function:: RLock() - - A factory function that returns a new reentrant lock object. A reentrant lock - must be released by the thread that acquired it. Once a thread has acquired a - reentrant lock, the same thread may acquire it again without blocking; the - thread must release it once for each time it has acquired it. - - See :ref:`rlock-objects`. - - -.. function:: Semaphore(value=1) - :noindex: - - A factory function that returns a new semaphore object. A semaphore manages a - counter representing the number of :meth:`release` calls minus the number of - :meth:`acquire` calls, plus an initial value. The :meth:`acquire` method blocks - if necessary until it can return without making the counter negative. If not - given, *value* defaults to 1. - - See :ref:`semaphore-objects`. - - -.. function:: BoundedSemaphore(value=1) - - A factory function that returns a new bounded semaphore object. A bounded - semaphore checks to make sure its current value doesn't exceed its initial - value. If it does, :exc:`ValueError` is raised. In most situations semaphores - are used to guard resources with limited capacity. If the semaphore is released - too many times it's a sign of a bug. If not given, *value* defaults to 1. - - -.. class:: Thread - :noindex: - - A class that represents a thread of control. This class can be safely - subclassed in a limited fashion. - - See :ref:`thread-objects`. - - -.. class:: Timer - :noindex: - - A thread that executes a function after a specified interval has passed. - - See :ref:`timer-objects`. - - .. function:: settrace(func) .. index:: single: trace function @@ -198,7 +105,23 @@ This module also defines the following c .. versionadded:: 3.2 -Detailed interfaces for the objects are documented below. +This module defines a number of classes. Most of them are documented in detail +later in this document. + +.. class:: local + + A class that represents thread-local data. Thread-local data are data whose + values are thread specific. To manage thread-local data, just create an + instance of :class:`local` (or a subclass) and store attributes on it:: + + mydata = threading.local() + mydata.x = 1 + + The instance's values will be different for separate threads. + + For more details and extensive examples, see the documentation string of the + :mod:`_threading_local` module. + The design of this module is loosely based on Java's threading model. However, where Java makes locks and condition variables basic behavior of every object, @@ -216,7 +139,8 @@ All of the methods described below are e Thread Objects -------------- -This class represents an activity that is run in a separate thread of control. +The :class:`Thread` class represents an activity that is run in a separate +thread of control. There are two ways to specify the activity: by passing a callable object to the constructor, or by overriding the :meth:`run` method in a subclass. No other methods (except for the constructor) should be overridden in a subclass. In @@ -254,7 +178,7 @@ daemonic, and cannot be :meth:`join`\ ed impossible to detect the termination of alien threads. -.. class:: Thread(group=None, target=None, name=None, args=(), kwargs={}, +.. class:: Thread(group=None, target=None, name=None, args=(), kwargs={}, \ verbose=None, *, daemon=None) This constructor should always be called with keyword arguments. Arguments @@ -287,6 +211,9 @@ impossible to detect the termination of .. versionchanged:: 3.3 Added the *daemon* argument. + .. versionchanged:: 3.3 + ``Thread`` used to be a factory function rather than the class itself. + .. method:: start() Start the thread's activity. @@ -414,6 +341,16 @@ and may vary across implementations. All methods are executed atomically. +.. class:: Lock() + + The class implementing primitive lock objects. Once a thread has acquired a + lock, subsequent attempts to acquire it block, until it is released; any + thread may release it. + + .. versionchanged:: 3.3 + ``Lock`` used to be a factory function rather than the class itself. + + .. method:: Lock.acquire(blocking=True, timeout=-1) Acquire a lock, blocking or non-blocking. @@ -476,6 +413,17 @@ pair) resets the lock to unlocked and al :meth:`acquire` to proceed. +.. class:: RLock() + + This class implements reentrant lock objects. A reentrant lock must be + released by the thread that acquired it. Once a thread has acquired a + reentrant lock, the same thread may acquire it again without blocking; the + thread must release it once for each time it has acquired it. + + .. versionchanged:: 3.3 + ``RLock`` used to be a factory function rather than the class itself. + + .. method:: RLock.acquire(blocking=True, timeout=-1) Acquire a lock, blocking or non-blocking. @@ -584,10 +532,16 @@ the call as often as necessary. .. class:: Condition(lock=None) + This class implements condition variable objects. A condition variable + allows one or more threads to wait until they are notified by another thread. + If the *lock* argument is given and not ``None``, it must be a :class:`Lock` or :class:`RLock` object, and it is used as the underlying lock. Otherwise, a new :class:`RLock` object is created and used as the underlying lock. + .. versionchanged:: 3.3 + ``Condition`` used to be a factory function rather than the class itself. + .. method:: acquire(*args) Acquire the underlying lock. This method calls the corresponding method on @@ -698,10 +652,19 @@ waiting until some other thread calls :m .. class:: Semaphore(value=1) + This class implements semaphore objects. A semaphore manages a counter + representing the number of :meth:`release` calls minus the number of + :meth:`acquire` calls, plus an initial value. The :meth:`acquire` method + blocks if necessary until it can return without making the counter negative. + If not given, *value* defaults to 1. + The optional argument gives the initial *value* for the internal counter; it defaults to ``1``. If the *value* given is less than 0, :exc:`ValueError` is raised. + .. versionchanged:: 3.3 + ``Semaphore`` used to be a factory function rather than the class itself. + .. method:: acquire(blocking=True, timeout=None) Acquire a semaphore. @@ -733,6 +696,19 @@ waiting until some other thread calls :m than zero again, wake up that thread. +.. class:: BoundedSemaphore(value=1) + + Class implementing bounded semaphore objects. A bounded semaphore checks to + make sure its current value doesn't exceed its initial value. If it does, + :exc:`ValueError` is raised. In most situations semaphores are used to guard + resources with limited capacity. If the semaphore is released too many times + it's a sign of a bug. If not given, *value* defaults to 1. + + .. versionchanged:: 3.3 + ``BoundedSemaphore`` used to be a factory function rather than the class + itself. + + .. _semaphore-examples: :class:`Semaphore` Example @@ -744,7 +720,7 @@ you should use a bounded semaphore. Bef main thread would initialize the semaphore:: maxconnections = 5 - ... + # ... pool_sema = BoundedSemaphore(value=maxconnections) Once spawned, worker threads call the semaphore's acquire and release methods @@ -752,7 +728,7 @@ when they need to connect to the server: pool_sema.acquire() conn = connectdb() - ... use connection ... + # ... use connection ... conn.close() pool_sema.release() @@ -775,7 +751,13 @@ An event object manages an internal flag .. class:: Event() - The internal flag is initially false. + Class implementing event objects. An event manages a flag that can be set to + true with the :meth:`~Event.set` method and reset to false with the + :meth:`clear` method. The :meth:`wait` method blocks until the flag is true. + The flag is initially false. + + .. versionchanged:: 3.3 + ``Event`` used to be a factory function rather than the class itself. .. method:: is_set() @@ -838,6 +820,9 @@ For example:: Create a timer that will run *function* with arguments *args* and keyword arguments *kwargs*, after *interval* seconds have passed. + .. versionchanged:: 3.3 + ``Timer`` used to be a factory function rather than the class itself. + .. method:: cancel() Stop the timer, and cancel the execution of the timer's action. This will