1998-08-10 16:42:37 -03:00
|
|
|
\section{\module{threading} ---
|
1999-03-12 15:57:38 -04:00
|
|
|
Higher-level threading interface}
|
1998-07-23 14:59:49 -03:00
|
|
|
|
1999-03-12 15:57:38 -04:00
|
|
|
\declaremodule{standard}{threading}
|
|
|
|
\modulesynopsis{Higher-level threading interface.}
|
1998-07-23 14:59:49 -03:00
|
|
|
|
1998-07-20 10:46:10 -03:00
|
|
|
|
1998-07-27 19:06:12 -03:00
|
|
|
This module constructs higher-level threading interfaces on top of the
|
1999-04-22 18:23:22 -03:00
|
|
|
lower level \refmodule{thread} module.
|
1998-07-20 10:46:10 -03:00
|
|
|
|
1998-07-27 19:06:12 -03:00
|
|
|
This module is safe for use with \samp{from threading import *}. It
|
1998-07-20 10:46:10 -03:00
|
|
|
defines the following functions and objects:
|
|
|
|
|
|
|
|
\begin{funcdesc}{activeCount}{}
|
|
|
|
Return the number of currently active \class{Thread} objects.
|
|
|
|
The returned count is equal to the length of the list returned by
|
|
|
|
\function{enumerate()}.
|
|
|
|
A function that returns the number of currently active threads.
|
|
|
|
\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 currently active \class{Thread} objects.
|
|
|
|
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}{}
|
2002-03-19 10:37:44 -04:00
|
|
|
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.
|
1998-07-20 10:46:10 -03:00
|
|
|
\end{funcdesc}
|
|
|
|
|
|
|
|
\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}
|
|
|
|
|
2001-08-20 15:49:00 -03:00
|
|
|
\begin{funcdesc}{Semaphore}{\optional{value}}
|
1998-07-20 10:46:10 -03:00
|
|
|
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
|
2001-08-20 15:49:00 -03:00
|
|
|
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.
|
1998-07-20 10:46:10 -03:00
|
|
|
\end{funcdesc}
|
|
|
|
|
2001-05-31 17:24:07 -03:00
|
|
|
\begin{classdesc*}{Thread}{}
|
2002-03-19 10:37:44 -04:00
|
|
|
A class that represents a thread of control. This class can be safely
|
|
|
|
subclassed in a limited fashion.
|
2001-05-31 17:24:07 -03:00
|
|
|
\end{classdesc*}
|
1998-07-20 10:46:10 -03:00
|
|
|
|
2001-09-05 10:44:54 -03:00
|
|
|
\begin{classdesc*}{Timer}{}
|
|
|
|
A thread that executes a function after a specified interval has passed.
|
|
|
|
\end{classdesc*}
|
|
|
|
|
1998-07-20 10:46:10 -03:00
|
|
|
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.
|
|
|
|
|
1999-03-12 15:57:38 -04:00
|
|
|
|
|
|
|
\subsection{Lock Objects \label{lock-objects}}
|
1998-07-20 10:46:10 -03:00
|
|
|
|
|
|
|
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
|
1999-04-22 18:23:22 -03:00
|
|
|
directly by the \refmodule{thread} extension module.
|
1998-07-20 10:46:10 -03:00
|
|
|
|
|
|
|
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.
|
|
|
|
|
1999-03-12 15:57:38 -04:00
|
|
|
\begin{methoddesc}{acquire}{\optional{blocking\code{ = 1}}}
|
1998-07-20 10:46:10 -03:00
|
|
|
Acquire a lock, blocking or non-blocking.
|
|
|
|
|
|
|
|
When invoked without arguments, block until the lock is
|
|
|
|
unlocked, then set it to locked, and return. 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.
|
|
|
|
|
|
|
|
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}
|
|
|
|
|
1999-03-12 15:57:38 -04:00
|
|
|
|
|
|
|
\subsection{RLock Objects \label{rlock-objects}}
|
1998-07-20 10:46:10 -03:00
|
|
|
|
|
|
|
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
|
2001-07-06 17:30:11 -03:00
|
|
|
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.
|
1998-07-20 10:46:10 -03:00
|
|
|
|
1999-03-12 15:57:38 -04:00
|
|
|
\begin{methoddesc}{acquire}{\optional{blocking\code{ = 1}}}
|
1998-07-20 10:46:10 -03:00
|
|
|
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}
|
|
|
|
|
1999-03-12 15:57:38 -04:00
|
|
|
|
|
|
|
\subsection{Condition Objects \label{condition-objects}}
|
1998-07-20 10:46:10 -03:00
|
|
|
|
|
|
|
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.
|
|
|
|
|
1999-03-12 15:57:38 -04:00
|
|
|
\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.
|
1998-07-20 10:46:10 -03:00
|
|
|
\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}
|
|
|
|
|
1999-03-12 15:57:38 -04:00
|
|
|
\begin{methoddesc}{wait}{\optional{timeout}}
|
1998-07-20 10:46:10 -03:00
|
|
|
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.
|
|
|
|
|
1999-03-12 15:57:38 -04:00
|
|
|
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).
|
1998-07-20 10:46:10 -03:00
|
|
|
|
1999-03-12 15:57:38 -04:00
|
|
|
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.
|
1998-07-20 10:46:10 -03:00
|
|
|
\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}
|
|
|
|
|
1999-03-12 15:57:38 -04:00
|
|
|
|
|
|
|
\subsection{Semaphore Objects \label{semaphore-objects}}
|
1998-07-20 10:46:10 -03:00
|
|
|
|
|
|
|
This is one of the oldest synchronization primitives in the history of
|
|
|
|
computer science, invented by the early Dutch computer scientist
|
1999-03-12 15:57:38 -04:00
|
|
|
Edsger W. Dijkstra (he used \method{P()} and \method{V()} instead of
|
|
|
|
\method{acquire()} and \method{release()}).
|
1998-07-20 10:46:10 -03:00
|
|
|
|
|
|
|
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()}.
|
|
|
|
|
1999-03-12 15:57:38 -04:00
|
|
|
\begin{classdesc}{Semaphore}{\optional{value}}
|
1998-07-20 10:46:10 -03:00
|
|
|
The optional argument gives the initial value for the internal
|
1999-03-12 15:57:38 -04:00
|
|
|
counter; it defaults to \code{1}.
|
1998-07-20 10:46:10 -03:00
|
|
|
\end{classdesc}
|
|
|
|
|
1999-03-12 15:57:38 -04:00
|
|
|
\begin{methoddesc}{acquire}{\optional{blocking}}
|
1998-07-20 10:46:10 -03:00
|
|
|
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.
|
|
|
|
|
1999-03-12 15:57:38 -04:00
|
|
|
When invoked with \var{blocking} set to true, do the same thing as
|
|
|
|
when called without arguments, and return true.
|
1998-07-20 10:46:10 -03:00
|
|
|
|
1999-03-12 15:57:38 -04:00
|
|
|
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.
|
1998-07-20 10:46:10 -03:00
|
|
|
\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}
|
|
|
|
|
1999-03-12 15:57:38 -04:00
|
|
|
|
2001-08-20 15:49:00 -03:00
|
|
|
\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.
|
|
|
|
|
2002-03-19 10:37:44 -04:00
|
|
|
|
1999-03-12 15:57:38 -04:00
|
|
|
\subsection{Event Objects \label{event-objects}}
|
1998-07-20 10:46:10 -03:00
|
|
|
|
|
|
|
This is one of the simplest mechanisms for communication between
|
2002-03-19 10:37:44 -04:00
|
|
|
threads: one thread signals an event and other threads wait for it.
|
1998-07-20 10:46:10 -03:00
|
|
|
|
|
|
|
An event object manages an internal flag that can be set to true with
|
2002-03-19 10:37:44 -04:00
|
|
|
the \method{set()} method and reset to false with the \method{clear()}
|
|
|
|
method. The \method{wait()} method blocks until the flag is true.
|
1998-07-20 10:46:10 -03:00
|
|
|
|
|
|
|
|
|
|
|
\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.
|
2002-03-19 10:37:44 -04:00
|
|
|
Subsequently, threads calling \method{wait()} will block until
|
|
|
|
\method{set()} is called to set the internal flag to true again.
|
1998-07-20 10:46:10 -03:00
|
|
|
\end{methoddesc}
|
|
|
|
|
1999-03-12 15:57:38 -04:00
|
|
|
\begin{methoddesc}{wait}{\optional{timeout}}
|
1998-07-20 10:46:10 -03:00
|
|
|
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}
|
|
|
|
|
1999-03-12 15:57:38 -04:00
|
|
|
|
|
|
|
\subsection{Thread Objects \label{thread-objects}}
|
1998-07-20 10:46:10 -03:00
|
|
|
|
|
|
|
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,
|
1999-03-12 15:57:38 -04:00
|
|
|
\emph{only} override the \method{__init__()} and \method{run()}
|
|
|
|
methods of this class.
|
1998-07-20 10:46:10 -03:00
|
|
|
|
|
|
|
Once a thread object is created, its activity must be started by
|
1999-03-12 15:57:38 -04:00
|
|
|
calling the thread's \method{start()} method. This invokes the
|
|
|
|
\method{run()} method in a separate thread of control.
|
1998-07-20 10:46:10 -03:00
|
|
|
|
|
|
|
Once the thread's activity is started, the thread is considered
|
|
|
|
'alive' and 'active' (these concepts are almost, but not quite
|
|
|
|
exactly, the same; their definition is intentionally somewhat
|
1999-03-12 15:57:38 -04:00
|
|
|
vague). It stops being alive and active when its \method{run()}
|
|
|
|
method terminates -- either normally, or by raising an unhandled
|
1998-07-20 10:46:10 -03:00
|
|
|
exception. The \method{isAlive()} method tests whether the thread is
|
|
|
|
alive.
|
|
|
|
|
1999-03-12 15:57:38 -04:00
|
|
|
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.
|
1998-07-20 10:46:10 -03:00
|
|
|
|
|
|
|
A thread has a name. The name can be passed to the constructor,
|
1999-03-12 15:57:38 -04:00
|
|
|
set with the \method{setName()} method, and retrieved with the
|
|
|
|
\method{getName()} method.
|
1998-07-20 10:46:10 -03:00
|
|
|
|
|
|
|
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
|
1999-03-12 15:57:38 -04:00
|
|
|
creating thread. The flag can be set with the \method{setDaemon()}
|
2001-05-31 17:24:07 -03:00
|
|
|
method and retrieved with the \method{isDaemon()} method.
|
1998-07-20 10:46:10 -03:00
|
|
|
|
|
|
|
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''. These are threads of control started outside the
|
2001-07-06 17:30:11 -03:00
|
|
|
threading module, such as directly from C code. Dummy thread objects
|
1998-07-20 10:46:10 -03:00
|
|
|
have limited functionality; they are always considered alive,
|
1999-03-12 15:57:38 -04:00
|
|
|
active, and daemonic, and cannot be \method{join()}ed. They are never
|
1998-07-20 10:46:10 -03:00
|
|
|
deleted, since it is impossible to detect the termination of alien
|
|
|
|
threads.
|
|
|
|
|
|
|
|
|
|
|
|
\begin{classdesc}{Thread}{group=None, target=None, name=None,
|
1999-03-12 15:57:38 -04:00
|
|
|
args=(), kwargs=\{\}}
|
1998-07-20 10:46:10 -03:00
|
|
|
This constructor should always be called with keyword
|
|
|
|
arguments. Arguments are:
|
|
|
|
|
2001-05-31 17:24:07 -03:00
|
|
|
\var{group} should be \code{None}; reserved for future extension when
|
|
|
|
a \class{ThreadGroup} class is implemented.
|
1998-07-20 10:46:10 -03:00
|
|
|
|
2001-05-31 17:24:07 -03:00
|
|
|
\var{target} is the callable object to be invoked by the
|
|
|
|
\method{run()} method. Defaults to \code{None}, meaning nothing is
|
|
|
|
called.
|
1998-07-20 10:46:10 -03:00
|
|
|
|
2001-05-31 17:24:07 -03:00
|
|
|
\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.
|
1998-07-20 10:46:10 -03:00
|
|
|
|
2001-05-31 17:24:07 -03:00
|
|
|
\var{args} is the argument tuple for the target invocation. Defaults
|
|
|
|
to \code{()}.
|
1998-07-20 10:46:10 -03:00
|
|
|
|
2001-05-31 17:24:07 -03:00
|
|
|
\var{kwargs} is a dictionary of keyword arguments for the target
|
|
|
|
invocation. Defaults to \code{\{\}}.
|
1998-07-20 10:46:10 -03:00
|
|
|
|
|
|
|
If the subclass overrides the constructor, it must make sure
|
1999-03-12 15:57:38 -04:00
|
|
|
to invoke the base class constructor (\code{Thread.__init__()})
|
1998-07-20 10:46:10 -03:00
|
|
|
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
|
2002-03-19 10:37:44 -04:00
|
|
|
\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.
|
1998-07-20 10:46:10 -03:00
|
|
|
\end{methoddesc}
|
|
|
|
|
1999-03-12 15:57:38 -04:00
|
|
|
\begin{methoddesc}{join}{\optional{timeout}}
|
1998-07-20 10:46:10 -03:00
|
|
|
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.
|
|
|
|
|
2002-03-19 10:37:44 -04:00
|
|
|
When the \var{timeout} argument is present and not \code{None}, it
|
|
|
|
should be a floating point number specifying a timeout for the
|
1998-07-20 10:46:10 -03:00
|
|
|
operation in seconds (or fractions thereof).
|
|
|
|
|
|
|
|
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.
|
|
|
|
\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 active non-daemon
|
|
|
|
threads are left.
|
|
|
|
\end{methoddesc}
|
2001-09-05 10:44:54 -03:00
|
|
|
|
|
|
|
|
|
|
|
\subsection{Timer Objects \label{timer-objects}}
|
|
|
|
|
2002-03-19 10:37:44 -04:00
|
|
|
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.
|
2001-09-05 10:44:54 -03:00
|
|
|
|
2002-03-19 10:37:44 -04:00
|
|
|
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.
|
2001-09-05 10:44:54 -03:00
|
|
|
|
|
|
|
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}{}
|
2002-03-19 10:37:44 -04:00
|
|
|
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.
|
2001-09-05 10:44:54 -03:00
|
|
|
\end{methoddesc}
|