add hg and python

1 files changed, 716 insertions, 0 deletions

diff --git a/sys/src/cmd/python/Doc/lib/libthreading.tex b/sys/src/cmd/python/Doc/lib/libthreading.tex
new file mode 100644
index 000000000..eb8778b20
--- /dev/null
+++ b/sys/src/cmd/python/Doc/lib/libthreading.tex
@@ -0,0 +1,716 @@
+\section{\module{threading} ---
+         Higher-level threading interface}
+
+\declaremodule{standard}{threading}
+\modulesynopsis{Higher-level threading interface.}
+
+
+This module constructs higher-level threading interfaces on top of the 
+lower level \refmodule{thread} module.
+
+The \refmodule[dummythreading]{dummy_threading} module is provided for
+situations where \module{threading} cannot be used because
+\refmodule{thread} is missing.
+
+This module defines the following functions and objects:
+
+\begin{funcdesc}{activeCount}{}
+Return the number of \class{Thread} objects currently alive.  The
+returned count is equal to the length of the list returned by
+\function{enumerate()}.
+\end{funcdesc}
+
+\begin{funcdesc}{Condition}{}
+A factory function that returns a new condition variable object.
+A condition variable allows one or more threads to wait until they
+are notified by another thread.
+\end{funcdesc}
+
+\begin{funcdesc}{currentThread}{}
+Return the current \class{Thread} object, corresponding to the
+caller's thread of control.  If the caller's thread of control was not
+created through the
+\module{threading} module, a dummy thread object with limited functionality
+is returned.
+\end{funcdesc}
+
+\begin{funcdesc}{enumerate}{}
+Return a list of all \class{Thread} objects currently alive.  The list
+includes daemonic threads, dummy thread objects created by
+\function{currentThread()}, and the main thread.  It excludes
+terminated threads and threads that have not yet been started.
+\end{funcdesc}
+
+\begin{funcdesc}{Event}{}
+A factory function that returns a new event object.  An event manages
+a flag that can be set to true with the \method{set()} method and
+reset to false with the \method{clear()} method.  The \method{wait()}
+method blocks until the flag is true.
+\end{funcdesc}
+
+\begin{classdesc*}{local}{}
+A class that represents thread-local data.  Thread-local data are data
+whose values are thread specific.  To manage thread-local data, just
+create an instance of \class{local} (or a subclass) and store
+attributes on it:
+
+\begin{verbatim}
+mydata = threading.local()
+mydata.x = 1
+\end{verbatim}
+
+The instance's values will be different for separate threads.
+
+For more details and extensive examples, see the documentation string
+of the \module{_threading_local} module.
+
+\versionadded{2.4}
+\end{classdesc*}
+
+\begin{funcdesc}{Lock}{}
+A factory function that returns a new primitive lock object.  Once
+a thread has acquired it, subsequent attempts to acquire it block,
+until it is released; any thread may release it.
+\end{funcdesc}
+
+\begin{funcdesc}{RLock}{}
+A factory function that returns a new reentrant lock object.
+A reentrant lock must be released by the thread that acquired it.
+Once a thread has acquired a reentrant lock, the same thread may
+acquire it again without blocking; the thread must release it once
+for each time it has acquired it.
+\end{funcdesc}
+
+\begin{funcdesc}{Semaphore}{\optional{value}}
+A factory function that returns a new semaphore object.  A
+semaphore manages a counter representing the number of \method{release()}
+calls minus the number of \method{acquire()} calls, plus an initial value.
+The \method{acquire()} method blocks if necessary until it can return
+without making the counter negative.  If not given, \var{value} defaults to
+1. 
+\end{funcdesc}
+
+\begin{funcdesc}{BoundedSemaphore}{\optional{value}}
+A factory function that returns a new bounded semaphore object.  A bounded
+semaphore checks to make sure its current value doesn't exceed its initial
+value.  If it does, \exception{ValueError} is raised. In most situations
+semaphores are used to guard resources with limited capacity.  If the
+semaphore is released too many times it's a sign of a bug.  If not given,
+\var{value} defaults to 1. 
+\end{funcdesc}
+
+\begin{classdesc*}{Thread}{}
+A class that represents a thread of control.  This class can be safely
+subclassed in a limited fashion.
+\end{classdesc*}
+
+\begin{classdesc*}{Timer}{}
+A thread that executes a function after a specified interval has passed.
+\end{classdesc*}
+
+\begin{funcdesc}{settrace}{func}
+Set a trace function\index{trace function} for all threads started
+from the \module{threading} module.  The \var{func} will be passed to 
+\function{sys.settrace()} for each thread, before its \method{run()}
+method is called.
+\versionadded{2.3}
+\end{funcdesc}
+
+\begin{funcdesc}{setprofile}{func}
+Set a profile function\index{profile function} for all threads started
+from the \module{threading} module.  The \var{func} will be passed to 
+\function{sys.setprofile()} for each thread, before its \method{run()}
+method is called.
+\versionadded{2.3}
+\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}
+
+Detailed interfaces for the objects are documented below.  
+
+The design of this module is loosely based on Java's threading model.
+However, where Java makes locks and condition variables basic behavior
+of every object, they are separate objects in Python.  Python's \class{Thread}
+class supports a subset of the behavior of Java's Thread class;
+currently, there are no priorities, no thread groups, and threads
+cannot be destroyed, stopped, suspended, resumed, or interrupted.  The
+static methods of Java's Thread class, when implemented, are mapped to
+module-level functions.
+
+All of the methods described below are executed atomically.
+
+
+\subsection{Lock Objects \label{lock-objects}}
+
+A primitive lock is a synchronization primitive that is not owned
+by a particular thread when locked.  In Python, it is currently
+the lowest level synchronization primitive available, implemented
+directly by the \refmodule{thread} extension module.
+
+A primitive lock is in one of two states, ``locked'' or ``unlocked''.
+It is created in the unlocked state.  It has two basic methods,
+\method{acquire()} and \method{release()}.  When the state is
+unlocked, \method{acquire()} changes the state to locked and returns
+immediately.  When the state is locked, \method{acquire()} blocks
+until a call to \method{release()} in another thread changes it to
+unlocked, then the \method{acquire()} call resets it to locked and
+returns.  The \method{release()} method should only be called in the
+locked state; it changes the state to unlocked and returns
+immediately.  When more than one thread is blocked in
+\method{acquire()} waiting for the state to turn to unlocked, only one
+thread proceeds when a \method{release()} call resets the state to
+unlocked; which one of the waiting threads proceeds is not defined,
+and may vary across implementations.
+
+All methods are executed atomically.
+
+\begin{methoddesc}{acquire}{\optional{blocking\code{ = 1}}}
+Acquire a lock, blocking or non-blocking.
+
+When invoked without arguments, block until the lock is
+unlocked, then set it to locked, and return true.  
+
+When invoked with the \var{blocking} argument set to true, do the
+same thing as when called without arguments, and return true.
+
+When invoked with the \var{blocking} argument set to false, do not
+block.  If a call without an argument would block, return false
+immediately; otherwise, do the same thing as when called
+without arguments, and return true.
+\end{methoddesc}
+
+\begin{methoddesc}{release}{}
+Release a lock.
+
+When the lock is locked, reset it to unlocked, and return.  If
+any other threads are blocked waiting for the lock to become
+unlocked, allow exactly one of them to proceed.
+
+Do not call this method when the lock is unlocked.
+
+There is no return value.
+\end{methoddesc}
+
+
+\subsection{RLock Objects \label{rlock-objects}}
+
+A reentrant lock is a synchronization primitive that may be
+acquired multiple times by the same thread.  Internally, it uses
+the concepts of ``owning thread'' and ``recursion level'' in
+addition to the locked/unlocked state used by primitive locks.  In
+the locked state, some thread owns the lock; in the unlocked
+state, no thread owns it.
+
+To lock the lock, a thread calls its \method{acquire()} method; this
+returns once the thread owns the lock.  To unlock the lock, a
+thread calls its \method{release()} method.
+\method{acquire()}/\method{release()} call pairs may be nested; only
+the final \method{release()} (the \method{release()} of the outermost
+pair) resets the lock to unlocked and allows another thread blocked in
+\method{acquire()} to proceed.
+
+\begin{methoddesc}{acquire}{\optional{blocking\code{ = 1}}}
+Acquire a lock, blocking or non-blocking.
+
+When invoked without arguments: if this thread already owns
+the lock, increment the recursion level by one, and return
+immediately.  Otherwise, if another thread owns the lock,
+block until the lock is unlocked.  Once the lock is unlocked
+(not owned by any thread), then grab ownership, set the
+recursion level to one, and return.  If more than one thread
+is blocked waiting until the lock is unlocked, only one at a
+time will be able to grab ownership of the lock.  There is no
+return value in this case.
+
+When invoked with the \var{blocking} argument set to true, do the
+same thing as when called without arguments, and return true.
+
+When invoked with the \var{blocking} argument set to false, do not
+block.  If a call without an argument would block, return false
+immediately; otherwise, do the same thing as when called
+without arguments, and return true.
+\end{methoddesc}
+
+\begin{methoddesc}{release}{}
+Release a lock, decrementing the recursion level.  If after the
+decrement it is zero, reset the lock to unlocked (not owned by any
+thread), and if any other threads are blocked waiting for the lock to
+become unlocked, allow exactly one of them to proceed.  If after the
+decrement the recursion level is still nonzero, the lock remains
+locked and owned by the calling thread.
+
+Only call this method when the calling thread owns the lock.
+Do not call this method when the lock is unlocked.
+
+There is no return value.
+\end{methoddesc}
+
+
+\subsection{Condition Objects \label{condition-objects}}
+
+A condition variable is always associated with some kind of lock;
+this can be passed in or one will be created by default.  (Passing
+one in is useful when several condition variables must share the
+same lock.)
+
+A condition variable has \method{acquire()} and \method{release()}
+methods that call the corresponding methods of the associated lock.
+It also has a \method{wait()} method, and \method{notify()} and
+\method{notifyAll()} methods.  These three must only be called when
+the calling thread has acquired the lock.
+
+The \method{wait()} method releases the lock, and then blocks until it
+is awakened by a \method{notify()} or \method{notifyAll()} call for
+the same condition variable in another thread.  Once awakened, it
+re-acquires the lock and returns.  It is also possible to specify a
+timeout.
+
+The \method{notify()} method wakes up one of the threads waiting for
+the condition variable, if any are waiting.  The \method{notifyAll()}
+method wakes up all threads waiting for the condition variable.
+
+Note: the \method{notify()} and \method{notifyAll()} methods don't
+release the lock; this means that the thread or threads awakened will
+not return from their \method{wait()} call immediately, but only when
+the thread that called \method{notify()} or \method{notifyAll()}
+finally relinquishes ownership of the lock.
+
+Tip: the typical programming style using condition variables uses the
+lock to synchronize access to some shared state; threads that are
+interested in a particular change of state call \method{wait()}
+repeatedly until they see the desired state, while threads that modify
+the state call \method{notify()} or \method{notifyAll()} when they
+change the state in such a way that it could possibly be a desired
+state for one of the waiters.  For example, the following code is a
+generic producer-consumer situation with unlimited buffer capacity:
+
+\begin{verbatim}
+# Consume one item
+cv.acquire()
+while not an_item_is_available():
+    cv.wait()
+get_an_available_item()
+cv.release()
+
+# Produce one item
+cv.acquire()
+make_an_item_available()
+cv.notify()
+cv.release()
+\end{verbatim}
+
+To choose between \method{notify()} and \method{notifyAll()}, consider
+whether one state change can be interesting for only one or several
+waiting threads.  E.g. in a typical producer-consumer situation,
+adding one item to the buffer only needs to wake up one consumer
+thread.
+
+\begin{classdesc}{Condition}{\optional{lock}}
+If the \var{lock} argument is given and not \code{None}, it must be a
+\class{Lock} or \class{RLock} object, and it is used as the underlying
+lock.  Otherwise, a new \class{RLock} object is created and used as
+the underlying lock.
+\end{classdesc}
+
+\begin{methoddesc}{acquire}{*args}
+Acquire the underlying lock.
+This method calls the corresponding method on the underlying
+lock; the return value is whatever that method returns.
+\end{methoddesc}
+
+\begin{methoddesc}{release}{}
+Release the underlying lock.
+This method calls the corresponding method on the underlying
+lock; there is no return value.
+\end{methoddesc}
+
+\begin{methoddesc}{wait}{\optional{timeout}}
+Wait until notified or until a timeout occurs.
+This must only be called when the calling thread has acquired the
+lock.
+
+This method releases the underlying lock, and then blocks until it is
+awakened by a \method{notify()} or \method{notifyAll()} call for the
+same condition variable in another thread, or until the optional
+timeout occurs.  Once awakened or timed out, it re-acquires the lock
+and returns.
+
+When the \var{timeout} argument is present and not \code{None}, it
+should be a floating point number specifying a timeout for the
+operation in seconds (or fractions thereof).
+
+When the underlying lock is an \class{RLock}, it is not released using
+its \method{release()} method, since this may not actually unlock the
+lock when it was acquired multiple times recursively.  Instead, an
+internal interface of the \class{RLock} class is used, which really
+unlocks it even when it has been recursively acquired several times.
+Another internal interface is then used to restore the recursion level
+when the lock is reacquired.
+\end{methoddesc}
+
+\begin{methoddesc}{notify}{}
+Wake up a thread waiting on this condition, if any.
+This must only be called when the calling thread has acquired the
+lock.
+
+This method wakes up one of the threads waiting for the condition
+variable, if any are waiting; it is a no-op if no threads are waiting.
+
+The current implementation wakes up exactly one thread, if any are
+waiting.  However, it's not safe to rely on this behavior.  A future,
+optimized implementation may occasionally wake up more than one
+thread.
+
+Note: the awakened thread does not actually return from its
+\method{wait()} call until it can reacquire the lock.  Since
+\method{notify()} does not release the lock, its caller should.
+\end{methoddesc}
+
+\begin{methoddesc}{notifyAll}{}
+Wake up all threads waiting on this condition.  This method acts like
+\method{notify()}, but wakes up all waiting threads instead of one.
+\end{methoddesc}
+
+
+\subsection{Semaphore Objects \label{semaphore-objects}}
+
+This is one of the oldest synchronization primitives in the history of
+computer science, invented by the early Dutch computer scientist
+Edsger W. Dijkstra (he used \method{P()} and \method{V()} instead of
+\method{acquire()} and \method{release()}).
+
+A semaphore manages an internal counter which is decremented by each
+\method{acquire()} call and incremented by each \method{release()}
+call.  The counter can never go below zero; when \method{acquire()}
+finds that it is zero, it blocks, waiting until some other thread
+calls \method{release()}.
+
+\begin{classdesc}{Semaphore}{\optional{value}}
+The optional argument gives the initial value for the internal
+counter; it defaults to \code{1}.
+\end{classdesc}
+
+\begin{methoddesc}{acquire}{\optional{blocking}}
+Acquire a semaphore.
+
+When invoked without arguments: if the internal counter is larger than
+zero on entry, decrement it by one and return immediately.  If it is
+zero on entry, block, waiting until some other thread has called
+\method{release()} to make it larger than zero.  This is done with
+proper interlocking so that if multiple \method{acquire()} calls are
+blocked, \method{release()} will wake exactly one of them up.  The
+implementation may pick one at random, so the order in which blocked
+threads are awakened should not be relied on.  There is no return
+value in this case.
+
+When invoked with \var{blocking} set to true, do the same thing as
+when called without arguments, and return true.
+
+When invoked with \var{blocking} set to false, do not block.  If a
+call without an argument would block, return false immediately;
+otherwise, do the same thing as when called without arguments, and
+return true.
+\end{methoddesc}
+
+\begin{methoddesc}{release}{}
+Release a semaphore,
+incrementing the internal counter by one.  When it was zero on
+entry and another thread is waiting for it to become larger
+than zero again, wake up that thread.
+\end{methoddesc}
+
+
+\subsubsection{\class{Semaphore} Example \label{semaphore-examples}}
+
+Semaphores are often used to guard resources with limited capacity, for
+example, a database server.  In any situation where the size of the resource
+size is fixed, you should use a bounded semaphore.  Before spawning any
+worker threads, your main thread would initialize the semaphore:
+
+\begin{verbatim}
+maxconnections = 5
+...
+pool_sema = BoundedSemaphore(value=maxconnections)
+\end{verbatim}
+
+Once spawned, worker threads call the semaphore's acquire and release
+methods when they need to connect to the server:
+
+\begin{verbatim}
+pool_sema.acquire()
+conn = connectdb()
+... use connection ...
+conn.close()
+pool_sema.release()
+\end{verbatim}
+
+The use of a bounded semaphore reduces the chance that a programming error
+which causes the semaphore to be released more than it's acquired will go
+undetected.
+
+
+\subsection{Event Objects \label{event-objects}}
+
+This is one of the simplest mechanisms for communication between
+threads: one thread signals an event and other threads wait for it.
+
+An event object manages an internal flag that can be set to true with
+the \method{set()} method and reset to false with the \method{clear()}
+method.  The \method{wait()} method blocks until the flag is true.
+
+
+\begin{classdesc}{Event}{}
+The internal flag is initially false.
+\end{classdesc}
+
+\begin{methoddesc}{isSet}{}
+Return true if and only if the internal flag is true.
+\end{methoddesc}
+
+\begin{methoddesc}{set}{}
+Set the internal flag to true.
+All threads waiting for it to become true are awakened.
+Threads that call \method{wait()} once the flag is true will not block
+at all.
+\end{methoddesc}
+
+\begin{methoddesc}{clear}{}
+Reset the internal flag to false.
+Subsequently, threads calling \method{wait()} will block until
+\method{set()} is called to set the internal flag to true again.
+\end{methoddesc}
+
+\begin{methoddesc}{wait}{\optional{timeout}}
+Block until the internal flag is true.
+If the internal flag is true on entry, return immediately.  Otherwise,
+block until another thread calls \method{set()} to set the flag to
+true, or until the optional timeout occurs.
+
+When the timeout argument is present and not \code{None}, it should be a
+floating point number specifying a timeout for the operation in
+seconds (or fractions thereof).
+\end{methoddesc}
+
+
+\subsection{Thread Objects \label{thread-objects}}
+
+This class represents an activity that is run in a separate thread
+of control.  There are two ways to specify the activity: by
+passing a callable object to the constructor, or by overriding the
+\method{run()} method in a subclass.  No other methods (except for the
+constructor) should be overridden in a subclass.  In other words, 
+\emph{only}  override the \method{__init__()} and \method{run()}
+methods of this class.
+
+Once a thread object is created, its activity must be started by
+calling the thread's \method{start()} method.  This invokes the
+\method{run()} method in a separate thread of control.
+
+Once the thread's activity is started, the thread is considered
+'alive'. It stops being alive when its \method{run()} method terminates
+-- either normally, or by raising an unhandled exception.  The
+\method{isAlive()} method tests whether the thread is alive.
+
+Other threads can call a thread's \method{join()} method.  This blocks
+the calling thread until the thread whose \method{join()} method is
+called is terminated.
+
+A thread has a name.  The name can be passed to the constructor,
+set with the \method{setName()} method, and retrieved with the
+\method{getName()} method.
+
+A thread can be flagged as a ``daemon thread''.  The significance
+of this flag is that the entire Python program exits when only
+daemon threads are left.  The initial value is inherited from the
+creating thread.  The flag can be set with the \method{setDaemon()}
+method and retrieved with the \method{isDaemon()} method.
+
+There is a ``main thread'' object; this corresponds to the
+initial thread of control in the Python program.  It is not a
+daemon thread.
+
+There is the possibility that ``dummy thread objects'' are created.
+These are thread objects corresponding to ``alien threads'', which
+are threads of control started outside the threading module, such as
+directly from C code.  Dummy thread objects have limited
+functionality; they are always considered alive and daemonic, and
+cannot be \method{join()}ed.  They are never deleted, since it is
+impossible to detect the termination of alien threads.
+
+
+\begin{classdesc}{Thread}{group=None, target=None, name=None,
+                          args=(), kwargs=\{\}}
+This constructor should always be called with keyword
+arguments.  Arguments are:
+
+\var{group} should be \code{None}; reserved for future extension when
+a \class{ThreadGroup} class is implemented.
+
+\var{target} is the callable object to be invoked by the
+\method{run()} method.  Defaults to \code{None}, meaning nothing is
+called.
+
+\var{name} is the thread name.  By default, a unique name is
+constructed of the form ``Thread-\var{N}'' where \var{N} is a small
+decimal number.
+
+\var{args} is the argument tuple for the target invocation.  Defaults
+to \code{()}.
+
+\var{kwargs} is a dictionary of keyword arguments for the target
+invocation.  Defaults to \code{\{\}}.
+
+If the subclass overrides the constructor, it must make sure
+to invoke the base class constructor (\code{Thread.__init__()})
+before doing anything else to the thread.
+\end{classdesc}
+
+\begin{methoddesc}{start}{}
+Start the thread's activity.
+
+This must be called at most once per thread object.  It
+arranges for the object's \method{run()} method to be invoked in a
+separate thread of control.
+\end{methoddesc}
+
+\begin{methoddesc}{run}{}
+Method representing the thread's activity.
+
+You may override this method in a subclass.  The standard
+\method{run()} method invokes the callable object passed to the
+object's constructor as the \var{target} argument, if any, with
+sequential and keyword arguments taken from the \var{args} and
+\var{kwargs} arguments, respectively.
+\end{methoddesc}
+
+\begin{methoddesc}{join}{\optional{timeout}}
+Wait until the thread terminates.
+This blocks the calling thread until the thread whose \method{join()}
+method is called terminates -- either normally or through an
+unhandled exception -- or until the optional timeout occurs.
+
+When the \var{timeout} argument is present and not \code{None}, it
+should be a floating point number specifying a timeout for the
+operation in seconds (or fractions thereof). As \method{join()} always 
+returns \code{None}, you must call \method{isAlive()} to decide whether 
+a timeout happened.
+
+When the \var{timeout} argument is not present or \code{None}, the
+operation will block until the thread terminates.
+
+A thread can be \method{join()}ed many times.
+
+A thread cannot join itself because this would cause a
+deadlock.
+
+It is an error to attempt to \method{join()} a thread before it has
+been started.
+\end{methoddesc}
+
+\begin{methoddesc}{getName}{}
+Return the thread's name.
+\end{methoddesc}
+
+\begin{methoddesc}{setName}{name}
+Set the thread's name.
+
+The name is a string used for identification purposes only.
+It has no semantics.  Multiple threads may be given the same
+name.  The initial name is set by the constructor.
+\end{methoddesc}
+
+\begin{methoddesc}{isAlive}{}
+Return whether the thread is alive.
+
+Roughly, a thread is alive from the moment the \method{start()} method
+returns until its \method{run()} method terminates. The module
+function \function{enumerate()} returns a list of all alive threads.
+\end{methoddesc}
+
+\begin{methoddesc}{isDaemon}{}
+Return the thread's daemon flag.
+\end{methoddesc}
+
+\begin{methoddesc}{setDaemon}{daemonic}
+Set the thread's daemon flag to the Boolean value \var{daemonic}.
+This must be called before \method{start()} is called.
+
+The initial value is inherited from the creating thread.
+
+The entire Python program exits when no alive non-daemon threads are
+left.
+\end{methoddesc}
+
+
+\subsection{Timer Objects \label{timer-objects}}
+
+This class represents an action that should be run only after a
+certain amount of time has passed --- a timer.  \class{Timer} is a
+subclass of \class{Thread} and as such also functions as an example of
+creating custom threads.
+
+Timers are started, as with threads, by calling their \method{start()}
+method.  The timer can be stopped (before its action has begun) by
+calling the \method{cancel()} method.  The interval the timer will
+wait before executing its action may not be exactly the same as the
+interval specified by the user.
+
+For example:
+\begin{verbatim}
+def hello():
+    print "hello, world"
+
+t = Timer(30.0, hello)
+t.start() # after 30 seconds, "hello, world" will be printed
+\end{verbatim}
+
+\begin{classdesc}{Timer}{interval, function, args=[], kwargs=\{\}}
+Create a timer that will run \var{function} with arguments \var{args} and 
+keyword arguments \var{kwargs}, after \var{interval} seconds have passed.
+\end{classdesc}
+
+\begin{methoddesc}{cancel}{}
+Stop the timer, and cancel the execution of the timer's action.  This
+will only work if the timer is still in its waiting stage.
+\end{methoddesc}
+
+\subsection{Using locks, conditions, and semaphores in the \keyword{with}
+statement \label{with-locks}}
+
+All of the objects provided by this module that have \method{acquire()} and
+\method{release()} methods can be used as context managers for a \keyword{with}
+statement.  The \method{acquire()} method will be called when the block is
+entered, and \method{release()} will be called when the block is exited.
+
+Currently, \class{Lock}, \class{RLock}, \class{Condition}, \class{Semaphore},
+and \class{BoundedSemaphore} objects may be used as \keyword{with}
+statement context managers.  For example:
+
+\begin{verbatim}
+from __future__ import with_statement
+import threading
+
+some_rlock = threading.RLock()
+
+with some_rlock:
+    print "some_rlock is locked while this executes"
+\end{verbatim}
+