174 lines
6.4 KiB
TeX
174 lines
6.4 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, 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 \module{thread}
|
|
module, the \refmodule[dummythread]{dummy_thread} module is available.
|
|
It duplicates this module's interface and can be
|
|
used as a drop-in replacement.
|
|
\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 and return its identifier. 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}{interrupt_main}{}
|
|
Raise a \exception{KeyboardInterrupt} exception in the main thread. A subthread
|
|
can use this function to interrupt the main thread.
|
|
\versionadded{2.3}
|
|
\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_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 \keyword{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}
|
|
|
|
\begin{funcdesc}{stack_size}{\optional{size}}
|
|
Return the thread stack size used when creating new threads. The
|
|
optional \var{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 unsupported, a \exception{ThreadError}
|
|
is raised. If the specified stack size is invalid, a \exception{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).
|
|
Availability: Windows, systems with \POSIX{} threads.
|
|
\versionadded{2.5}
|
|
\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). 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. The
|
|
return value is \code{True} if the lock is acquired successfully,
|
|
\code{False} 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{True} if it has been acquired by
|
|
some thread, \code{False} if not.
|
|
\end{methoddesc}
|
|
|
|
In addition to these methods, lock objects can also be used via the
|
|
\keyword{with} statement, e.g.:
|
|
|
|
\begin{verbatim}
|
|
from __future__ import with_statement
|
|
import thread
|
|
|
|
a_lock = thread.allocate_lock()
|
|
|
|
with a_lock:
|
|
print "a_lock is locked while this executes"
|
|
\end{verbatim}
|
|
|
|
\strong{Caveats:}
|
|
|
|
\begin{itemize}
|
|
\item
|
|
Threads interact strangely with interrupts: the
|
|
\exception{KeyboardInterrupt} exception will be received by an
|
|
arbitrary thread. (When the \refmodule{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()}.
|
|
|
|
\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}
|