Doc/lib/libthreading.tex

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