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.
 154 \method{acquire()}/\method{release()} call pairs may be nested; only
 155 the final \method{release()} (the \method{release()} of the outermost
 156 pair) resets the lock to unlocked and allows another thread blocked in
 157 \method{acquire()} to proceed.
 158
 159 \begin{methoddesc}{acquire}{\optional{blocking\code{ = 1}}}
 160 Acquire a lock, blocking or non-blocking.
 161
 162 When invoked without arguments: if this thread already owns
 163 the lock, increment the recursion level by one, and return
 164 immediately.  Otherwise, if another thread owns the lock,
 165 block until the lock is unlocked.  Once the lock is unlocked
 166 (not owned by any thread), then grab ownership, set the
 167 recursion level to one, and return.  If more than one thread
 168 is blocked waiting until the lock is unlocked, only one at a
 169 time will be able to grab ownership of the lock.  There is no
 170 return value in this case.
 171
 172 When invoked with the \var{blocking} argument set to true, do the
 173 same thing as when called without arguments, and return true.
 174
 175 When invoked with the \var{blocking} argument set to false, do not
 176 block.  If a call without an argument would block, return false
 177 immediately; otherwise, do the same thing as when called
 178 without arguments, and return true.
 179 \end{methoddesc}
 180
 181 \begin{methoddesc}{release}{}
 182 Release a lock, decrementing the recursion level.  If after the
 183 decrement it is zero, reset the lock to unlocked (not owned by any
 184 thread), and if any other threads are blocked waiting for the lock to
 185 become unlocked, allow exactly one of them to proceed.  If after the
 186 decrement the recursion level is still nonzero, the lock remains
 187 locked and owned by the calling thread.
 188
 189 Only call this method when the calling thread owns the lock.
 190 Do not call this method when the lock is unlocked.
 191
 192 There is no return value.
 193 \end{methoddesc}
 194
 195
 196 \subsection{Condition Objects \label{condition-objects}}
 197
 198 A condition variable is always associated with some kind of lock;
 199 this can be passed in or one will be created by default.  (Passing
 200 one in is useful when several condition variables must share the
 201 same lock.)
 202
 203 A condition variable has \method{acquire()} and \method{release()}
 204 methods that call the corresponding methods of the associated lock.
 205 It also has a \method{wait()} method, and \method{notify()} and
 206 \method{notifyAll()} methods.  These three must only be called when
 207 the calling thread has acquired the lock.
 208
 209 The \method{wait()} method releases the lock, and then blocks until it
 210 is awakened by a \method{notify()} or \method{notifyAll()} call for
 211 the same condition variable in another thread.  Once awakened, it
 212 re-acquires the lock and returns.  It is also possible to specify a
 213 timeout.
 214
 215 The \method{notify()} method wakes up one of the threads waiting for
 216 the condition variable, if any are waiting.  The \method{notifyAll()}
 217 method wakes up all threads waiting for the condition variable.
 218
 219 Note: the \method{notify()} and \method{notifyAll()} methods don't
 220 release the lock; this means that the thread or threads awakened will
 221 not return from their \method{wait()} call immediately, but only when
 222 the thread that called \method{notify()} or \method{notifyAll()}
 223 finally relinquishes ownership of the lock.
 224
 225 Tip: the typical programming style using condition variables uses the
 226 lock to synchronize access to some shared state; threads that are
 227 interested in a particular change of state call \method{wait()}
 228 repeatedly until they see the desired state, while threads that modify
 229 the state call \method{notify()} or \method{notifyAll()} when they
 230 change the state in such a way that it could possibly be a desired
 231 state for one of the waiters.  For example, the following code is a
 232 generic producer-consumer situation with unlimited buffer capacity:
 233
 234 \begin{verbatim}
 235 # Consume one item
 236 cv.acquire()
 237 while not an_item_is_available():
 238     cv.wait()
 239 get_an_available_item()
 240 cv.release()
 241
 242 # Produce one item
 243 cv.acquire()
 244 make_an_item_available()
 245 cv.notify()
 246 cv.release()
 247 \end{verbatim}
 248
 249 To choose between \method{notify()} and \method{notifyAll()}, consider
 250 whether one state change can be interesting for only one or several
 251 waiting threads.  E.g. in a typical producer-consumer situation,
 252 adding one item to the buffer only needs to wake up one consumer
 253 thread.
 254
 255 \begin{classdesc}{Condition}{\optional{lock}}
 256 If the \var{lock} argument is given and not \code{None}, it must be a
 257 \class{Lock} or \class{RLock} object, and it is used as the underlying
 258 lock.  Otherwise, a new \class{RLock} object is created and used as
 259 the underlying lock.
 260 \end{classdesc}
 261
 262 \begin{methoddesc}{acquire}{*args}
 263 Acquire the underlying lock.
 264 This method calls the corresponding method on the underlying
 265 lock; the return value is whatever that method returns.
 266 \end{methoddesc}
 267
 268 \begin{methoddesc}{release}{}
 269 Release the underlying lock.
 270 This method calls the corresponding method on the underlying
 271 lock; there is no return value.
 272 \end{methoddesc}
 273
 274 \begin{methoddesc}{wait}{\optional{timeout}}
 275 Wait until notified or until a timeout occurs.
 276 This must only be called when the calling thread has acquired the
 277 lock.
 278
 279 This method releases the underlying lock, and then blocks until it is
 280 awakened by a \method{notify()} or \method{notifyAll()} call for the
 281 same condition variable in another thread, or until the optional
 282 timeout occurs.  Once awakened or timed out, it re-acquires the lock
 283 and returns.
 284
 285 When the \var{timeout} argument is present and not \code{None}, it
 286 should be a floating point number specifying a timeout for the
 287 operation in seconds (or fractions thereof).
 288
 289 When the underlying lock is an \class{RLock}, it is not released using
 290 its \method{release()} method, since this may not actually unlock the
 291 lock when it was acquired multiple times recursively.  Instead, an
 292 internal interface of the \class{RLock} class is used, which really
 293 unlocks it even when it has been recursively acquired several times.
 294 Another internal interface is then used to restore the recursion level
 295 when the lock is reacquired.
 296 \end{methoddesc}
 297
 298 \begin{methoddesc}{notify}{}
 299 Wake up a thread waiting on this condition, if any.
 300 This must only be called when the calling thread has acquired the
 301 lock.
 302
 303 This method wakes up one of the threads waiting for the condition
 304 variable, if any are waiting; it is a no-op if no threads are waiting.
 305
 306 The current implementation wakes up exactly one thread, if any are
 307 waiting.  However, it's not safe to rely on this behavior.  A future,
 308 optimized implementation may occasionally wake up more than one
 309 thread.
 310
 311 Note: the awakened thread does not actually return from its
 312 \method{wait()} call until it can reacquire the lock.  Since
 313 \method{notify()} does not release the lock, its caller should.
 314 \end{methoddesc}
 315
 316 \begin{methoddesc}{notifyAll}{}
 317 Wake up all threads waiting on this condition.  This method acts like
 318 \method{notify()}, but wakes up all waiting threads instead of one.
 319 \end{methoddesc}
 320
 321
 322 \subsection{Semaphore Objects \label{semaphore-objects}}
 323
 324 This is one of the oldest synchronization primitives in the history of
 325 computer science, invented by the early Dutch computer scientist
 326 Edsger W. Dijkstra (he used \method{P()} and \method{V()} instead of
 327 \method{acquire()} and \method{release()}).
 328
 329 A semaphore manages an internal counter which is decremented by each
 330 \method{acquire()} call and incremented by each \method{release()}
 331 call.  The counter can never go below zero; when \method{acquire()}
 332 finds that it is zero, it blocks, waiting until some other thread
 333 calls \method{release()}.
 334
 335 \begin{classdesc}{Semaphore}{\optional{value}}
 336 The optional argument gives the initial value for the internal
 337 counter; it defaults to \code{1}.
 338 \end{classdesc}
 339
 340 \begin{methoddesc}{acquire}{\optional{blocking}}
 341 Acquire a semaphore.
 342
 343 When invoked without arguments: if the internal counter is larger than
 344 zero on entry, decrement it by one and return immediately.  If it is
 345 zero on entry, block, waiting until some other thread has called
 346 \method{release()} to make it larger than zero.  This is done with
 347 proper interlocking so that if multiple \method{acquire()} calls are
 348 blocked, \method{release()} will wake exactly one of them up.  The
 349 implementation may pick one at random, so the order in which blocked
 350 threads are awakened should not be relied on.  There is no return
 351 value in this case.
 352
 353 When invoked with \var{blocking} set to true, do the same thing as
 354 when called without arguments, and return true.
 355
 356 When invoked with \var{blocking} set to false, do not block.  If a
 357 call without an argument would block, return false immediately;
 358 otherwise, do the same thing as when called without arguments, and
 359 return true.
 360 \end{methoddesc}
 361
 362 \begin{methoddesc}{release}{}
 363 Release a semaphore,
 364 incrementing the internal counter by one.  When it was zero on
 365 entry and another thread is waiting for it to become larger
 366 than zero again, wake up that thread.
 367 \end{methoddesc}
 368
 369
 370 \subsection{Event Objects \label{event-objects}}
 371
 372 This is one of the simplest mechanisms for communication between
 373 threads: one thread signals an event and one or more other threads
 374 are waiting for it.
 375
 376 An event object manages an internal flag that can be set to true with
 377 the \method{set()} method and reset to false with the \method{clear()} method.  The
 378 \method{wait()} method blocks until the flag is true.
 379
 380
 381 \begin{classdesc}{Event}{}
 382 The internal flag is initially false.
 383 \end{classdesc}
 384
 385 \begin{methoddesc}{isSet}{}
 386 Return true if and only if the internal flag is true.
 387 \end{methoddesc}
 388
 389 \begin{methoddesc}{set}{}
 390 Set the internal flag to true.
 391 All threads waiting for it to become true are awakened.
 392 Threads that call \method{wait()} once the flag is true will not block
 393 at all.
 394 \end{methoddesc}
 395
 396 \begin{methoddesc}{clear}{}
 397 Reset the internal flag to false.
 398 Subsequently, threads calling \method{wait()} will block until \method{set()} is
 399 called to set the internal flag to true again.
 400 \end{methoddesc}
 401
 402 \begin{methoddesc}{wait}{\optional{timeout}}
 403 Block until the internal flag is true.
 404 If the internal flag is true on entry, return immediately.  Otherwise,
 405 block until another thread calls \method{set()} to set the flag to
 406 true, or until the optional timeout occurs.
 407
 408 When the timeout argument is present and not \code{None}, it should be a
 409 floating point number specifying a timeout for the operation in
 410 seconds (or fractions thereof).
 411 \end{methoddesc}
 412
 413
 414 \subsection{Thread Objects \label{thread-objects}}
 415
 416 This class represents an activity that is run in a separate thread
 417 of control.  There are two ways to specify the activity: by
 418 passing a callable object to the constructor, or by overriding the
 419 \method{run()} method in a subclass.  No other methods (except for the
 420 constructor) should be overridden in a subclass.  In other words,
 421 \emph{only}  override the \method{__init__()} and \method{run()}
 422 methods of this class.
 423
 424 Once a thread object is created, its activity must be started by
 425 calling the thread's \method{start()} method.  This invokes the
 426 \method{run()} method in a separate thread of control.
 427
 428 Once the thread's activity is started, the thread is considered
 429 'alive' and 'active' (these concepts are almost, but not quite
 430 exactly, the same; their definition is intentionally somewhat
 431 vague).  It stops being alive and active when its \method{run()}
 432 method terminates -- either normally, or by raising an unhandled
 433 exception.  The \method{isAlive()} method tests whether the thread is
 434 alive.
 435
 436 Other threads can call a thread's \method{join()} method.  This blocks
 437 the calling thread until the thread whose \method{join()} method is
 438 called is terminated.
 439
 440 A thread has a name.  The name can be passed to the constructor,
 441 set with the \method{setName()} method, and retrieved with the
 442 \method{getName()} method.
 443
 444 A thread can be flagged as a ``daemon thread''.  The significance
 445 of this flag is that the entire Python program exits when only
 446 daemon threads are left.  The initial value is inherited from the
 447 creating thread.  The flag can be set with the \method{setDaemon()}
 448 method and retrieved with the \method{isDaemon()} method.
 449
 450 There is a ``main thread'' object; this corresponds to the
 451 initial thread of control in the Python program.  It is not a
 452 daemon thread.
 453
 454 There is the possibility that ``dummy thread objects'' are
 455 created.  These are thread objects corresponding to ``alien
 456 threads''.  These are threads of control started outside the
 457 threading module, such as directly from C code.  Dummy thread objects
 458 have limited functionality; they are always considered alive,
 459 active, and daemonic, and cannot be \method{join()}ed.  They are never
 460 deleted, since it is impossible to detect the termination of alien
 461 threads.
 462
 463
 464 \begin{classdesc}{Thread}{group=None, target=None, name=None,
 465                           args=(), kwargs=\{\}}
 466 This constructor should always be called with keyword
 467 arguments.  Arguments are:
 468
 469 \var{group} should be \code{None}; reserved for future extension when
 470 a \class{ThreadGroup} class is implemented.
 471
 472 \var{target} is the callable object to be invoked by the
 473 \method{run()} method.  Defaults to \code{None}, meaning nothing is
 474 called.
 475
 476 \var{name} is the thread name.  By default, a unique name is
 477 constructed of the form ``Thread-\var{N}'' where \var{N} is a small
 478 decimal number.
 479
 480 \var{args} is the argument tuple for the target invocation.  Defaults
 481 to \code{()}.
 482
 483 \var{kwargs} is a dictionary of keyword arguments for the target
 484 invocation.  Defaults to \code{\{\}}.
 485
 486 If the subclass overrides the constructor, it must make sure
 487 to invoke the base class constructor (\code{Thread.__init__()})
 488 before doing anything else to the thread.
 489 \end{classdesc}
 490
 491 \begin{methoddesc}{start}{}
 492 Start the thread's activity.
 493
 494 This must be called at most once per thread object.  It
 495 arranges for the object's \method{run()} method to be invoked in a
 496 separate thread of control.
 497 \end{methoddesc}
 498
 499 \begin{methoddesc}{run}{}
 500 Method representing the thread's activity.
 501
 502 You may override this method in a subclass.  The standard
 503 \method{run()} method invokes the callable object passed to the object's constructor as the
 504 \var{target} argument, if any, with sequential and keyword
 505 arguments taken from the \var{args} and \var{kwargs} arguments,
 506 respectively.
 507 \end{methoddesc}
 508
 509 \begin{methoddesc}{join}{\optional{timeout}}
 510 Wait until the thread terminates.
 511 This blocks the calling thread until the thread whose \method{join()}
 512 method is called terminates -- either normally or through an
 513 unhandled exception -- or until the optional timeout occurs.
 514
 515 When the \var{timeout} argument is present and not \code{None}, it should
 516 be a floating point number specifying a timeout for the
 517 operation in seconds (or fractions thereof).
 518
 519 A thread can be \method{join()}ed many times.
 520
 521 A thread cannot join itself because this would cause a
 522 deadlock.
 523
 524 It is an error to attempt to \method{join()} a thread before it has
 525 been started.
 526 \end{methoddesc}
 527
 528 \begin{methoddesc}{getName}{}
 529 Return the thread's name.
 530 \end{methoddesc}
 531
 532 \begin{methoddesc}{setName}{name}
 533 Set the thread's name.
 534
 535 The name is a string used for identification purposes only.
 536 It has no semantics.  Multiple threads may be given the same
 537 name.  The initial name is set by the constructor.
 538 \end{methoddesc}
 539
 540 \begin{methoddesc}{isAlive}{}
 541 Return whether the thread is alive.
 542
 543 Roughly, a thread is alive from the moment the \method{start()} method
 544 returns until its \method{run()} method terminates.
 545 \end{methoddesc}
 546
 547 \begin{methoddesc}{isDaemon}{}
 548 Return the thread's daemon flag.
 549 \end{methoddesc}
 550
 551 \begin{methoddesc}{setDaemon}{daemonic}
 552 Set the thread's daemon flag to the Boolean value \var{daemonic}.
 553 This must be called before \method{start()} is called.
 554
 555 The initial value is inherited from the creating thread.
 556
 557 The entire Python program exits when no active non-daemon
 558 threads are left.
 559 \end{methoddesc}