Lib/threading_api.py

   1 """Proposed new higher-level threading interfaces.
   2
   3 This module is safe for use with 'from threading import *'.  It
   4 defines the following objects:
   5
   6 Lock()
   7     A factory function that returns a new primitive lock object.  Once
   8     a thread has acquired it, subsequent attempts to acquire it block,
   9     until it is released; any thread may release it.
  10
  11 RLock()
  12     A factory function that returns a new reentrant lock object.
  13     A reentrant lock must be released by the thread that acquired it.
  14     Once a thread has acquired a reentrant lock, the same thread may
  15     acquire it again without blocking; the thread must release it once
  16     for each time it has acquired it.
  17
  18 Condition()
  19     A factory function that returns a new condition variable object.
  20     A condition variable allows one or more threads to wait until they
  21     are notified by another thread.
  22
  23 Semaphore()
  24     A factory function that returns a new semaphore object.  A
  25     semaphore manages a counter representing the number of release()
  26     calls minus the number of acquire() calls, plus an initial value.
  27     The acquire() method blocks if necessary until it can return
  28     without making the counter negative.
  29
  30 Event()
  31     A factory function that returns a new event object.  An event
  32     manages a flag that can be set to true with the set() method and
  33     reset to false with the clear() method.  The wait() method blocks
  34     until the flag is true.
  35
  36 Thread
  37     A class that represents a thread of control -- subclassable.
  38
  39 currentThread()
  40     A function that returns the Thread object for the caller's thread.
  41
  42 activeCount()
  43     A function that returns the number of currently active threads.
  44
  45 enumerate()
  46     A function that returns a list of all currently active threads.
  47
  48 Detailed interfaces for each of these are documented below in the form
  49 of pseudo class definitions.  Note that the classes marked as ``do not
  50 subclass'' are actually implemented as factory functions; classes are
  51 shown here as a way to structure the documentation only.
  52
  53 The design of this module is loosely based on Java's threading model.
  54 However, where Java makes locks and condition variables basic behavior
  55 of every object, they are separate objects in Python.  Python's Thread
  56 class supports a subset of the behavior of Java's Thread class;
  57 currently, there are no priorities, no thread groups, and threads
  58 cannot be destroyed, stopped, suspended, resumed, or interrupted.  The
  59 static methods of Java's Thread class, when implemented, are mapped to
  60 module-level functions.
  61
  62 All methods described below are executed atomically.
  63
  64 """
  65
  66
  67 class Lock:
  68     """Primitive lock object.
  69
  70     *** DO NOT SUBCLASS THIS CLASS ***
  71
  72     A primitive lock is a synchronization primitive that is not owned
  73     by a particular thread when locked.  In Python, it is currently
  74     the lowest level synchronization primitive available, implemented
  75     directly by the thread extension module.
  76
  77     A primitive lock is in one of two states, ``locked'' or
  78     ``unlocked''.  It is created in the unlocked state.  It has two
  79     basic methods, acquire() and release().  When the state is
  80     unlocked, acquire() changes the state to locked and returns
  81     immediately.  When the state is locked, acquire() blocks until a
  82     call to release() in another thread changes it to unlocked, then
  83     the acquire() call resets it to locked and returns.  The release()
  84     method should only be called in the locked state; it changes the
  85     state to unlocked and returns immediately.  When more than one
  86     thread is blocked in acquire() waiting for the state to turn to
  87     unlocked, only one thread proceeds when a release() call resets
  88     the state to unlocked; which one of the waiting threads proceeds
  89     is not defined, and may vary across implementations.
  90
  91     All methods are executed atomically.
  92
  93     """
  94
  95     def acquire(self, blocking=1):
  96         """Acquire a lock, blocking or non-blocking.
  97
  98         When invoked without arguments, block until the lock is
  99         unlocked, then set it to locked, and return.  There is no
 100         return value in this case.
 101
 102         When invoked with the 'blocking' argument set to true, do the
 103         same thing as when called without arguments, and return true.
 104
 105         When invoked with the 'blocking' argument set to false, do not
 106         block.  If a call without argument would block, return false
 107         immediately; otherwise, do the same thing as when called
 108         without arguments, and return true.
 109
 110         """
 111
 112     def release(self):
 113         """Release a lock.
 114
 115         When the lock is locked, reset it to unlocked, and return.  If
 116         any other threads are blocked waiting for the lock to become
 117         unlocked, allow exactly one of them to proceed.
 118
 119         Do not call this method when the lock is unlocked.
 120
 121         There is no return value.
 122
 123         """
 124
 125
 126 class RLock:
 127     """Reentrant lock object.
 128
 129     *** DO NOT SUBCLASS THIS CLASS ***
 130
 131     A reentrant lock is a synchronization primitive that may be
 132     acquired multiple times by the same thread.  Internally, it uses
 133     the concepts of ``owning thread'' and ``recursion level'' in
 134     addition to the locked/unlocked state used by primitive locks.  In
 135     the locked state, some thread owns the lock; in the unlocked
 136     state, no thread owns it.
 137
 138     To lock the lock, a thread calls its acquire() method; this
 139     returns once the thread owns the lock.  To unlock the lock, a
 140     thread calls its release() method.  acquire()/release() call pairs
 141     may be nested; only the final release() (i.e. the release() of the
 142     outermost pair) resets the lock to unlocked and allows another
 143     thread blocked in acquire() to proceed.
 144
 145     """
 146
 147     def acquire(self, blocking=1):
 148         """Acquire a lock, blocking or non-blocking.
 149
 150         When invoked without arguments: if this thread already owns
 151         the lock, increment the recursion level by one, and return
 152         immediately.  Otherwise, if another thread owns the lock,
 153         block until the lock is unlocked.  Once the lock is unlocked
 154         (not owned by any thread), then grab ownership, set the
 155         recursion level to one, and return.  If more than one thread
 156         is blocked waiting until the lock is unlocked, only one at a
 157         time will be able to grab ownership of the lock.  There is no
 158         return value in this case.
 159
 160         When invoked with the 'blocking' argument set to true, do the
 161         same thing as when called without arguments, and return true.
 162
 163         When invoked with the 'blocking' argument set to false, do not
 164         block.  If a call without argument would block, return false
 165         immediately; otherwise, do the same thing as when called
 166         without arguments, and return true.
 167
 168         """
 169
 170     def release(self):
 171         """Release a lock.
 172
 173         Only call this method when the calling thread owns the lock.
 174         Decrement the recursion level.  If after the decrement it is
 175         zero, reset the lock to unlocked (not owned by any thread),
 176         and if any other threads are blocked waiting for the lock to
 177         become unlocked, allow exactly one of them to proceed.  If
 178         after the decrement the recursion level is still nonzero, the
 179         lock remains locked and owned by the calling thread.
 180
 181         Do not call this method when the lock is unlocked.
 182
 183         There is no return value.
 184
 185         """
 186
 187
 188 class Condition:
 189     """Synchronized condition variable object.
 190
 191     *** DO NOT SUBCLASS THIS CLASS ***
 192
 193     A condition variable is always associated with some kind of lock;
 194     this can be passed in or one will be created by default.  (Passing
 195     one in is useful when several condition variables must share the
 196     same lock.)
 197
 198     A condition variable has acquire() and release() methods that call
 199     the corresponding methods of the associated lock.
 200
 201     It also has a wait() method, and notify() and notifyAll() methods.
 202     These three must only be called when the calling thread has
 203     acquired the lock.
 204
 205     The wait() method releases the lock, and then blocks until it is
 206     awakened by a notifiy() or notifyAll() call for the same condition
 207     variable in another thread.  Once awakened, it re-acquires the
 208     lock and returns.  It is also possible to specify a timeout.
 209
 210     The notify() method wakes up one of the threads waiting for the
 211     condition variable, if any are waiting.  The notifyAll() method
 212     wakes up all threads waiting for the condition variable.
 213
 214     Note: the notify() and notifyAll() methods don't release the
 215     lock; this means that the thread or threads awakened will not
 216     return from their wait() call immediately, but only when the
 217     thread that called notify() or notifyAll() finally relinquishes
 218     ownership of the lock.
 219
 220     Tip: the typical programming style using condition variables uses
 221     the lock to synchronize access to some shared state; threads that
 222     are interested in a particular change of state call wait()
 223     repeatedly until they see the desired state, while threads that
 224     modify the state call notify() or notifyAll() when they change the
 225     state in such a way that it could possibly be a desired state for
 226     one of the waiters.  For example, the following code is a generic
 227     producer-consumer situation with unlimited buffer capacity:
 228
 229         # Consume one item
 230         cv.acquire()
 231         while not an_item_is_available():
 232             cv.wait()
 233         get_an_available_item()
 234         cv.release()
 235
 236         # Produce one item
 237         cv.acquire()
 238         make_an_item_available()
 239         cv.notify()
 240         cv.release()
 241
 242     To choose between notify() and notifyAll(), consider whether one
 243     state change can be interesting for only one or several waiting
 244     threads.  E.g. in a typical producer-consumer situation, adding
 245     one item to the buffer only needs to wake up one consumer thread.
 246
 247     """
 248
 249     def __init__(self, lock=None):
 250         """Constructor.
 251
 252         If the lock argument is given and not None, it must be a Lock
 253         or RLock object, and it is used as the underlying lock.
 254         Otherwise, a new RLock object is created and used as the
 255         underlying lock.
 256
 257         """
 258
 259     def acquire(self, *args):
 260         """Acquire the underlying lock.
 261
 262         This method calls the corresponding method on the underlying
 263         lock; the return value is whatever that method returns.
 264
 265         """
 266
 267     def release(self):
 268         """Release the underlying lock.
 269
 270         This method calls the corresponding method on the underlying
 271         lock; there is no return value.
 272
 273         """
 274
 275     def wait(self, timeout=None):
 276         """Wait until notified or until a timeout occurs.
 277
 278         This must only be called when the calling thread has acquired
 279         the lock.
 280
 281         This method releases the underlying lock, and then blocks
 282         until it is awakened by a notify() or notifyAll() call for the
 283         same condition variable in another thread, or until the
 284         optional timeout occurs.  Once awakened or timed out, it
 285         re-acquires the lock and returns.
 286
 287         When the timeout argument is present and not None, it should
 288         be a floating point number specifying a timeout for the
 289         operation in seconds (or fractions thereof).
 290
 291         When the underlying lock is an RLock, it is not released using
 292         its release() method, since this may not actually unlock the
 293         lock when it was acquired() multiple times recursively.
 294         Instead, an internal interface of the RLock class is used,
 295         which really unlocks it even when it has been recursively
 296         acquired several times.  Another internal interface is then
 297         used to restore the recursion level when the lock is
 298         reacquired.
 299
 300         """
 301
 302     def notify(self):
 303         """Wake up a thread waiting on this condition, if any.
 304
 305         This must only be called when the calling thread has acquired
 306         the lock.
 307
 308         This method wakes up one of the threads waiting for the
 309         condition variable, if any are waiting; it is a no-op if no
 310         threads are waiting.
 311
 312         The current implementation wakes up exactly one thread, if any
 313         are waiting.  However, it's not safe to rely on this behavior.
 314         A future, optimized implementation may occasionally wake up
 315         more than one thread.
 316
 317         Note: the awakened thread does not actually return from its
 318         wait() call until it can reacquire the lock.  Since notify()
 319         does not release the lock, its caller should.
 320
 321         """
 322
 323     def notifyAll(self):
 324         """Wake up all threads waiting on this condition.
 325
 326         This method acts like notify(), but wakes up all waiting
 327         threads instead of one.
 328
 329         """
 330
 331
 332 class Semaphore:
 333     """Semaphore object.
 334
 335     This is one of the oldest synchronization primitives in the
 336     history of computer science, invented by the early Dutch computer
 337     scientist Edsger W. Dijkstra (he used P() and V() instead of
 338     acquire() and release()).
 339
 340     A semaphore manages an internal counter which is decremented by
 341     each acquire() call and incremented by each release() call.  The
 342     counter can never go below zero; when acquire() finds that it is
 343     zero, it blocks, waiting until some other thread calls release().
 344
 345     """
 346
 347     def __init__(self, value=1):
 348         """Constructor.
 349
 350         The optional argument gives the initial value for the internal
 351         counter; it defaults to 1.
 352
 353         """
 354
 355     def acquire(self, blocking=1):
 356         """Acquire a semaphore.
 357
 358         When invoked without arguments: if the internal counter is
 359         larger than zero on entry, decrement it by one and return
 360         immediately.  If it is zero on entry, block, waiting until
 361         some other thread has called release() to make it larger than
 362         zero.  This is done with proper interlocking so that if
 363         multiple acquire() calls are blocked, release() will wake
 364         exactly one of them up.  The implementation may pick one at
 365         random, so the order in which blocked threads are awakened
 366         should not be relied on.  There is no return value in this
 367         case.
 368
 369         When invoked with the 'blocking' argument set to true, do the
 370         same thing as when called without arguments, and return true.
 371
 372         When invoked with the 'blocking' argument set to false, do not
 373         block.  If a call without argument would block, return false
 374         immediately; otherwise, do the same thing as when called
 375         without arguments, and return true.
 376
 377         """
 378
 379     def release(self):
 380         """Release a semaphore.
 381
 382         Increment the internal counter by one.  When it was zero on
 383         entry and another thread is waiting for it to become larger
 384         than zero again, wake up that thread.
 385
 386         """
 387
 388
 389 class Event:
 390     """Event object.
 391
 392     This is one of the simplest mechanisms for communication between
 393     threads: one thread signals an event and another thread, or
 394     threads, wait for it.
 395
 396     An event object manages an internal flag that can be set to true
 397     with the set() method and reset to false with the clear() method.
 398     The wait() method blocks until the flag is true.
 399
 400     """
 401
 402     def __init__(self):
 403         """Constructor.
 404
 405         The internal flag is initially false.
 406
 407         """
 408
 409     def isSet(self):
 410         """Return true iff the internal flag is true."""
 411
 412     def set(self):
 413         """Set the internal flag to true.
 414
 415         All threads waiting for it to become true are awakened.
 416
 417         Threads that call wait() once the flag is true will not block
 418         at all.
 419
 420         """
 421
 422     def clear(self):
 423         """Reset the internal flag to false.
 424
 425         Subsequently, threads calling wait() will block until set() is
 426         called to set the internal flag to true again.
 427
 428         """
 429
 430     def wait(self, timeout=None):
 431         """Block until the internal flag is true.
 432
 433         If the internal flag is true on entry, return immediately.
 434         Otherwise, block until another thread calls set() to set the
 435         flag to true, or until the optional timeout occurs.
 436
 437         When the timeout argument is present and not None, it should
 438         be a floating point number specifying a timeout for the
 439         operation in seconds (or fractions thereof).
 440
 441         """
 442
 443
 444 class Thread:
 445     """Thread class.
 446
 447     *** ONLY OVERRIDE THE __init__() AND run() METHODS OF THIS CLASS ***
 448
 449     This class represents an activity that is run in a separate thread
 450     of control.  There are two ways to specify the activity: by
 451     passing a callable object to the constructor, or by overriding the
 452     run() method in a subclass.  No other methods (except for the
 453     constructor) should be overridden in a subclass.
 454
 455     Once a thread object is created, its activity must be started by
 456     calling the thread's start() method.  This invokes the run()
 457     method in a separate thread of control.
 458
 459     Once the thread's activity is started, the thread is considered
 460     'alive' and 'active' (these concepts are almost, but not quite
 461     exactly, the same; their definition is intentionally somewhat
 462     vague).  It stops being alive and active when its run() method
 463     terminates -- either normally, or by raising an unhandled
 464     exception.  The isAlive() method tests whether the thread is
 465     alive.
 466
 467     Other threads can call a thread's join() method.  This blocks the
 468     calling thread until the thread whose join() method is called
 469     is terminated.
 470
 471     A thread has a name.  The name can be passed to the constructor,
 472     set with the setName() method, and retrieved with the getName()
 473     method.
 474
 475     A thread can be flagged as a ``daemon thread''.  The significance
 476     of this flag is that the entire Python program exits when only
 477     daemon threads are left.  The initial value is inherited from the
 478     creating thread.  The flag can be set with the setDaemon() method
 479     and retrieved with the getDaemon() method.
 480
 481     There is a ``main thread'' object; this corresponds to the
 482     initial thread of control in the Python program.  It is not a
 483     daemon thread.
 484
 485     There is the possibility that ``dummy thread objects'' are
 486     created.  These are thread objects corresponding to ``alien
 487     threads''.  These are threads of control started outside the
 488     threading module, e.g. directly from C code.  Dummy thread objects
 489     have limited functionality; they are always considered alive,
 490     active, and daemonic, and cannot be join()ed.  They are never
 491     deleted, since it is impossible to detect the termination of alien
 492     threads.
 493
 494     """
 495
 496     def __init__(self, group=None, target=None, name=None,
 497                  args=(), kwargs={}):
 498         """Thread constructor.
 499
 500         This constructor should always be called with keyword
 501         arguments.  Arguments are:
 502
 503         group
 504             Should be None; reserved for future extension when a
 505             ThreadGroup class is implemented.
 506
 507         target
 508             Callable object to be invoked by the run() method.
 509             Defaults to None, meaning nothing is called.
 510
 511         name
 512             The thread name.  By default, a unique name is constructed
 513             of the form ``Thread-N'' where N is a small decimal
 514             number.
 515
 516         args
 517             Argument tuple for the target invocation.  Defaults to ().
 518
 519         kwargs
 520             Keyword argument dictionary for the target invocation.
 521             Defaults to {}.
 522
 523         If the subclass overrides the constructor, it must make sure
 524         to invoke the base class constructor (Thread.__init__())
 525         before doing anything else to the thread.
 526
 527         """
 528
 529     def start(self):
 530         """Start the thread's activity.
 531
 532         This must be called at most once per thread object.  It
 533         arranges for the object's run() method to be invoked in a
 534         separate thread of control.
 535
 536         """
 537
 538     def run(self):
 539         """Method representing the thread's activity.
 540
 541         You may override this method in a subclass.  The standard
 542         run() method invokes the callable object passed as the
 543         'target' argument, if any, with sequential and keyword
 544         arguments taken from the 'args' and 'kwargs' arguments,
 545         respectively.
 546
 547         """
 548
 549     def join(self, timeout=None):
 550         """Wait until the thread terminates.
 551
 552         This blocks the calling thread until the thread whose join()
 553         method is called terminates -- either normally or through an
 554         unhandled exception -- or until the optional timeout occurs.
 555
 556         When the timeout argument is present and not None, it should
 557         be a floating point number specifying a timeout for the
 558         operation in seconds (or fractions thereof).
 559
 560         A thread can be join()ed many times.
 561
 562         A thread cannot join itself because this would cause a
 563         deadlock.
 564
 565         It is an error to attempt to join() a thread before it has
 566         been started.
 567
 568         """
 569
 570     def getName(self):
 571         """Return the thread's name."""
 572
 573     def setName(self, name):
 574         """Set the thread's name.
 575
 576         The name is a string used for identification purposes only.
 577         It has no semantics.  Multiple threads may be given the same
 578         name.  The initial name is set by the constructor.
 579
 580         """
 581
 582     def isAlive(self):
 583         """Return whether the thread is alive.
 584
 585         Roughly, a thread is alive from the moment the start() method
 586         returns until its run() method terminates.
 587
 588         """
 589
 590     def isDaemon(self):
 591         """Return the thread's daemon flag."""
 592
 593     def setDaemon(self, daemonic):
 594         """Set the thread's daemon flag (a Boolean).
 595
 596         This must be called before start() is called.
 597
 598         The initial value is inherited from the creating thread.
 599
 600         The entire Python program exits when no active non-daemon
 601         threads are left.
 602
 603         """
 604
 605
 606 # Module-level functions:
 607
 608
 609 def currentThread():
 610     """Return the current Thread object.
 611
 612     This function returns the Thread object corresponding to the
 613     caller's thread of control.
 614
 615     If the caller's thread of control was not created through the
 616     threading module, a dummy thread object with limited functionality
 617     is returned.
 618
 619     """
 620
 621
 622 def activeCount():
 623     """Return the number of currently active Thread objects.
 624
 625     The returned count is equal to the length of the list returned by
 626     enumerate().
 627
 628     """
 629
 630
 631 def enumerate():
 632     """Return a list of all currently active Thread objects.
 633
 634     The list includes daemonic threads, dummy thread objects created
 635     by currentThread(), and the main thread.  It excludes terminated
 636     threads and threads that have not yet been started.
 637
 638     """