mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-09-15 13:16:12 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 8

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

273
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,54 +240,51 @@ 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 It must be called at most once per thread object. It arranges for the
:meth:`run` method to be invoked in a separate thread of control. 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 This method will raise a :exc:`RuntimeException` if called more than once
same thread object. on the same thread object.
.. method:: run()
.. method:: Thread.run()
Method representing the thread's activity. Method representing the thread's activity.
You may override this method in a subclass. The standard :meth:`run` method You may override this method in a subclass. The standard :meth:`run`
invokes the callable object passed to the object's constructor as the *target* method invokes the callable object passed to the object's constructor as
argument, if any, with sequential and keyword arguments taken from the *args* the *target* argument, if any, with sequential and keyword arguments taken
and *kwargs* arguments, respectively. from the *args* and *kwargs* arguments, respectively.
.. method:: join([timeout])
.. method:: Thread.join([timeout])
Wait until the thread terminates. This blocks the calling thread until the Wait until the thread terminates. This blocks the calling thread until the
thread whose :meth:`join` method is called terminates -- either normally or thread whose :meth:`join` method is called terminates -- either normally
through an unhandled exception -- or until the optional timeout occurs. 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 When the *timeout* argument is present and not ``None``, it should be a
point number specifying a timeout for the operation in seconds (or fractions floating point number specifying a timeout for the operation in seconds
thereof). As :meth:`join` always returns ``None``, you must call :meth:`isAlive` (or fractions thereof). As :meth:`join` always returns ``None``, you must
after :meth:`join` to decide whether a timeout happened -- if the thread is call :meth:`isAlive` after :meth:`join` to decide whether a timeout
still alive, the :meth:`join` call timed out. 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 not present or ``None``, the operation will
until the thread terminates. block until the thread terminates.
A thread can be :meth:`join`\ ed many times. A thread can be :meth:`join`\ ed many times.
@ -295,54 +293,49 @@ impossible to detect the termination of alien threads.
:meth:`join` a thread before it has been started and attempts to do so :meth:`join` a thread before it has been started and attempts to do so
raises the same exception. raises the same exception.
.. method:: getName()
.. method:: Thread.getName() setName()
Thread.setName()
Old API for :attr:`~Thread.name`. Old API for :attr:`~Thread.name`.
.. attribute:: name
.. attribute:: Thread.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.
.. attribute:: ident
.. attribute:: Thread.ident The 'thread identifier' of this thread or ``None`` if the thread has not
been started. This is a nonzero integer. See the
The 'thread identifier' of this thread or ``None`` if the thread has not been :func:`thread.get_ident()` function. Thread identifiers may be recycled
started. This is a nonzero integer. See the :func:`thread.get_ident()` when a thread exits and another thread is created. The identifier is
function. Thread identifiers may be recycled when a thread exits and another available even after the thread has exited.
thread is created. The identifier is available even after the thread has
exited.
.. versionadded:: 2.6 .. versionadded:: 2.6
.. method:: is_alive()
.. method:: Thread.is_alive() isAlive()
Thread.isAlive()
Return whether the thread is alive. Return whether the thread is alive.
Roughly, a thread is alive from the moment the :meth:`start` method returns Roughly, a thread is alive from the moment the :meth:`start` method
until its :meth:`run` method terminates. The module function :func:`enumerate` returns until its :meth:`run` method terminates. The module function
returns a list of all alive threads. :func:`enumerate` returns a list of all alive threads.
.. method:: isDaemon()
.. method:: Thread.isDaemon() setDaemon()
Thread.setDaemon()
Old API for :attr:`~Thread.daemon`. Old API for :attr:`~Thread.daemon`.
.. attribute:: 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,
A boolean value indicating whether this thread is a daemon thread (True) or otherwise :exc:`RuntimeError` is raised. Its initial value is inherited
not (False). This must be set before :meth:`start` is called, otherwise from the creating thread; the main thread is not a daemon thread and
:exc:`RuntimeError` is raised. Its initial value is inherited from the therefore all threads created in the main thread default to :attr:`daemon`
creating thread; the main thread is not a daemon thread and therefore all = ``False``.
threads created in the main thread default to :attr:`daemon` = ``False``.
The entire Python program exits when no alive non-daemon threads are left. The entire Python program exits when no alive non-daemon threads are left.
@ -515,69 +508,65 @@ 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
underlying lock; there is no return value.
.. method:: Condition.wait([timeout])
Wait until notified or until a timeout occurs. If the calling thread has not 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. 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 This method releases the underlying lock, and then blocks until it is
by a :meth:`notify` or :meth:`notifyAll` call for the same condition variable in awakened by a :meth:`notify` or :meth:`notifyAll` call for the same
another thread, or until the optional timeout occurs. Once awakened or timed condition variable in another thread, or until the optional timeout
out, it re-acquires the lock and returns. 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 When the *timeout* argument is present and not ``None``, it should be a
point number specifying a timeout for the operation in seconds (or fractions floating point number specifying a timeout for the operation in seconds
thereof). (or fractions thereof).
When the underlying lock is an :class:`RLock`, it is not released using its When the underlying lock is an :class:`RLock`, it is not released using
:meth:`release` method, since this may not actually unlock the lock when it was its :meth:`release` method, since this may not actually unlock the lock
acquired multiple times recursively. Instead, an internal interface of the when it was acquired multiple times recursively. Instead, an internal
:class:`RLock` class is used, which really unlocks it even when it has been interface of the :class:`RLock` class is used, which really unlocks it
recursively acquired several times. Another internal interface is then used to even when it has been recursively acquired several times. Another internal
restore the recursion level when the lock is reacquired. interface is then used to restore the recursion level when the lock is
reacquired.
.. method:: notify()
.. method:: Condition.notify()
Wake up a thread waiting on this condition, if any. If the calling 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` has not acquired the lock when this method is called, a
is raised. :exc:`RuntimeError` is raised.
This method wakes up one of the threads waiting for the condition variable, This method wakes up one of the threads waiting for the condition
if any are waiting; it is a no-op if no threads are waiting. variable, 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. The current implementation wakes up exactly one thread, if any are
However, it's not safe to rely on this behavior. A future, optimized waiting. However, it's not safe to rely on this behavior. A future,
implementation may occasionally wake up more than one thread. optimized implementation may occasionally wake up more than one thread.
Note: the awakened thread does not actually return from its :meth:`wait` call Note: the awakened thread does not actually return from its :meth:`wait`
until it can reacquire the lock. Since :meth:`notify` does not release the call until it can reacquire the lock. Since :meth:`notify` does not
lock, its caller should. release the lock, its caller should.
.. method:: notify_all()
.. method:: Condition.notify_all() notifyAll()
Condition.notifyAll()
Wake up all threads waiting on this condition. This method acts like 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 :meth:`notify`, but wakes up all waiting threads instead of one. If the
thread has not acquired the lock when this method is called, a calling thread has not acquired the lock when this method is called, a
:exc:`RuntimeError` is raised. :exc:`RuntimeError` is raised.
@ -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 When invoked without arguments: if the internal counter is larger than
entry, decrement it by one and return immediately. If it is zero on entry, zero on entry, decrement it by one and return immediately. If it is zero
block, waiting until some other thread has called :meth:`release` to make it on entry, block, waiting until some other thread has called
larger than zero. This is done with proper interlocking so that if multiple :meth:`release` to make it larger than zero. This is done with proper
:meth:`acquire` calls are blocked, :meth:`release` will wake exactly one of them interlocking so that if multiple :meth:`acquire` calls are blocked,
up. The implementation may pick one at random, so the order in which blocked :meth:`release` will wake exactly one of them up. The implementation may
threads are awakened should not be relied on. There is no return value in this pick one at random, so the order in which blocked threads are awakened
case. 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 true, do the same thing as when called
without arguments, and return true. without arguments, and return true.
When invoked with *blocking* set to false, do not block. If a call without an When invoked with *blocking* set to false, do not block. If a call
argument would block, return false immediately; otherwise, do the same thing as without an argument would block, return false immediately; otherwise, do
when called without arguments, and return true. the same thing as when called without arguments, and return true.
.. method:: release()
.. method:: Semaphore.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
Release a semaphore, incrementing the internal counter by one. When it was zero than zero again, wake up that thread.
on entry and another thread is waiting for it to become larger than zero again,
wake up that thread.
.. _semaphore-examples: .. _semaphore-examples:
@ -675,36 +662,33 @@ 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() isSet()
Event.isSet()
Return true if and only if the internal flag is true. Return true if and only if the internal flag is true.
.. method:: set()
.. method:: Event.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.
Set the internal flag to true. All threads waiting for it to become true are .. method:: clear()
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:: Event.clear() .. method:: wait([timeout])
Reset the internal flag to false. Subsequently, threads calling :meth:`wait` Block until the internal flag is true. If the internal flag is true on
will block until :meth:`.set` is called to set the internal flag to true entry, return immediately. Otherwise, block until another thread calls
again. :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
.. method:: Event.wait([timeout]) floating point number specifying a timeout for the operation in seconds
(or fractions thereof).
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 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. ``True`` except if a timeout is given and the operation times out.
@ -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: