Restructured library documentation

Doc/lib/libthread.tex

@@ -0,0 +1,89 @@
+\section{Built-in Module \sectcode{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 and Sun Sparc systems only.
+
+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 raises
+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_thread}{}
+Exit the current thread silently.  Other threads continue to run.
+\strong{Caveat:} code in pending \code{finally} clauses is not executed.
+\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}
+
+Lock objects have the following methods:
+
+\renewcommand{\indexsubitem}{(lock method)}
+\begin{funcdesc}{acquire}{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.
+
+\item
+Calling \code{sys.exit(\var{status})} or executing
+\code{raise SystemExit, \var{status}} is almost equivalent to calling
+\code{thread.exit_prog(\var{status})}, except that the former ways of
+exiting the entire program do honor \code{finally} clauses in the
+current thread (but not in other threads).
+
+\item
+Not all built-in functions that may block waiting for I/O allow other
+threads to run, although the most popular ones (\code{sleep},
+\code{read}, \code{select}) work as expected.
+
+\end{itemize}