mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-07-29 06:05:00 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 9

Move member descriptions inside the classes.

Browse source
This commit is contained in:
Georg Brandl 2009-07-26 14:44:23 +00:00
parent d7d4fd7336
commit 3591a8f81d
1 changed files with 155 additions and 172 deletions
Download patch file Download diff file Expand all files Collapse all files

327
Doc/library/threading.rst
View file

@ -231,7 +231,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.
@ -239,112 +240,104 @@ 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:: start()
.. method:: Thread.start() Start the thread's activity.
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.
It must be called at most once per thread object. It arranges for the object's This method will raise a :exc:`RuntimeException` if called more than once
:meth:`run` method to be invoked in a separate thread of control. on the same thread object.
This method will raise a :exc:`RuntimeException` if called more than once on the .. method:: run()
same thread object.
Method representing the thread's activity.
.. method:: Thread.run() 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 representing the thread's activity. .. method:: join([timeout])
You may override this method in a subclass. The standard :meth:`run` method Wait until the thread terminates. This blocks the calling thread until the
invokes the callable object passed to the object's constructor as the *target* thread whose :meth:`join` method is called terminates -- either normally
argument, if any, with sequential and keyword arguments taken from the *args* or through an unhandled exception -- or until the optional timeout occurs.
and *kwargs* arguments, respectively.
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:`isAlive` after :meth:`join` to decide whether a timeout
happened -- if the thread is still alive, the :meth:`join` call timed out.
.. method:: Thread.join([timeout]) When the *timeout* argument is not present or ``None``, the operation will
block until the thread terminates.
Wait until the thread terminates. This blocks the calling thread until the A thread can be :meth:`join`\ ed many times.
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 :meth:`join` raises a :exc:`RuntimeError` if an attempt is made to join
point number specifying a timeout for the operation in seconds (or fractions the current thread as that would cause a deadlock. It is also an error to
thereof). As :meth:`join` always returns ``None``, you must call :meth:`isAlive` :meth:`join` a thread before it has been started and attempts to do so
after :meth:`join` to decide whether a timeout happened -- if the thread is raises the same exception.
still alive, the :meth:`join` call timed out.
When the *timeout* argument is not present or ``None``, the operation will block .. method:: getName()
until the thread terminates. setName()
A thread can be :meth:`join`\ ed many times. Old API for :attr:`~Thread.name`.
:meth:`join` raises a :exc:`RuntimeError` if an attempt is made to join .. attribute:: name
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 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:: Thread.getName() .. attribute:: ident
Thread.setName()
Old API for :attr:`~Thread.name`. 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.
.. versionadded:: 2.6
.. attribute:: Thread.name .. method:: is_alive()
isAlive()
A string used for identification purposes only. It has no semantics. Return whether the thread is alive.
Multiple threads may be given the same name. The initial name is set by the
constructor.
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.
.. attribute:: Thread.ident .. method:: isDaemon()
setDaemon()
The 'thread identifier' of this thread or ``None`` if the thread has not been Old API for :attr:`~Thread.daemon`.
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.
.. versionadded:: 2.6 .. attribute:: 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``.
.. method:: Thread.is_alive() The entire Python program exits when no alive non-daemon threads are left.
Thread.isAlive()
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.isDaemon()
Thread.setDaemon()
Old API for :attr:`~Thread.daemon`.
.. 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.
.. _lock-objects: .. _lock-objects:
@ -515,70 +508,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:: acquire(*args)
.. method:: Condition.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 .. method:: release()
underlying lock; the return value is whatever that method returns.
Release the underlying lock. This method calls the corresponding method on
the underlying lock; there is no return value.
.. method:: Condition.release() .. method:: wait([timeout])
Release the underlying lock. This method calls the corresponding method on the Wait until notified or until a timeout occurs. If the calling thread has not
underlying lock; there is no return value. acquired the lock when this method is called, a :exc:`RuntimeError` is raised.
This method releases the underlying lock, and then blocks until it is
awakened by a :meth:`notify` or :meth:`notifyAll` 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.
.. method:: Condition.wait([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).
Wait until notified or until a timeout occurs. If the calling thread has not When the underlying lock is an :class:`RLock`, it is not released using
acquired the lock when this method is called, a :exc:`RuntimeError` is raised. 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.
This method releases the underlying lock, and then blocks until it is awakened .. method:: notify()
by a :meth:`notify` or :meth:`notifyAll` 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 *timeout* argument is present and not ``None``, it should be a floating Wake up a thread waiting on this condition, if any. If the calling thread
point number specifying a timeout for the operation in seconds (or fractions has not acquired the lock when this method is called, a
thereof). :exc:`RuntimeError` is raised.
When the underlying lock is an :class:`RLock`, it is not released using its This method wakes up one of the threads waiting for the condition
:meth:`release` method, since this may not actually unlock the lock when it was variable, if any are waiting; it is a no-op if no threads are waiting.
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.
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.
.. method:: Condition.notify() 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.
Wake up a thread waiting on this condition, if any. If the calling thread .. method:: notify_all()
has not acquired the lock when this method is called, a :exc:`RuntimeError` notifyAll()
is raised.
This method wakes up one of the threads waiting for the condition variable, Wake up all threads waiting on this condition. This method acts like
if any are waiting; it is a no-op if no threads are waiting. :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
The current implementation wakes up exactly one thread, if any are waiting. :exc:`RuntimeError` is raised.
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()
Condition.notifyAll()
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:
@ -602,33 +591,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 without arguments: if the internal counter is larger than zero on When invoked with *blocking* set to true, do the same thing as when called
entry, decrement it by one and return immediately. If it is zero on entry, without arguments, and return true.
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 with *blocking* set to false, do not block. If a call
without arguments, and return true. 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 false, do not block. If a call without an .. method:: release()
argument would block, return false immediately; otherwise, do the same thing as
when called without arguments, and return true.
Release a semaphore, incrementing the internal counter by one. When it
.. method:: Semaphore.release() 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: .. _semaphore-examples:
@ -675,42 +662,39 @@ 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()
isSet()
.. method:: Event.is_set() Return true if and only if the internal flag is true.
Event.isSet()
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 floating point number specifying a timeout for the operation in seconds
again. (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:: 2.7
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:: 2.7
Previously, the method always returned ``None``.
.. _timer-objects: .. _timer-objects:
@ -741,11 +725,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: