diff options
| -rw-r--r-- | Lib/threading.py | 638 | ||||
| -rw-r--r-- | Lib/threading_api.py | 638 |
2 files changed, 1276 insertions, 0 deletions
diff --git a/Lib/threading.py b/Lib/threading.py new file mode 100644 index 0000000..79319c1 --- /dev/null +++ b/Lib/threading.py @@ -0,0 +1,638 @@ +# threading.py: +# Proposed new threading module, emulating a subset of Java's threading model + +import sys +import time +import thread +import traceback +import StringIO + +# Rename some stuff so "from threading import *" is safe + +_sys = sys +del sys + +_time = time.time +_sleep = time.sleep +del time + +_start_new_thread = thread.start_new_thread +_allocate_lock = thread.allocate_lock +_get_ident = thread.get_ident +del thread + +_print_exc = traceback.print_exc +del traceback + +_StringIO = StringIO.StringIO +del StringIO + + +# Debug support (adapted from ihooks.py) + +_VERBOSE = 0 + +if __debug__: + + class _Verbose: + + def __init__(self, verbose=None): + if verbose is None: + verbose = _VERBOSE + self.__verbose = verbose + + def _note(self, format, *args): + if self.__verbose: + format = format % args + format = "%s: %s\n" % ( + currentThread().getName(), format) + _sys.stderr.write(format) + +else: + # Disable this when using "python -O" + class _Verbose: + def __init__(self, verbose=None): + pass + def _note(self, *args): + pass + + +# Synchronization classes + +Lock = _allocate_lock + +def RLock(*args, **kwargs): + return apply(_RLock, args, kwargs) + +class _RLock(_Verbose): + + def __init__(self, verbose=None): + _Verbose.__init__(self, verbose) + self.__block = _allocate_lock() + self.__owner = None + self.__count = 0 + + def __repr__(self): + return "<%s(%s, %d)>" % ( + self.__class__.__name__, + self.__owner and self.__owner.getName(), + self.__count) + + def acquire(self, blocking=1): + me = currentThread() + if self.__owner is me: + self.__count = self.__count + 1 + if __debug__: + self._note("%s.acquire(%s): recursive success", self, blocking) + return 1 + rc = self.__block.acquire(blocking) + if rc: + self.__owner = me + self.__count = 1 + if __debug__: + self._note("%s.acquire(%s): initial succes", self, blocking) + else: + if __debug__: + self._note("%s.acquire(%s): failure", self, blocking) + return rc + + def release(self): + me = currentThread() + assert self.__owner is me, "release() of un-acquire()d lock" + self.__count = count = self.__count - 1 + if not count: + self.__owner = None + self.__block.release() + if __debug__: + self._note("%s.release(): final release", self) + else: + if __debug__: + self._note("%s.release(): non-final release", self) + + # Internal methods used by condition variables + + def _acquire_restore(self, (count, owner)): + self.__block.acquire() + self.__count = count + self.__owner = owner + if __debug__: + self._note("%s._acquire_restore()", self) + + def _release_save(self): + if __debug__: + self._note("%s._release_save()", self) + count = self.__count + self.__count = 0 + owner = self.__owner + self.__owner = None + self.__block.release() + return (count, owner) + + def _is_owned(self): + return self.__owner is currentThread() + + +def Condition(*args, **kwargs): + return apply(_Condition, args, kwargs) + +class _Condition(_Verbose): + + def __init__(self, lock=None, verbose=None): + _Verbose.__init__(self, verbose) + if lock is None: + lock = RLock() + self.__lock = lock + # Export the lock's acquire() and release() methods + self.acquire = lock.acquire + self.release = lock.release + # If the lock defines _release_save() and/or _acquire_restore(), + # these override the default implementations (which just call + # release() and acquire() on the lock). Ditto for _is_owned(). + try: + self._release_save = lock._release_save + except AttributeError: + pass + try: + self._acquire_restore = lock._acquire_restore + except AttributeError: + pass + try: + self._is_owned = lock._is_owned + except AttributeError: + pass + self.__waiters = [] + + def __repr__(self): + return "<Condition(%s, %d)>" % (self.__lock, len(self.__waiters)) + + def _release_save(self): + self.__lock.release() # No state to save + + def _acquire_restore(self, x): + self.__lock.acquire() # Ignore saved state + + def _is_owned(self): + if self.__lock.acquire(0): + self.__lock.release() + return 0 + else: + return 1 + + def wait(self, timeout=None): + me = currentThread() + assert self._is_owned(), "wait() of un-acquire()d lock" + waiter = _allocate_lock() + waiter.acquire() + self.__waiters.append(waiter) + saved_state = self._release_save() + if timeout is None: + waiter.acquire() + if __debug__: + self._note("%s.wait(): got it", self) + else: + endtime = _time() + timeout + delay = 0.000001 # 1 usec + while 1: + gotit = waiter.acquire(0) + if gotit or _time() >= endtime: + break + _sleep(delay) + if delay < 1.0: + delay = delay * 2.0 + if not gotit: + if __debug__: + self._note("%s.wait(%s): timed out", self, timeout) + try: + self.__waiters.remove(waiter) + except ValueError: + pass + else: + if __debug__: + self._note("%s.wait(%s): got it", self, timeout) + self._acquire_restore(saved_state) + + def notify(self, n=1): + me = currentThread() + assert self._is_owned(), "notify() of un-acquire()d lock" + __waiters = self.__waiters + waiters = __waiters[:n] + if not waiters: + if __debug__: + self._note("%s.notify(): no waiters", self) + return + self._note("%s.notify(): notifying %d waiter%s", self, n, + n!=1 and "s" or "") + for waiter in waiters: + waiter.release() + try: + __waiters.remove(waiter) + except ValueError: + pass + + def notifyAll(self): + self.notify(len(self.__waiters)) + + +def Semaphore(*args, **kwargs): + return apply(_Semaphore, args, kwargs) + +class _Semaphore(_Verbose): + + # After Tim Peters' semaphore class, but bnot quite the same (no maximum) + + def __init__(self, value=1, verbose=None): + assert value >= 0, "Semaphore initial value must be >= 0" + _Verbose.__init__(self, verbose) + self.__cond = Condition(Lock()) + self.__value = value + + def acquire(self, blocking=1): + rc = 0 + self.__cond.acquire() + while self.__value == 0: + if not blocking: + break + self.__cond.wait() + else: + self.__value = self.__value - 1 + rc = 1 + self.__cond.release() + return rc + + def release(self): + self.__cond.acquire() + self.__value = self.__value + 1 + self.__cond.notify() + self.__cond.release() + + +def Event(*args, **kwargs): + return apply(_Event, args, kwargs) + +class _Event(_Verbose): + + # After Tim Peters' event class (without is_posted()) + + def __init__(self, verbose=None): + _Verbose.__init__(self, verbose) + self.__cond = Condition(Lock()) + self.__flag = 0 + + def isSet(self): + return self.__flag + + def set(self): + self.__cond.acquire() + self.__flag = 1 + self.__cond.notifyAll() + self.__cond.release() + + def clear(self): + self.__cond.acquire() + self.__flag = 0 + self.__cond.release() + + def wait(self, timeout=None): + self.__cond.acquire() + if not self.__flag: + self.__cond.wait(timeout) + self.__cond.release() + + +# Helper to generate new thread names +_counter = 0 +def _newname(template="Thread-%d"): + global _counter + _counter = _counter + 1 + return template % _counter + +# Active thread administration +_active_limbo_lock = _allocate_lock() +_active = {} +_limbo = {} + + +# Main class for threads + +class Thread(_Verbose): + + __initialized = 0 + + def __init__(self, group=None, target=None, name=None, + args=(), kwargs={}, verbose=None): + assert group is None, "group argument must be None for now" + _Verbose.__init__(self, verbose) + self.__target = target + self.__name = str(name or _newname()) + self.__args = args + self.__kwargs = kwargs + self.__daemonic = self._set_daemon() + self.__started = 0 + self.__stopped = 0 + self.__block = Condition(Lock()) + self.__initialized = 1 + + def _set_daemon(self): + # Overridden in _MainThread and _DummyThread + return currentThread().isDaemon() + + def __repr__(self): + assert self.__initialized, "Thread.__init__() was not called" + status = "initial" + if self.__started: + status = "started" + if self.__stopped: + status = "stopped" + if self.__daemonic: + status = status + " daemon" + return "<%s(%s, %s)>" % (self.__class__.__name__, self.__name, status) + + def start(self): + assert self.__initialized, "Thread.__init__() not called" + assert not self.__started, "thread already started" + if __debug__: + self._note("%s.start(): starting thread", self) + _active_limbo_lock.acquire() + _limbo[self] = self + _active_limbo_lock.release() + _start_new_thread(self.__bootstrap, ()) + self.__started = 1 + _sleep(0.000001) # 1 usec, to let the thread run (Solaris hack) + + def run(self): + if self.__target: + apply(self.__target, self.__args, self.__kwargs) + + def __bootstrap(self): + try: + self.__started = 1 + _active_limbo_lock.acquire() + _active[_get_ident()] = self + del _limbo[self] + _active_limbo_lock.release() + if __debug__: + self._note("%s.__bootstrap(): thread started", self) + try: + self.run() + except SystemExit: + if __debug__: + self._note("%s.__bootstrap(): raised SystemExit", self) + except: + if __debug__: + self._note("%s.__bootstrap(): unhandled exception", self) + s = _StringIO() + _print_exc(file=s) + _sys.stderr.write("Exception in thread %s:\n%s\n" % + (self.getName(), s.getvalue())) + else: + if __debug__: + self._note("%s.__bootstrap(): normal return", self) + finally: + self.__stop() + self.__delete() + + def __stop(self): + self.__block.acquire() + self.__stopped = 1 + self.__block.notifyAll() + self.__block.release() + + def __delete(self): + _active_limbo_lock.acquire() + del _active[_get_ident()] + _active_limbo_lock.release() + + def join(self, timeout=None): + assert self.__initialized, "Thread.__init__() not called" + assert self.__started, "cannot join thread before it is started" + assert self is not currentThread(), "cannot join current thread" + if __debug__: + if not self.__stopped: + self._note("%s.join(): waiting until thread stops", self) + self.__block.acquire() + if timeout is None: + while not self.__stopped: + self.__block.wait() + if __debug__: + self._note("%s.join(): thread stopped", self) + else: + deadline = time.time() + timeout + while not self.__stopped: + delay = deadline - time.time() + if delay <= 0: + if __debug__: + self._note("%s.join(): timed out", self) + break + self.__block.wait(delay) + else: + if __debug__: + self._note("%s.join(): thread stopped", self) + self.__block.release() + + def getName(self): + assert self.__initialized, "Thread.__init__() not called" + return self.__name + + def setName(self, name): + assert self.__initialized, "Thread.__init__() not called" + self.__name = str(name) + + def isAlive(self): + assert self.__initialized, "Thread.__init__() not called" + return self.__started and not self.__stopped + + def isDaemon(self): + assert self.__initialized, "Thread.__init__() not called" + return self.__daemonic + + def setDaemon(self, daemonic): + assert self.__initialized, "Thread.__init__() not called" + assert not self.__started, "cannot set daemon status of active thread" + self.__daemonic = daemonic + + +# Special thread class to represent the main thread +# This is garbage collected through an exit handler + +class _MainThread(Thread): + + def __init__(self): + Thread.__init__(self, name="MainThread") + self._Thread__started = 1 + _active_limbo_lock.acquire() + _active[_get_ident()] = self + _active_limbo_lock.release() + try: + self.__oldexitfunc = _sys.exitfunc + except AttributeError: + self.__oldexitfunc = None + _sys.exitfunc = self.__exitfunc + + def _set_daemon(self): + return 0 + + def __exitfunc(self): + self._Thread__stop() + t = _pickSomeNonDaemonThread() + if t: + if __debug__: + self._note("%s: waiting for other threads", self) + while t: + t.join() + t = _pickSomeNonDaemonThread() + if self.__oldexitfunc: + if __debug__: + self._note("%s: calling exit handler", self) + self.__oldexitfunc() + if __debug__: + self._note("%s: exiting", self) + self._Thread__delete() + +def _pickSomeNonDaemonThread(): + for t in enumerate(): + if not t.isDaemon() and t.isAlive(): + return t + return None + + +# Dummy thread class to represent threads not started here. +# These aren't garbage collected when they die, +# nor can they be waited for. +# Their purpose is to return *something* from currentThread(). +# They are marked as daemon threads so we won't wait for them +# when we exit (conform previous semantics). + +class _DummyThread(Thread): + + def __init__(self): + Thread.__init__(self, name=_newname("Dummy-%d")) + self.__Thread_started = 1 + _active_limbo_lock.acquire() + _active[_get_ident()] = self + _active_limbo_lock.release() + + def _set_daemon(self): + return 1 + + def join(self): + assert 0, "cannot join a dummy thread" + + +# Global API functions + +def currentThread(): + try: + return _active[_get_ident()] + except KeyError: + print "currentThread(): no current thread for", _get_ident() + return _DummyThread() + +def activeCount(): + _active_limbo_lock.acquire() + count = len(_active) + len(_limbo) + _active_limbo_lock.release() + return count + +def enumerate(): + _active_limbo_lock.acquire() + active = _active.values() + _limbo.values() + _active_limbo_lock.release() + return active + + +# Create the main thread object + +_MainThread() + + +# Self-test code + +def _test(): + + import whrandom + + class BoundedQueue(_Verbose): + + def __init__(self, limit): + _Verbose.__init__(self) + self.mon = RLock() + self.rc = Condition(self.mon) + self.wc = Condition(self.mon) + self.limit = limit + self.queue = [] + + def put(self, item): + self.mon.acquire() + while len(self.queue) >= self.limit: + self._note("put(%s): queue full", item) + self.wc.wait() + self.queue.append(item) + self._note("put(%s): appended, length now %d", + item, len(self.queue)) + self.rc.notify() + self.mon.release() + + def get(self): + self.mon.acquire() + while not self.queue: + self._note("get(): queue empty") + self.rc.wait() + item = self.queue[0] + del self.queue[0] + self._note("get(): got %s, %d left", item, len(self.queue)) + self.wc.notify() + self.mon.release() + return item + + class ProducerThread(Thread): + + def __init__(self, queue, quota): + Thread.__init__(self, name="Producer") + self.queue = queue + self.quota = quota + + def run(self): + from whrandom import random + counter = 0 + while counter < self.quota: + counter = counter + 1 + self.queue.put("%s.%d" % (self.getName(), counter)) + _sleep(random() * 0.00001) + + + class ConsumerThread(Thread): + + def __init__(self, queue, count): + Thread.__init__(self, name="Consumer") + self.queue = queue + self.count = count + + def run(self): + while self.count > 0: + item = self.queue.get() + print item + self.count = self.count - 1 + + import time + + NP = 3 + QL = 4 + NI = 5 + + Q = BoundedQueue(QL) + P = [] + for i in range(NP): + t = ProducerThread(Q, NI) + t.setName("Producer-%d" % (i+1)) + P.append(t) + C = ConsumerThread(Q, NI*NP) + for t in P: + t.start() + _sleep(0.000001) + C.start() + for t in P: + t.join() + C.join() + +if __name__ == '__main__': + _test() diff --git a/Lib/threading_api.py b/Lib/threading_api.py new file mode 100644 index 0000000..285cee1 --- /dev/null +++ b/Lib/threading_api.py @@ -0,0 +1,638 @@ +"""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): + """Set the thread's daemon flag. + + 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. + + """ |