mirror of https://github.com/python/cpython.git
103 lines
3.6 KiB
TeX
103 lines
3.6 KiB
TeX
\section{Built-in Module \sectcode{thread}}
|
|
\label{module-thread}
|
|
\bimodindex{thread}
|
|
|
|
This module provides low-level primitives for working with multiple
|
|
threads (a.k.a.\ \dfn{light-weight processes} or \dfn{tasks}) --- multiple
|
|
threads of control sharing their global data space. For
|
|
synchronization, simple locks (a.k.a.\ \dfn{mutexes} or \dfn{binary
|
|
semaphores}) are provided.
|
|
|
|
The module is optional and supported on SGI IRIX 4.x and 5.x and Sun
|
|
Solaris 2.x systems, as well as on systems that have a PTHREAD
|
|
implementation (e.g.\ KSR).
|
|
|
|
It defines the following constant and functions:
|
|
|
|
\renewcommand{\indexsubitem}{(in module thread)}
|
|
\begin{excdesc}{error}
|
|
Raised on thread-specific errors.
|
|
\end{excdesc}
|
|
|
|
\begin{funcdesc}{start_new_thread}{func\, arg}
|
|
Start a new thread. The thread executes the function \var{func}
|
|
with the argument list \var{arg} (which must be a tuple). When the
|
|
function returns, the thread silently exits. When the function
|
|
terminates with an unhandled exception, a stack trace is printed and
|
|
then the thread exits (but other threads continue to run).
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{exit}{}
|
|
This is a shorthand for \code{thread.exit_thread()}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{exit_thread}{}
|
|
Raise the \code{SystemExit} exception. When not caught, this will
|
|
cause the thread to exit silently.
|
|
\end{funcdesc}
|
|
|
|
%\begin{funcdesc}{exit_prog}{status}
|
|
%Exit all threads and report the value of the integer argument
|
|
%\var{status} as the exit status of the entire program.
|
|
%\strong{Caveat:} code in pending \code{finally} clauses, in this thread
|
|
%or in other threads, is not executed.
|
|
%\end{funcdesc}
|
|
|
|
\begin{funcdesc}{allocate_lock}{}
|
|
Return a new lock object. Methods of locks are described below. The
|
|
lock is initially unlocked.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{get_ident}{}
|
|
Return the `thread identifier' of the current thread. This is a
|
|
nonzero integer. Its value has no direct meaning; it is intended as a
|
|
magic cookie to be used e.g. to index a dictionary of thread-specific
|
|
data. Thread identifiers may be recycled when a thread exits and
|
|
another thread is created.
|
|
\end{funcdesc}
|
|
|
|
Lock objects have the following methods:
|
|
|
|
\renewcommand{\indexsubitem}{(lock method)}
|
|
\begin{funcdesc}{acquire}{\optional{waitflag}}
|
|
Without the optional argument, this method acquires the lock
|
|
unconditionally, if necessary waiting until it is released by another
|
|
thread (only one thread at a time can acquire a lock --- that's their
|
|
reason for existence), and returns \code{None}. If the integer
|
|
\var{waitflag} argument is present, the action depends on its value:\
|
|
if it is zero, the lock is only acquired if it can be acquired
|
|
immediately without waiting, while if it is nonzero, the lock is
|
|
acquired unconditionally as before. If an argument is present, the
|
|
return value is 1 if the lock is acquired successfully, 0 if not.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{release}{}
|
|
Releases the lock. The lock must have been acquired earlier, but not
|
|
necessarily by the same thread.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{locked}{}
|
|
Return the status of the lock:\ 1 if it has been acquired by some
|
|
thread, 0 if not.
|
|
\end{funcdesc}
|
|
|
|
{\bf Caveats:}
|
|
|
|
\begin{itemize}
|
|
\item
|
|
Threads interact strangely with interrupts: the
|
|
\code{KeyboardInterrupt} exception will be received by an arbitrary
|
|
thread. (When the \code{signal} module is available, interrupts
|
|
always go to the main thread.)
|
|
|
|
\item
|
|
Calling \code{sys.exit()} or raising the \code{SystemExit} is
|
|
equivalent to calling \code{thread.exit_thread()}.
|
|
|
|
\item
|
|
Not all built-in functions that may block waiting for I/O allow other
|
|
threads to run. (The most popular ones (\code{sleep}, \code{read},
|
|
\code{select}) work as expected.)
|
|
|
|
\end{itemize}
|