traverseda
/
cpython
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

#4245: move Thread section to the top.

This commit is contained in:
Georg Brandl 2008-11-06 10:20:49 +00:00
parent b9bfea712f
commit 01ba86af46
1 changed files with 160 additions and 160 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

320
Doc/library/threading.rst
View File

@ -180,6 +180,166 @@ when implemented, are mapped to module-level functions.
All of the methods described below are executed atomically. 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:`isAlive`
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.
.. versionadded:: 2.6
.. method:: Thread.is_alive()
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
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:
Lock Objects Lock Objects
@ -539,166 +699,6 @@ An event object manages an internal flag that can be set to true with the
thereof). 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:`isAlive`
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.
.. versionadded:: 2.6
.. method:: Thread.is_alive()
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
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:
Timer Objects Timer Objects