n | |
| :mod:`thread` --- Multiple threads of control |
| ============================================= |
| |
| .. module:: thread |
| :synopsis: Create multiple threads of control within one interpreter. |
n | |
| .. note:: |
| The :mod:`thread` module has been renamed to :mod:`_thread` in Python 3.0. |
| The :term:`2to3` tool will automatically adapt imports when converting your |
| sources to 3.0; however, you should consider using the high-level |
| :mod:`threading` module instead. |
| |
| |
| .. index:: |
| single: light-weight processes |
| single: processes, light-weight |
| single: binary semaphores |
| single: semaphores, binary |
| |
| This module provides low-level primitives for working with multiple threads |
n | (a.k.a. :dfn:`light-weight processes` or :dfn:`tasks`) --- multiple threads of |
n | (also called :dfn:`light-weight processes` or :dfn:`tasks`) --- multiple threads of |
| control sharing their global data space. For synchronization, simple locks |
n | (a.k.a. :dfn:`mutexes` or :dfn:`binary semaphores`) are provided. |
n | (also called :dfn:`mutexes` or :dfn:`binary semaphores`) are provided. |
| The :mod:`threading` module provides an easier to use and higher-level |
| threading API built on top of this module. |
| |
| .. index:: |
| single: pthreads |
| pair: threads; POSIX |
| |
| The module is optional. It is supported on Windows, Linux, SGI IRIX, Solaris |
| 2.x, as well as on systems that have a POSIX thread (a.k.a. "pthread") |
| implementation. For systems lacking the :mod:`thread` module, the |
| .. versionadded:: 2.3 |
| |
| |
| .. function:: exit() |
| |
| Raise the :exc:`SystemExit` exception. When not caught, this will cause the |
| thread to exit silently. |
| |
n | .. % \begin{funcdesc}{exit_prog}{status} |
n | .. |
| function:: exit_prog(status) |
| |
| .. % Exit all threads and report the value of the integer argument |
| Exit all threads and report the value of the integer argument |
| .. % \var{status} as the exit status of the entire program. |
| *status* as the exit status of the entire program. |
| .. % \strong{Caveat:} code in pending \keyword{finally} clauses, in this thread |
| **Caveat:** code in pending :keyword:`finally` clauses, in this thread |
| .. % or in other threads, is not executed. |
| or in other threads, is not executed. |
| .. % \end{funcdesc} |
| |
| |
| .. function:: allocate_lock() |
| |
| Return a new lock object. Methods of locks are described below. The lock is |
| initially unlocked. |
| |
| |
| |
| |
| .. function:: stack_size([size]) |
| |
| Return the thread stack size used when creating new threads. The optional |
| *size* argument specifies the stack size to be used for subsequently created |
| threads, and must be 0 (use platform or configured default) or a positive |
| integer value of at least 32,768 (32kB). If changing the thread stack size is |
n | unsupported, a :exc:`ThreadError` is raised. If the specified stack size is |
n | unsupported, the :exc:`error` exception is raised. If the specified stack size is |
| invalid, a :exc:`ValueError` is raised and the stack size is unmodified. 32kB |
| is currently the minimum supported stack size value to guarantee sufficient |
| stack space for the interpreter itself. Note that some platforms may have |
| particular restrictions on values for the stack size, such as requiring a |
| minimum stack size > 32kB or requiring allocation in multiples of the system |
| memory page size - platform documentation should be referred to for more |
| information (4kB pages are common; using multiples of 4096 for the stack size is |
| the suggested approach in the absence of more specific information). |
| .. method:: lock.locked() |
| |
| Return the status of the lock: ``True`` if it has been acquired by some thread, |
| ``False`` if not. |
| |
| In addition to these methods, lock objects can also be used via the |
| :keyword:`with` statement, e.g.:: |
| |
t | from __future__ import with_statement |
| import thread |
| |
| a_lock = thread.allocate_lock() |
| |
| with a_lock: |
| print "a_lock is locked while this executes" |
| |
| **Caveats:** |