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.
........

1 files changed, 153 insertions, 170 deletions

diff --git a/Doc/library/threading.rst b/Doc/library/threading.rst
index d880157..ce91750 100644
--- a/Doc/library/threading.rst
+++ b/Doc/library/threading.rst
@@ -1,4 +1,3 @@
-
 :mod:`threading` --- Higher-level threading interface
 =====================================================
 
@@ -213,7 +212,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 +221,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 +488,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 +571,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:
@@ -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.
 
+   .. 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 +703,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: