Removed; since long subsumed in Doc/lib/libthreading.tex
This commit is contained in:
Guido van Rossum
parent
7a1229991d
commit
ba3ed56a22
|
|
@ -1,638 +0,0 @@
|
|||
"""Proposed new higher-level threading interfaces.
|
||||
|
||||
This module is safe for use with 'from threading import *'. It
|
||||
defines the following objects:
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
Semaphore()
|
||||
A factory function that returns a new semaphore object. A
|
||||
semaphore manages a counter representing the number of release()
|
||||
calls minus the number of acquire() calls, plus an initial value.
|
||||
The acquire() method blocks if necessary until it can return
|
||||
without making the counter negative.
|
||||
|
||||
Event()
|
||||
A factory function that returns a new event object. An event
|
||||
manages a flag that can be set to true with the set() method and
|
||||
reset to false with the clear() method. The wait() method blocks
|
||||
until the flag is true.
|
||||
|
||||
Thread
|
||||
A class that represents a thread of control -- subclassable.
|
||||
|
||||
currentThread()
|
||||
A function that returns the Thread object for the caller's thread.
|
||||
|
||||
activeCount()
|
||||
A function that returns the number of currently active threads.
|
||||
|
||||
enumerate()
|
||||
A function that returns a list of all currently active threads.
|
||||
|
||||
Detailed interfaces for each of these are documented below in the form
|
||||
of pseudo class definitions. Note that the classes marked as ``do not
|
||||
subclass'' are actually implemented as factory functions; classes are
|
||||
shown here as a way to structure the documentation only.
|
||||
|
||||
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 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 methods described below are executed atomically.
|
||||
|
||||
"""
|
||||
|
||||
|
||||
class Lock:
|
||||
"""Primitive lock object.
|
||||
|
||||
*** DO NOT SUBCLASS THIS CLASS ***
|
||||
|
||||
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 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, acquire() and release(). When the state is
|
||||
unlocked, acquire() changes the state to locked and returns
|
||||
immediately. When the state is locked, acquire() blocks until a
|
||||
call to release() in another thread changes it to unlocked, then
|
||||
the acquire() call resets it to locked and returns. The 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 acquire() waiting for the state to turn to
|
||||
unlocked, only one thread proceeds when a 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.
|
||||
|
||||
"""
|
||||
|
||||
def acquire(self, blocking=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. There is no
|
||||
return value in this case.
|
||||
|
||||
When invoked with the 'blocking' argument set to true, do the
|
||||
same thing as when called without arguments, and return true.
|
||||
|
||||
When invoked with the 'blocking' argument set to false, do not
|
||||
block. If a call without argument would block, return false
|
||||
immediately; otherwise, do the same thing as when called
|
||||
without arguments, and return true.
|
||||
|
||||
"""
|
||||
|
||||
def release(self):
|
||||
"""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.
|
||||
|
||||
"""
|
||||
|
||||
|
||||
class RLock:
|
||||
"""Reentrant lock object.
|
||||
|
||||
*** DO NOT SUBCLASS THIS CLASS ***
|
||||
|
||||
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 acquire() method; this
|
||||
returns once the thread owns the lock. To unlock the lock, a
|
||||
thread calls its release() method. acquire()/release() call pairs
|
||||
may be nested; only the final release() (i.e. the release() of the
|
||||
outermost pair) resets the lock to unlocked and allows another
|
||||
thread blocked in acquire() to proceed.
|
||||
|
||||
"""
|
||||
|
||||
def acquire(self, blocking=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 'blocking' argument set to true, do the
|
||||
same thing as when called without arguments, and return true.
|
||||
|
||||
When invoked with the 'blocking' argument set to false, do not
|
||||
block. If a call without argument would block, return false
|
||||
immediately; otherwise, do the same thing as when called
|
||||
without arguments, and return true.
|
||||
|
||||
"""
|
||||
|
||||
def release(self):
|
||||
"""Release a lock.
|
||||
|
||||
Only call this method when the calling thread owns the lock.
|
||||
Decrement 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.
|
||||
|
||||
Do not call this method when the lock is unlocked.
|
||||
|
||||
There is no return value.
|
||||
|
||||
"""
|
||||
|
||||
|
||||
class Condition:
|
||||
"""Synchronized condition variable object.
|
||||
|
||||
*** DO NOT SUBCLASS THIS CLASS ***
|
||||
|
||||
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 acquire() and release() methods that call
|
||||
the corresponding methods of the associated lock.
|
||||
|
||||
It also has a wait() method, and notify() and notifyAll() methods.
|
||||
These three must only be called when the calling thread has
|
||||
acquired the lock.
|
||||
|
||||
The wait() method releases the lock, and then blocks until it is
|
||||
awakened by a notifiy() or 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 notify() method wakes up one of the threads waiting for the
|
||||
condition variable, if any are waiting. The notifyAll() method
|
||||
wakes up all threads waiting for the condition variable.
|
||||
|
||||
Note: the notify() and notifyAll() methods don't release the
|
||||
lock; this means that the thread or threads awakened will not
|
||||
return from their wait() call immediately, but only when the
|
||||
thread that called notify() or 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 wait()
|
||||
repeatedly until they see the desired state, while threads that
|
||||
modify the state call notify() or 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:
|
||||
|
||||
# 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()
|
||||
|
||||
To choose between notify() and 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.
|
||||
|
||||
"""
|
||||
|
||||
def __init__(self, lock=None):
|
||||
"""Constructor.
|
||||
|
||||
If the lock argument is given and not None, it must be a Lock
|
||||
or RLock object, and it is used as the underlying lock.
|
||||
Otherwise, a new RLock object is created and used as the
|
||||
underlying lock.
|
||||
|
||||
"""
|
||||
|
||||
def acquire(self, *args):
|
||||
"""Acquire the underlying lock.
|
||||
|
||||
This method calls the corresponding method on the underlying
|
||||
lock; the return value is whatever that method returns.
|
||||
|
||||
"""
|
||||
|
||||
def release(self):
|
||||
"""Release the underlying lock.
|
||||
|
||||
This method calls the corresponding method on the underlying
|
||||
lock; there is no return value.
|
||||
|
||||
"""
|
||||
|
||||
def wait(self, timeout=None):
|
||||
"""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 notify() or 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 timeout argument is present and not 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 RLock, it is not released using
|
||||
its release() method, since this may not actually unlock the
|
||||
lock when it was acquired() multiple times recursively.
|
||||
Instead, an internal interface of the 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.
|
||||
|
||||
"""
|
||||
|
||||
def notify(self):
|
||||
"""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
|
||||
wait() call until it can reacquire the lock. Since notify()
|
||||
does not release the lock, its caller should.
|
||||
|
||||
"""
|
||||
|
||||
def notifyAll(self):
|
||||
"""Wake up all threads waiting on this condition.
|
||||
|
||||
This method acts like notify(), but wakes up all waiting
|
||||
threads instead of one.
|
||||
|
||||
"""
|
||||
|
||||
|
||||
class Semaphore:
|
||||
"""Semaphore object.
|
||||
|
||||
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 P() and V() instead of
|
||||
acquire() and release()).
|
||||
|
||||
A semaphore manages an internal counter which is decremented by
|
||||
each acquire() call and incremented by each release() call. The
|
||||
counter can never go below zero; when acquire() finds that it is
|
||||
zero, it blocks, waiting until some other thread calls release().
|
||||
|
||||
"""
|
||||
|
||||
def __init__(self, value=1):
|
||||
"""Constructor.
|
||||
|
||||
The optional argument gives the initial value for the internal
|
||||
counter; it defaults to 1.
|
||||
|
||||
"""
|
||||
|
||||
def acquire(self, blocking=1):
|
||||
"""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 release() to make it larger than
|
||||
zero. This is done with proper interlocking so that if
|
||||
multiple acquire() calls are blocked, 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 the 'blocking' argument set to true, do the
|
||||
same thing as when called without arguments, and return true.
|
||||
|
||||
When invoked with the 'blocking' argument set to false, do not
|
||||
block. If a call without argument would block, return false
|
||||
immediately; otherwise, do the same thing as when called
|
||||
without arguments, and return true.
|
||||
|
||||
"""
|
||||
|
||||
def release(self):
|
||||
"""Release a semaphore.
|
||||
|
||||
Increment 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.
|
||||
|
||||
"""
|
||||
|
||||
|
||||
class Event:
|
||||
"""Event object.
|
||||
|
||||
This is one of the simplest mechanisms for communication between
|
||||
threads: one thread signals an event and another thread, or
|
||||
threads, wait for it.
|
||||
|
||||
An event object manages an internal flag that can be set to true
|
||||
with the set() method and reset to false with the clear() method.
|
||||
The wait() method blocks until the flag is true.
|
||||
|
||||
"""
|
||||
|
||||
def __init__(self):
|
||||
"""Constructor.
|
||||
|
||||
The internal flag is initially false.
|
||||
|
||||
"""
|
||||
|
||||
def isSet(self):
|
||||
"""Return true iff the internal flag is true."""
|
||||
|
||||
def set(self):
|
||||
"""Set the internal flag to true.
|
||||
|
||||
All threads waiting for it to become true are awakened.
|
||||
|
||||
Threads that call wait() once the flag is true will not block
|
||||
at all.
|
||||
|
||||
"""
|
||||
|
||||
def clear(self):
|
||||
"""Reset the internal flag to false.
|
||||
|
||||
Subsequently, threads calling wait() will block until set() is
|
||||
called to set the internal flag to true again.
|
||||
|
||||
"""
|
||||
|
||||
def wait(self, timeout=None):
|
||||
"""Block until the internal flag is true.
|
||||
|
||||
If the internal flag is true on entry, return immediately.
|
||||
Otherwise, block until another thread calls set() to set the
|
||||
flag to true, or until the optional timeout occurs.
|
||||
|
||||
When the timeout argument is present and not None, it should
|
||||
be a floating point number specifying a timeout for the
|
||||
operation in seconds (or fractions thereof).
|
||||
|
||||
"""
|
||||
|
||||
|
||||
class Thread:
|
||||
"""Thread class.
|
||||
|
||||
*** ONLY OVERRIDE THE __init__() AND run() METHODS OF THIS CLASS ***
|
||||
|
||||
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
|
||||
run() method in a subclass. No other methods (except for the
|
||||
constructor) should be overridden in a subclass.
|
||||
|
||||
Once a thread object is created, its activity must be started by
|
||||
calling the thread's start() method. This invokes the run()
|
||||
method in a separate thread of control.
|
||||
|
||||
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
|
||||
vague). It stops being alive and active when its run() method
|
||||
terminates -- either normally, or by raising an unhandled
|
||||
exception. The isAlive() method tests whether the thread is
|
||||
alive.
|
||||
|
||||
Other threads can call a thread's join() method. This blocks the
|
||||
calling thread until the thread whose join() method is called
|
||||
is terminated.
|
||||
|
||||
A thread has a name. The name can be passed to the constructor,
|
||||
set with the setName() method, and retrieved with the 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 setDaemon() method
|
||||
and retrieved with the getDaemon() 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''. These are threads of control started outside the
|
||||
threading module, e.g. directly from C code. Dummy thread objects
|
||||
have limited functionality; they are always considered alive,
|
||||
active, and daemonic, and cannot be join()ed. They are never
|
||||
deleted, since it is impossible to detect the termination of alien
|
||||
threads.
|
||||
|
||||
"""
|
||||
|
||||
def __init__(self, group=None, target=None, name=None,
|
||||
args=(), kwargs={}):
|
||||
"""Thread constructor.
|
||||
|
||||
This constructor should always be called with keyword
|
||||
arguments. Arguments are:
|
||||
|
||||
group
|
||||
Should be None; reserved for future extension when a
|
||||
ThreadGroup class is implemented.
|
||||
|
||||
target
|
||||
Callable object to be invoked by the run() method.
|
||||
Defaults to None, meaning nothing is called.
|
||||
|
||||
name
|
||||
The thread name. By default, a unique name is constructed
|
||||
of the form ``Thread-N'' where N is a small decimal
|
||||
number.
|
||||
|
||||
args
|
||||
Argument tuple for the target invocation. Defaults to ().
|
||||
|
||||
kwargs
|
||||
Keyword argument dictionary for the target invocation.
|
||||
Defaults to {}.
|
||||
|
||||
If the subclass overrides the constructor, it must make sure
|
||||
to invoke the base class constructor (Thread.__init__())
|
||||
before doing anything else to the thread.
|
||||
|
||||
"""
|
||||
|
||||
def start(self):
|
||||
"""Start the thread's activity.
|
||||
|
||||
This must be called at most once per thread object. It
|
||||
arranges for the object's run() method to be invoked in a
|
||||
separate thread of control.
|
||||
|
||||
"""
|
||||
|
||||
def run(self):
|
||||
"""Method representing the thread's activity.
|
||||
|
||||
You may override this method in a subclass. The standard
|
||||
run() method invokes the callable object passed as the
|
||||
'target' argument, if any, with sequential and keyword
|
||||
arguments taken from the 'args' and 'kwargs' arguments,
|
||||
respectively.
|
||||
|
||||
"""
|
||||
|
||||
def join(self, timeout=None):
|
||||
"""Wait until the thread terminates.
|
||||
|
||||
This blocks the calling thread until the thread whose join()
|
||||
method is called terminates -- either normally or through an
|
||||
unhandled exception -- or until the optional timeout occurs.
|
||||
|
||||
When the timeout argument is present and not None, it should
|
||||
be a floating point number specifying a timeout for the
|
||||
operation in seconds (or fractions thereof).
|
||||
|
||||
A thread can be join()ed many times.
|
||||
|
||||
A thread cannot join itself because this would cause a
|
||||
deadlock.
|
||||
|
||||
It is an error to attempt to join() a thread before it has
|
||||
been started.
|
||||
|
||||
"""
|
||||
|
||||
def getName(self):
|
||||
"""Return the thread's name."""
|
||||
|
||||
def setName(self, 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.
|
||||
|
||||
"""
|
||||
|
||||
def isAlive(self):
|
||||
"""Return whether the thread is alive.
|
||||
|
||||
Roughly, a thread is alive from the moment the start() method
|
||||
returns until its run() method terminates.
|
||||
|
||||
"""
|
||||
|
||||
def isDaemon(self):
|
||||
"""Return the thread's daemon flag."""
|
||||
|
||||
def setDaemon(self, daemonic):
|
||||
"""Set the thread's daemon flag (a Boolean).
|
||||
|
||||
This must be called before 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.
|
||||
|
||||
"""
|
||||
|
||||
|
||||
# Module-level functions:
|
||||
|
||||
|
||||
def currentThread():
|
||||
"""Return the current Thread object.
|
||||
|
||||
This function returns the Thread object corresponding to the
|
||||
caller's thread of control.
|
||||
|
||||
If the caller's thread of control was not created through the
|
||||
threading module, a dummy thread object with limited functionality
|
||||
is returned.
|
||||
|
||||
"""
|
||||
|
||||
|
||||
def activeCount():
|
||||
"""Return the number of currently active Thread objects.
|
||||
|
||||
The returned count is equal to the length of the list returned by
|
||||
enumerate().
|
||||
|
||||
"""
|
||||
|
||||
|
||||
def enumerate():
|
||||
"""Return a list of all currently active Thread objects.
|
||||
|
||||
The list includes daemonic threads, dummy thread objects created
|
||||
by currentThread(), and the main thread. It excludes terminated
|
||||
threads and threads that have not yet been started.
|
||||
|
||||
"""
|
||||
Loading…
Reference in New Issue