126 lines
4.4 KiB
TeX
126 lines
4.4 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.
|
|
\index{light-weight processes}
|
|
\index{processes, light-weight}
|
|
\index{binary semaphores}
|
|
\index{semaphores, binary}
|
|
|
|
The module is optional. It is supported on Windows NT and '95, SGI
|
|
IRIX, Solaris 2.x, as well as on systems that have a \POSIX{} thread
|
|
(a.k.a. ``pthread'') implementation.
|
|
\index{pthreads}
|
|
\indexii{threads}{\POSIX{}}
|
|
|
|
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}
|
|
|
|
\strong{Caveats:}
|
|
|
|
\begin{itemize}
|
|
\item
|
|
Threads interact strangely with interrupts: the
|
|
\code{KeyboardInterrupt} exception will be received by an arbitrary
|
|
thread. (When the \code{signal}\refbimodindex{signal} module is
|
|
available, interrupts always go to the main thread.)
|
|
|
|
\item
|
|
Calling \code{sys.exit()} or raising the \code{SystemExit} exception 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.)
|
|
|
|
\item
|
|
It is not possible to interrupt the \code{acquire()} method on a lock
|
|
-- the \code{KeyboardInterrupt} exception will happen after the lock
|
|
has been acquired.
|
|
|
|
\item
|
|
When the main thread exits, it is system defined whether the other
|
|
threads survive. On SGI IRIX using the native thread implementation,
|
|
they survive. On most other systems, they are killed without
|
|
executing ``try-finally'' clauses or executing object destructors.
|
|
\indexii{threads}{IRIX}
|
|
|
|
\item
|
|
When the main thread exits, it doesn't do any of its usual cleanup
|
|
(except that ``try-finally'' clauses are honored), and the standard
|
|
I/O files are not flushed.
|
|
|
|
\end{itemize}
|