add hg and python

1 files changed, 173 insertions, 0 deletions

diff --git a/sys/src/cmd/python/Doc/lib/libthread.tex b/sys/src/cmd/python/Doc/lib/libthread.tex
new file mode 100644
index 000000000..d007eecde
--- /dev/null
+++ b/sys/src/cmd/python/Doc/lib/libthread.tex
@@ -0,0 +1,173 @@
+\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}