rest25/library/thread.rst => rest262/library/thread.rst
n1- 
2:mod:`thread` --- Multiple threads of control
3=============================================
4
5.. module:: thread
6   :synopsis: Create multiple threads of control within one interpreter.
n6+ 
7+.. note::
8+   The :mod:`thread` module has been renamed to :mod:`_thread` in Python 3.0.
9+   The :term:`2to3` tool will automatically adapt imports when converting your
10+   sources to 3.0; however, you should consider using the high-level
11+   :mod:`threading` module instead.
7
8
9.. index::
10   single: light-weight processes
11   single: processes, light-weight
12   single: binary semaphores
13   single: semaphores, binary
14
15This module provides low-level primitives for working with multiple threads
n16-(a.k.a. :dfn:`light-weight processes` or :dfn:`tasks`) --- multiple threads of
n21+(also called :dfn:`light-weight processes` or :dfn:`tasks`) --- multiple threads of
17control sharing their global data space.  For synchronization, simple locks
n18-(a.k.a. :dfn:`mutexes` or :dfn:`binary semaphores`) are provided.
n23+(also called :dfn:`mutexes` or :dfn:`binary semaphores`) are provided.
24+The :mod:`threading` module provides an easier to use and higher-level
25+threading API built on top of this module.
19
20.. index::
21   single: pthreads
22   pair: threads; POSIX
23
24The module is optional.  It is supported on Windows, Linux, SGI IRIX, Solaris
252.x, as well as on systems that have a POSIX thread (a.k.a. "pthread")
26implementation.  For systems lacking the :mod:`thread` module, the
58   .. versionadded:: 2.3
59
60
61.. function:: exit()
62
63   Raise the :exc:`SystemExit` exception.  When not caught, this will cause the
64   thread to exit silently.
65
n66-.. % \begin{funcdesc}{exit_prog}{status}
n73+..
74+   function:: exit_prog(status)
75+ 
67-.. % Exit all threads and report the value of the integer argument
76+      Exit all threads and report the value of the integer argument
68-.. % \var{status} as the exit status of the entire program.
77+      *status* as the exit status of the entire program.
69-.. % \strong{Caveat:} code in pending \keyword{finally} clauses, in this thread
78+      **Caveat:** code in pending :keyword:`finally` clauses, in this thread
70-.. % or in other threads, is not executed.
79+      or in other threads, is not executed.
71-.. % \end{funcdesc}
72
73
74.. function:: allocate_lock()
75
76   Return a new lock object.  Methods of locks are described below.  The lock is
77   initially unlocked.
78
79
86
87
88.. function:: stack_size([size])
89
90   Return the thread stack size used when creating new threads.  The optional
91   *size* argument specifies the stack size to be used for subsequently created
92   threads, and must be 0 (use platform or configured default) or a positive
93   integer value of at least 32,768 (32kB). If changing the thread stack size is
n94-   unsupported, a :exc:`ThreadError` is raised.  If the specified stack size is
n102+   unsupported, the :exc:`error` exception is raised.  If the specified stack size is
95   invalid, a :exc:`ValueError` is raised and the stack size is unmodified.  32kB
96   is currently the minimum supported stack size value to guarantee sufficient
97   stack space for the interpreter itself.  Note that some platforms may have
98   particular restrictions on values for the stack size, such as requiring a
99   minimum stack size > 32kB or requiring allocation in multiples of the system
100   memory page size - platform documentation should be referred to for more
101   information (4kB pages are common; using multiples of 4096 for the stack size is
102   the suggested approach in the absence of more specific information).
127.. method:: lock.locked()
128
129   Return the status of the lock: ``True`` if it has been acquired by some thread,
130   ``False`` if not.
131
132In addition to these methods, lock objects can also be used via the
133:keyword:`with` statement, e.g.::
134
t135-   from __future__ import with_statement
136   import thread
137
138   a_lock = thread.allocate_lock()
139
140   with a_lock:
141       print "a_lock is locked while this executes"
142
143**Caveats:**
Legends
Colors
 Added 
Changed
Deleted
Links
(f)irst change
(n)ext change
(t)op