Skip to content

C
cpython
Kaydet (Commit) 7a72b3ad authored tarafından Georg Brandl's avatar Georg Brandl
Dosyalara gözat
Seçenekler

Recorded merge of revisions 74210 via svnmerge from 

svn+ssh://pythondev@svn.python.org/python/trunk

........
  r74210 | georg.brandl | 2009-07-26 16:44:23 +0200 (So, 26 Jul 2009) | 1 line

  Move member descriptions inside the classes.
........
üst 6730538e
Hide whitespace changes
Inline Side-by-side
Showing with 153 additions and 170 deletions
Doc/library/threading.rst
Dosyayı görüntüle @ 7a72b3ad
:mod:`threading` --- Higher-level threading interface :mod:`threading` --- Higher-level threading interface
===================================================== =====================================================
...@@ -213,7 +212,8 @@ impossible to detect the termination of alien threads. ...@@ -213,7 +212,8 @@ 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={})
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 *group* should be ``None``; reserved for future extension when a
:class:`ThreadGroup` class is implemented. :class:`ThreadGroup` class is implemented.
...@@ -221,111 +221,103 @@ impossible to detect the termination of alien threads. ...@@ -221,111 +221,103 @@ impossible to detect the termination of alien threads.
*target* is the callable object to be invoked by the :meth:`run` method. *target* is the callable object to be invoked by the :meth:`run` method.
Defaults to ``None``, meaning nothing is called. Defaults to ``None``, meaning nothing is called.
*name* is the thread name. By default, a unique name is constructed of the form *name* is the thread name. By default, a unique name is constructed of the
"Thread-*N*" where *N* is a small decimal number. form "Thread-*N*" where *N* is a small decimal number.
*args* is the argument tuple for the target invocation. Defaults to ``()``. *args* is the argument tuple for the target invocation. Defaults to ``()``.
*kwargs* is a dictionary of keyword arguments for the target invocation. *kwargs* is a dictionary of keyword arguments for the target invocation.
Defaults to ``{}``. Defaults to ``{}``.
If the subclass overrides the constructor, it must make sure to invoke the base If the subclass overrides the constructor, it must make sure to invoke the
class constructor (``Thread.__init__()``) before doing anything else to the base class constructor (``Thread.__init__()``) before doing anything else to
thread. 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.
This method will raise a :exc:`RuntimeException` if called more than once on the .. method:: start()
same thread object.
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 .. method:: run()
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 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 .. method:: join([timeout])
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 present and not ``None``, it should be a floating Wait until the thread terminates. This blocks the calling thread until the
point number specifying a timeout for the operation in seconds (or fractions thread whose :meth:`join` method is called terminates -- either normally
thereof). As :meth:`join` always returns ``None``, you must call :meth:`is_alive` or through an unhandled exception -- or until the optional timeout occurs.
after :meth:`join` to decide whether a timeout happened -- if the thread is
still alive, the :meth:`join` call timed out.
When the *timeout* argument is not present or ``None``, the operation will block When the *timeout* argument is present and not ``None``, it should be a
until the thread terminates. 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 A thread can be :meth:`join`\ ed many times.
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.
: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. 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 Multiple threads may be given the same name. The initial name is set by
constructor. the constructor.
.. method:: getName()
setName()
.. method:: Thread.getName() Old getter/setter API for :attr:`~Thread.name`; use it directly as a
Thread.setName() property instead.
Old getter/setter API for :attr:`~Thread.name`; use it directly as a property .. attribute:: ident
instead.
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 Return whether the thread is alive.
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.
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 The entire Python program exits when no alive non-daemon threads are left.
until its :meth:`run` method terminates. The module function :func:`enumerate`
returns a list of all alive threads.
.. method:: isDaemon()
setDaemon()
.. attribute:: Thread.daemon Old getter/setter API for :attr:`~Thread.daemon`; use it directly as a
property instead.
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.
.. _lock-objects: .. _lock-objects:
...@@ -496,69 +488,66 @@ needs to wake up one consumer thread. ...@@ -496,69 +488,66 @@ needs to wake up one consumer thread.
.. class:: Condition([lock]) .. class:: Condition([lock])
If the *lock* argument is given and not ``None``, it must be a :class:`Lock` or If the *lock* argument is given and not ``None``, it must be a :class:`Lock`
:class:`RLock` object, and it is used as the underlying lock. Otherwise, a new or :class:`RLock` object, and it is used as the underlying lock. Otherwise,
:class:`RLock` object is created and used as the underlying lock. 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 Acquire the underlying lock. This method calls the corresponding method on
underlying lock; the return value is whatever that method returns. 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 .. method:: wait([timeout])
underlying lock; there is no return value.
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 When the *timeout* argument is present and not ``None``, it should be a
acquired the lock when this method is called, a :exc:`RuntimeError` is raised. 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 When the underlying lock is an :class:`RLock`, it is not released using
by a :meth:`notify` or :meth:`notify_all` call for the same condition variable in its :meth:`release` method, since this may not actually unlock the lock
another thread, or until the optional timeout occurs. Once awakened or timed when it was acquired multiple times recursively. Instead, an internal
out, it re-acquires the lock and returns. 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 .. method:: notify()
point number specifying a timeout for the operation in seconds (or fractions
thereof).
When the underlying lock is an :class:`RLock`, it is not released using its Wake up a thread waiting on this condition, if any. If the calling thread
:meth:`release` method, since this may not actually unlock the lock when it was has not acquired the lock when this method is called, a
acquired multiple times recursively. Instead, an internal interface of the :exc:`RuntimeError` is raised.
: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.
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 Note: the awakened thread does not actually return from its :meth:`wait`
has not acquired the lock when this method is called, a :exc:`RuntimeError` call until it can reacquire the lock. Since :meth:`notify` does not
is raised. release the lock, its caller should.
This method wakes up one of the threads waiting for the condition variable, .. method:: notify_all()
if any are waiting; it is a no-op if no threads are waiting.
The current implementation wakes up exactly one thread, if any are waiting. Wake up all threads waiting on this condition. This method acts like
However, it's not safe to rely on this behavior. A future, optimized :meth:`notify`, but wakes up all waiting threads instead of one. If the
implementation may occasionally wake up more than one thread. 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.
.. 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.
.. _semaphore-objects: .. _semaphore-objects:
...@@ -582,33 +571,31 @@ waiting until some other thread calls :meth:`release`. ...@@ -582,33 +571,31 @@ waiting until some other thread calls :meth:`release`.
defaults to ``1``. If the *value* given is less than 0, :exc:`ValueError` is defaults to ``1``. If the *value* given is less than 0, :exc:`ValueError` is
raised. raised.
.. method:: acquire([blocking])
.. method:: Semaphore.acquire([blocking]) Acquire a semaphore.
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.
When invoked with *blocking* set to true, do the same thing as when called When invoked without arguments: if the internal counter is larger than
without arguments, and return true. 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 When invoked with *blocking* set to true, do the same thing as when called
argument would block, return false immediately; otherwise, do the same thing as without arguments, and return true.
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 Release a semaphore, incrementing the internal counter by one. When it
on entry and another thread is waiting for it to become larger than zero again, was zero on entry and another thread is waiting for it to become larger
wake up that thread. than zero again, wake up that thread.
.. _semaphore-examples: .. _semaphore-examples:
...@@ -655,40 +642,37 @@ An event object manages an internal flag that can be set to true with the ...@@ -655,40 +642,37 @@ An event object manages an internal flag that can be set to true with the
The internal flag is initially false. 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 Reset the internal flag to false. Subsequently, threads calling
awakened. Threads that call :meth:`wait` once the flag is true will not block at :meth:`wait` will block until :meth:`set` is called to set the internal
all. 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` When the timeout argument is present and not ``None``, it should be a
will block until :meth:`set` is called to set the internal flag to true again. 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]) .. versionchanged:: 3.1
Previously, the method always returned ``None``.
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``.
.. _timer-objects: .. _timer-objects:
...@@ -719,11 +703,10 @@ For example:: ...@@ -719,11 +703,10 @@ For example::
Create a timer that will run *function* with arguments *args* and keyword Create a timer that will run *function* with arguments *args* and keyword
arguments *kwargs*, after *interval* seconds have passed. 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: .. _with-locks:
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment