Merged revisions 67117-67119,67123-67124,67143 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r67117 | georg.brandl | 2008-11-06 11:17:58 +0100 (Thu, 06 Nov 2008) | 2 lines
#4268: Use correct module for two toplevel functions.
........
r67118 | georg.brandl | 2008-11-06 11:19:11 +0100 (Thu, 06 Nov 2008) | 2 lines
#4267: small fixes in sqlite3 docs.
........
r67119 | georg.brandl | 2008-11-06 11:20:49 +0100 (Thu, 06 Nov 2008) | 2 lines
#4245: move Thread section to the top.
........
r67123 | georg.brandl | 2008-11-06 19:49:15 +0100 (Thu, 06 Nov 2008) | 2 lines
#4247: add "pass" examples to tutorial.
........
r67124 | andrew.kuchling | 2008-11-06 20:23:02 +0100 (Thu, 06 Nov 2008) | 1 line
Fix grammar error; reword two paragraphs
........
r67143 | georg.brandl | 2008-11-07 09:27:39 +0100 (Fri, 07 Nov 2008) | 2 lines
Fix syntax.
........
diff --git a/Doc/library/threading.rst b/Doc/library/threading.rst
index 9cc62be..01e7136 100644
--- a/Doc/library/threading.rst
+++ b/Doc/library/threading.rst
@@ -168,6 +168,163 @@
All of the methods described below are executed atomically.
+.. _thread-objects:
+
+Thread Objects
+--------------
+
+This class represents an activity that is run in a separate thread of control.
+There are two ways to specify the activity: by passing a callable object to the
+constructor, or by overriding the :meth:`run` method in a subclass. No other
+methods (except for the constructor) should be overridden in a subclass. In
+other words, *only* override the :meth:`__init__` and :meth:`run` methods of
+this class.
+
+Once a thread object is created, its activity must be started by calling the
+thread's :meth:`start` method. This invokes the :meth:`run` method in a
+separate thread of control.
+
+Once the thread's activity is started, the thread is considered 'alive'. It
+stops being alive when its :meth:`run` method terminates -- either normally, or
+by raising an unhandled exception. The :meth:`is_alive` method tests whether the
+thread is alive.
+
+Other threads can call a thread's :meth:`join` method. This blocks the calling
+thread until the thread whose :meth:`join` method is called is terminated.
+
+A thread has a name. The name can be passed to the constructor, and read or
+changed through the :attr:`name` attribute.
+
+A thread can be flagged as a "daemon thread". The significance of this flag is
+that the entire Python program exits when only daemon threads are left. The
+initial value is inherited from the creating thread. The flag can be set
+through the :attr:`daemon` attribute.
+
+There is a "main thread" object; this corresponds to the initial thread of
+control in the Python program. It is not a daemon thread.
+
+There is the possibility that "dummy thread objects" are created. These are
+thread objects corresponding to "alien threads", which are threads of control
+started outside the threading module, such as directly from C code. Dummy
+thread objects have limited functionality; they are always considered alive and
+daemonic, and cannot be :meth:`join`\ ed. They are never deleted, since it is
+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:
+
+ *group* should be ``None``; reserved for future extension when a
+ :class:`ThreadGroup` class is implemented.
+
+ *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.
+
+ *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.
+
+ This method will raise a :exc:`RuntimeException` if called more than once on the
+ same thread object.
+
+
+.. method:: Thread.run()
+
+ Method representing the thread's activity.
+
+ 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:: Thread.join([timeout])
+
+ 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 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.
+
+ When the *timeout* argument is not present or ``None``, the operation will block
+ until the thread terminates.
+
+ 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.
+
+
+.. method:: Thread.getName()
+ Thread.setName()
+
+ Old API for :attr:`~Thread.name`.
+
+
+.. attribute:: Thread.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.
+
+
+.. 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 :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.
+
+
+.. method:: Thread.is_alive()
+
+ 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
+
+ The thread's daemon flag. This must be set before :meth:`start` is called,
+ otherwise :exc:`RuntimeError` is raised.
+
+ The initial value is inherited from the creating thread.
+
+ The entire Python program exits when no alive non-daemon threads are left.
+
+
.. _lock-objects:
Lock Objects
@@ -525,163 +682,6 @@
thereof).
-.. _thread-objects:
-
-Thread Objects
---------------
-
-This class represents an activity that is run in a separate thread of control.
-There are two ways to specify the activity: by passing a callable object to the
-constructor, or by overriding the :meth:`run` method in a subclass. No other
-methods (except for the constructor) should be overridden in a subclass. In
-other words, *only* override the :meth:`__init__` and :meth:`run` methods of
-this class.
-
-Once a thread object is created, its activity must be started by calling the
-thread's :meth:`start` method. This invokes the :meth:`run` method in a
-separate thread of control.
-
-Once the thread's activity is started, the thread is considered 'alive'. It
-stops being alive when its :meth:`run` method terminates -- either normally, or
-by raising an unhandled exception. The :meth:`is_alive` method tests whether the
-thread is alive.
-
-Other threads can call a thread's :meth:`join` method. This blocks the calling
-thread until the thread whose :meth:`join` method is called is terminated.
-
-A thread has a name. The name can be passed to the constructor, and read or
-changed through the :attr:`name` attribute.
-
-A thread can be flagged as a "daemon thread". The significance of this flag is
-that the entire Python program exits when only daemon threads are left. The
-initial value is inherited from the creating thread. The flag can be set
-through the :attr:`daemon` attribute.
-
-There is a "main thread" object; this corresponds to the initial thread of
-control in the Python program. It is not a daemon thread.
-
-There is the possibility that "dummy thread objects" are created. These are
-thread objects corresponding to "alien threads", which are threads of control
-started outside the threading module, such as directly from C code. Dummy
-thread objects have limited functionality; they are always considered alive and
-daemonic, and cannot be :meth:`join`\ ed. They are never deleted, since it is
-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:
-
- *group* should be ``None``; reserved for future extension when a
- :class:`ThreadGroup` class is implemented.
-
- *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.
-
- *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.
-
- This method will raise a :exc:`RuntimeException` if called more than once on the
- same thread object.
-
-
-.. method:: Thread.run()
-
- Method representing the thread's activity.
-
- 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:: Thread.join([timeout])
-
- 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 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.
-
- When the *timeout* argument is not present or ``None``, the operation will block
- until the thread terminates.
-
- 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.
-
-
-.. method:: Thread.getName()
- Thread.setName()
-
- Old API for :attr:`~Thread.name`.
-
-
-.. attribute:: Thread.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.
-
-
-.. 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 :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.
-
-
-.. method:: Thread.is_alive()
-
- 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
-
- The thread's daemon flag. This must be set before :meth:`start` is called,
- otherwise :exc:`RuntimeError` is raised.
-
- The initial value is inherited from the creating thread.
-
- The entire Python program exits when no alive non-daemon threads are left.
-
-
.. _timer-objects:
Timer Objects