diff options
Diffstat (limited to 'Doc/library/threading.rst')
| -rw-r--r-- | Doc/library/threading.rst | 330 |
1 files changed, 157 insertions, 173 deletions
diff --git a/Doc/library/threading.rst b/Doc/library/threading.rst index d880157..86a9bf8 100644 --- a/Doc/library/threading.rst +++ b/Doc/library/threading.rst @@ -1,4 +1,3 @@ - :mod:`threading` --- Higher-level threading interface ===================================================== @@ -55,8 +54,9 @@ This module defines the following functions and objects: :noindex: A factory function that returns a new event object. An event manages a flag - that can be set to true with the :meth:`set` method and reset to false with the - :meth:`clear` method. The :meth:`wait` method blocks until the flag is true. + 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. .. class:: local @@ -213,7 +213,8 @@ impossible to detect the termination of alien threads. .. class:: Thread(group=None, target=None, name=None, args=(), kwargs={}) - This constructor should always be called with keyword arguments. Arguments are: + This constructor should always be called with keyword arguments. Arguments + are: *group* should be ``None``; reserved for future extension when a :class:`ThreadGroup` class is implemented. @@ -221,111 +222,103 @@ impossible to detect the termination of alien threads. *target* is the callable object to be invoked by the :meth:`run` method. Defaults to ``None``, meaning nothing is called. - *name* is the thread name. By default, a unique name is constructed of the form - "Thread-*N*" where *N* is a small decimal number. + *name* is the thread name. By default, a unique name is constructed of the + form "Thread-*N*" where *N* is a small decimal number. *args* is the argument tuple for the target invocation. Defaults to ``()``. *kwargs* is a dictionary of keyword arguments for the target invocation. Defaults to ``{}``. - If the subclass overrides the constructor, it must make sure to invoke the base - class constructor (``Thread.__init__()``) before doing anything else to the - thread. - - -.. method:: Thread.start() - - Start the thread's activity. - - It must be called at most once per thread object. It arranges for the object's - :meth:`run` method to be invoked in a separate thread of control. + If the subclass overrides the constructor, it must make sure to invoke the + base class constructor (``Thread.__init__()``) before doing anything else to + the thread. - This method will raise a :exc:`RuntimeException` if called more than once on the - same thread object. + .. method:: start() + Start the thread's activity. -.. method:: Thread.run() + It must be called at most once per thread object. It arranges for the + object's :meth:`run` method to be invoked in a separate thread of control. - Method representing the thread's activity. + This method will raise a :exc:`RuntimeException` if called more than once + on the same thread object. - You may override this method in a subclass. The standard :meth:`run` method - invokes the callable object passed to the object's constructor as the *target* - argument, if any, with sequential and keyword arguments taken from the *args* - and *kwargs* arguments, respectively. + .. method:: run() + Method representing the thread's activity. -.. method:: Thread.join([timeout]) + You may override this method in a subclass. The standard :meth:`run` + method invokes the callable object passed to the object's constructor as + the *target* argument, if any, with sequential and keyword arguments taken + from the *args* and *kwargs* arguments, respectively. - Wait until the thread terminates. This blocks the calling thread until the - thread whose :meth:`join` method is called terminates -- either normally or - through an unhandled exception -- or until the optional timeout occurs. + .. method:: join([timeout]) - When the *timeout* argument is present and not ``None``, it should be a floating - point number specifying a timeout for the operation in seconds (or fractions - thereof). As :meth:`join` always returns ``None``, you must call :meth:`is_alive` - after :meth:`join` to decide whether a timeout happened -- if the thread is - still alive, the :meth:`join` call timed out. + Wait until the thread terminates. This blocks the calling thread until the + thread whose :meth:`join` method is called terminates -- either normally + or through an unhandled exception -- or until the optional timeout occurs. - When the *timeout* argument is not present or ``None``, the operation will block - until the thread terminates. + When the *timeout* argument is present and not ``None``, it should be a + floating point number specifying a timeout for the operation in seconds + (or fractions thereof). As :meth:`join` always returns ``None``, you must + call :meth:`is_alive` after :meth:`join` to decide whether a timeout + happened -- if the thread is still alive, the :meth:`join` call timed out. - A thread can be :meth:`join`\ ed many times. + When the *timeout* argument is not present or ``None``, the operation will + block until the thread terminates. - :meth:`join` raises a :exc:`RuntimeError` if an attempt is made to join - the current thread as that would cause a deadlock. It is also an error to - :meth:`join` a thread before it has been started and attempts to do so - raises the same exception. + A thread can be :meth:`join`\ ed many times. + :meth:`join` raises a :exc:`RuntimeError` if an attempt is made to join + the current thread as that would cause a deadlock. It is also an error to + :meth:`join` a thread before it has been started and attempts to do so + raises the same exception. -.. attribute:: Thread.name + .. attribute:: name - A string used for identification purposes only. It has no semantics. - Multiple threads may be given the same name. The initial name is set by the - constructor. + A string used for identification purposes only. It has no semantics. + Multiple threads may be given the same name. The initial name is set by + the constructor. + .. method:: getName() + setName() -.. method:: Thread.getName() - Thread.setName() + Old getter/setter API for :attr:`~Thread.name`; use it directly as a + property instead. - Old getter/setter API for :attr:`~Thread.name`; use it directly as a property - instead. + .. attribute:: ident + The 'thread identifier' of this thread or ``None`` if the thread has not + been started. This is a nonzero integer. See the + :func:`thread.get_ident()` function. Thread identifiers may be recycled + when a thread exits and another thread is created. The identifier is + available even after the thread has exited. -.. attribute:: Thread.ident + .. method:: is_alive() - The 'thread identifier' of this thread or ``None`` if the thread has not been - started. This is a nonzero integer. See the :func:`thread.get_ident()` - function. Thread identifiers may be recycled when a thread exits and another - thread is created. The identifier is available even after the thread has - exited. + Return whether the thread is alive. + Roughly, a thread is alive from the moment the :meth:`start` method + returns until its :meth:`run` method terminates. The module function + :func:`enumerate` returns a list of all alive threads. -.. method:: Thread.is_alive() + .. attribute:: daemon - Return whether the thread is alive. + A boolean value indicating whether this thread is a daemon thread (True) + or not (False). This must be set before :meth:`start` is called, + otherwise :exc:`RuntimeError` is raised. Its initial value is inherited + from the creating thread; the main thread is not a daemon thread and + therefore all threads created in the main thread default to :attr:`daemon` + = ``False``. - Roughly, a thread is alive from the moment the :meth:`start` method returns - until its :meth:`run` method terminates. The module function :func:`enumerate` - returns a list of all alive threads. + The entire Python program exits when no alive non-daemon threads are left. + .. method:: isDaemon() + setDaemon() -.. attribute:: Thread.daemon - - A boolean value indicating whether this thread is a daemon thread (True) or - not (False). This must be set before :meth:`start` is called, otherwise - :exc:`RuntimeError` is raised. Its initial value is inherited from the - creating thread; the main thread is not a daemon thread and therefore all - threads created in the main thread default to :attr:`daemon` = ``False``. - - The entire Python program exits when no alive non-daemon threads are left. - - -.. method:: Thread.isDaemon() - Thread.setDaemon() - - Old getter/setter API for :attr:`~Thread.daemon`; use it directly as a - property instead. + Old getter/setter API for :attr:`~Thread.daemon`; use it directly as a + property instead. .. _lock-objects: @@ -496,69 +489,66 @@ needs to wake up one consumer thread. .. class:: Condition([lock]) - 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. - + 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. -.. method:: Condition.acquire(*args) + .. method:: acquire(*args) - Acquire the underlying lock. This method calls the corresponding method on the - underlying lock; the return value is whatever that method returns. + Acquire the underlying lock. This method calls the corresponding method on + the underlying lock; the return value is whatever that method returns. + .. method:: release() -.. method:: Condition.release() + Release the underlying lock. This method calls the corresponding method on + the underlying lock; there is no return value. - Release the underlying lock. This method calls the corresponding method on the - underlying lock; there is no return value. + .. method:: wait([timeout]) + Wait until notified or until a timeout occurs. If the calling thread has + not acquired the lock when this method is called, a :exc:`RuntimeError` is + raised. -.. method:: Condition.wait([timeout]) + This method releases the underlying lock, and then blocks until it is + awakened by a :meth:`notify` or :meth:`notify_all` call for the same + condition variable in another thread, or until the optional timeout + occurs. Once awakened or timed out, it re-acquires the lock and returns. - Wait until notified or until a timeout occurs. If the calling thread has not - acquired the lock when this method is called, a :exc:`RuntimeError` is raised. + When the *timeout* argument is present and not ``None``, it should be a + floating point number specifying a timeout for the operation in seconds + (or fractions thereof). - This method releases the underlying lock, and then blocks until it is awakened - by a :meth:`notify` or :meth:`notify_all` call for the same condition variable in - another thread, or until the optional timeout occurs. Once awakened or timed - out, it re-acquires the lock and returns. + When the underlying lock is an :class:`RLock`, it is not released using + its :meth:`release` method, since this may not actually unlock the lock + when it was acquired multiple times recursively. Instead, an internal + interface of the :class:`RLock` class is used, which really unlocks it + even when it has been recursively acquired several times. Another internal + interface is then used to restore the recursion level when the lock is + reacquired. - When the *timeout* argument is present and not ``None``, it should be a floating - point number specifying a timeout for the operation in seconds (or fractions - thereof). + .. method:: notify() - When the underlying lock is an :class:`RLock`, it is not released using its - :meth:`release` method, since this may not actually unlock the lock when it was - acquired multiple times recursively. Instead, an internal interface of the - :class:`RLock` class is used, which really unlocks it even when it has been - recursively acquired several times. Another internal interface is then used to - restore the recursion level when the lock is reacquired. + Wake up a thread waiting on this condition, if any. If the calling thread + has not acquired the lock when this method is called, a + :exc:`RuntimeError` is raised. + This method wakes up one of the threads waiting for the condition + variable, if any are waiting; it is a no-op if no threads are waiting. -.. method:: Condition.notify() + The current implementation wakes up exactly one thread, if any are + waiting. However, it's not safe to rely on this behavior. A future, + optimized implementation may occasionally wake up more than one thread. - Wake up a thread waiting on this condition, if any. If the calling thread - has not acquired the lock when this method is called, a :exc:`RuntimeError` - is raised. + Note: the awakened thread does not actually return from its :meth:`wait` + call until it can reacquire the lock. Since :meth:`notify` does not + release the lock, its caller should. - This method wakes up one of the threads waiting for the condition variable, - if any are waiting; it is a no-op if no threads are waiting. + .. method:: notify_all() - The current implementation wakes up exactly one thread, if any are waiting. - However, it's not safe to rely on this behavior. A future, optimized - implementation may occasionally wake up more than one thread. - - Note: the awakened thread does not actually return from its :meth:`wait` call - until it can reacquire the lock. Since :meth:`notify` does not release the - lock, its caller should. - - -.. method:: Condition.notify_all() - - Wake up all threads waiting on this condition. This method acts like - :meth:`notify`, but wakes up all waiting threads instead of one. If the calling - thread has not acquired the lock when this method is called, a - :exc:`RuntimeError` is raised. + Wake up all threads waiting on this condition. This method acts like + :meth:`notify`, but wakes up all waiting threads instead of one. If the + calling thread has not acquired the lock when this method is called, a + :exc:`RuntimeError` is raised. .. _semaphore-objects: @@ -582,33 +572,31 @@ waiting until some other thread calls :meth:`release`. defaults to ``1``. If the *value* given is less than 0, :exc:`ValueError` is raised. + .. method:: acquire([blocking]) -.. method:: Semaphore.acquire([blocking]) - - Acquire a semaphore. - - When invoked without arguments: if the internal counter is larger than zero on - entry, decrement it by one and return immediately. If it is zero on entry, - block, waiting until some other thread has called :meth:`release` to make it - larger than zero. This is done with proper interlocking so that if multiple - :meth:`acquire` calls are blocked, :meth:`release` will wake exactly one of them - up. The implementation may pick one at random, so the order in which blocked - threads are awakened should not be relied on. There is no return value in this - case. + Acquire a semaphore. - When invoked with *blocking* set to true, do the same thing as when called - without arguments, and return true. + When invoked without arguments: if the internal counter is larger than + zero on entry, decrement it by one and return immediately. If it is zero + on entry, block, waiting until some other thread has called + :meth:`release` to make it larger than zero. This is done with proper + interlocking so that if multiple :meth:`acquire` calls are blocked, + :meth:`release` will wake exactly one of them up. The implementation may + pick one at random, so the order in which blocked threads are awakened + should not be relied on. There is no return value in this case. - When invoked with *blocking* set to false, do not block. If a call without an - argument would block, return false immediately; otherwise, do the same thing as - when called without arguments, and return true. + When invoked with *blocking* set to true, do the same thing as when called + without arguments, and return true. + When invoked with *blocking* set to false, do not block. If a call + without an argument would block, return false immediately; otherwise, do + the same thing as when called without arguments, and return true. -.. method:: Semaphore.release() + .. method:: release() - Release a semaphore, incrementing the internal counter by one. When it was zero - on entry and another thread is waiting for it to become larger than zero again, - wake up that thread. + Release a semaphore, incrementing the internal counter by one. When it + was zero on entry and another thread is waiting for it to become larger + than zero again, wake up that thread. .. _semaphore-examples: @@ -647,7 +635,7 @@ This is one of the simplest mechanisms for communication between threads: one thread signals an event and other threads wait for it. An event object manages an internal flag that can be set to true with the -:meth:`set` method and reset to false with the :meth:`clear` method. The +:meth:`~Event.set` method and reset to false with the :meth:`clear` method. The :meth:`wait` method blocks until the flag is true. @@ -655,40 +643,37 @@ An event object manages an internal flag that can be set to true with the The internal flag is initially false. + .. method:: is_set() -.. method:: Event.is_set() + Return true if and only if the internal flag is true. - Return true if and only if the internal flag is true. + .. method:: set() + Set the internal flag to true. All threads waiting for it to become true + are awakened. Threads that call :meth:`wait` once the flag is true will + not block at all. -.. method:: Event.set() + .. method:: clear() - Set the internal flag to true. All threads waiting for it to become true are - awakened. Threads that call :meth:`wait` once the flag is true will not block at - all. + Reset the internal flag to false. Subsequently, threads calling + :meth:`wait` will block until :meth:`.set` is called to set the internal + flag to true again. + .. method:: wait([timeout]) -.. method:: Event.clear() + Block until the internal flag is true. If the internal flag is true on + entry, return immediately. Otherwise, block until another thread calls + :meth:`set` to set the flag to true, or until the optional timeout occurs. - Reset the internal flag to false. Subsequently, threads calling :meth:`wait` - will block until :meth:`set` is called to set the internal flag to true again. + When the timeout argument is present and not ``None``, it should be a + floating point number specifying a timeout for the operation in seconds + (or fractions thereof). + This method returns the internal flag on exit, so it will always return + ``True`` except if a timeout is given and the operation times out. -.. method:: Event.wait([timeout]) - - Block until the internal flag is true. If the internal flag is true on entry, - return immediately. Otherwise, block until another thread calls :meth:`set` - to set the flag to true, or until the optional timeout occurs. - - When the timeout argument is present and not ``None``, it should be a floating - point number specifying a timeout for the operation in seconds (or fractions - thereof). - - This method returns the internal flag on exit, so it will always return - ``True`` except if a timeout is given and the operation times out. - - .. versionchanged:: 3.1 - Previously, the method always returned ``None``. + .. versionchanged:: 3.1 + Previously, the method always returned ``None``. .. _timer-objects: @@ -719,11 +704,10 @@ For example:: Create a timer that will run *function* with arguments *args* and keyword arguments *kwargs*, after *interval* seconds have passed. + .. method:: cancel() -.. method:: Timer.cancel() - - Stop the timer, and cancel the execution of the timer's action. This will only - work if the timer is still in its waiting stage. + Stop the timer, and cancel the execution of the timer's action. This will + only work if the timer is still in its waiting stage. .. _with-locks: |