mirror of
https://github.com/python/cpython.git
synced 2024-12-01 03:01:36 +01:00
138 lines
4.8 KiB
TeX
138 lines
4.8 KiB
TeX
\section{\module{thread} ---
|
|
Multiple threads of control.}
|
|
\declaremodule{builtin}{thread}
|
|
|
|
\modulesynopsis{Create multiple threads of control within one interpreter.}
|
|
|
|
|
|
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:
|
|
|
|
\begin{excdesc}{error}
|
|
Raised on thread-specific errors.
|
|
\end{excdesc}
|
|
|
|
\begin{datadesc}{LockType}
|
|
This is the type of lock objects.
|
|
\end{datadesc}
|
|
|
|
\begin{funcdesc}{start_new_thread}{function, args\optional{kwargs}}
|
|
Start a new thread. The thread executes the function \var{function}
|
|
with the argument list \var{args} (which must be a tuple). The
|
|
optional \var{kwargs} argument specifies a dictionary of keyword
|
|
arguments. 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}{}
|
|
Raise the \exception{SystemExit} exception. When not caught, this
|
|
will cause the thread to exit silently.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{exit_thread}{}
|
|
\deprecated{1.5.2}{Use \function{exit()}.}
|
|
This is an obsolete synonym for \function{exit()}.
|
|
\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:
|
|
|
|
\begin{methoddesc}[lock]{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 \code{1} if the lock is acquired successfully,
|
|
\code{0} if not.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[lock]{release}{}
|
|
Releases the lock. The lock must have been acquired earlier, but not
|
|
necessarily by the same thread.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[lock]{locked}{}
|
|
Return the status of the lock:\ \code{1} if it has been acquired by
|
|
some thread, \code{0} if not.
|
|
\end{methoddesc}
|
|
|
|
\strong{Caveats:}
|
|
|
|
\begin{itemize}
|
|
\item
|
|
Threads interact strangely with interrupts: the
|
|
\exception{KeyboardInterrupt} exception will be received by an
|
|
arbitrary thread. (When the \module{signal}\refbimodindex{signal}
|
|
module is available, interrupts always go to the main thread.)
|
|
|
|
\item
|
|
Calling \function{sys.exit()} or raising the \exception{SystemExit}
|
|
exception is equivalent to calling \function{exit_thread()}.
|
|
|
|
\item
|
|
Not all built-in functions that may block waiting for I/O allow other
|
|
threads to run. (The most popular ones (\function{time.sleep()},
|
|
\method{\var{file}.read()}, \function{select.select()}) work as
|
|
expected.)
|
|
|
|
\item
|
|
It is not possible to interrupt the \method{acquire()} method on a lock
|
|
--- the \exception{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 \keyword{try} ... \keyword{finally} clauses or executing
|
|
object destructors.
|
|
\indexii{threads}{IRIX}
|
|
|
|
\item
|
|
When the main thread exits, it does not do any of its usual cleanup
|
|
(except that \keyword{try} ... \keyword{finally} clauses are honored),
|
|
and the standard I/O files are not flushed.
|
|
|
|
\end{itemize}
|