1:mod:`!threading` --- Thread-based parallelism 2============================================== 3 4.. module:: threading 5 :synopsis: Thread-based parallelism. 6 7**Source code:** :source:`Lib/threading.py` 8 9-------------- 10 11This module constructs higher-level threading interfaces on top of the lower 12level :mod:`_thread` module. 13 14.. versionchanged:: 3.7 15 This module used to be optional, it is now always available. 16 17.. seealso:: 18 19 :class:`concurrent.futures.ThreadPoolExecutor` offers a higher level interface 20 to push tasks to a background thread without blocking execution of the 21 calling thread, while still being able to retrieve their results when needed. 22 23 :mod:`queue` provides a thread-safe interface for exchanging data between 24 running threads. 25 26 :mod:`asyncio` offers an alternative approach to achieving task level 27 concurrency without requiring the use of multiple operating system threads. 28 29.. note:: 30 31 In the Python 2.x series, this module contained ``camelCase`` names 32 for some methods and functions. These are deprecated as of Python 3.10, 33 but they are still supported for compatibility with Python 2.5 and lower. 34 35 36.. impl-detail:: 37 38 In CPython, due to the :term:`Global Interpreter Lock 39 <global interpreter lock>`, only one thread 40 can execute Python code at once (even though certain performance-oriented 41 libraries might overcome this limitation). 42 If you want your application to make better use of the computational 43 resources of multi-core machines, you are advised to use 44 :mod:`multiprocessing` or :class:`concurrent.futures.ProcessPoolExecutor`. 45 However, threading is still an appropriate model if you want to run 46 multiple I/O-bound tasks simultaneously. 47 48.. include:: ../includes/wasm-notavail.rst 49 50This module defines the following functions: 51 52 53.. function:: active_count() 54 55 Return the number of :class:`Thread` objects currently alive. The returned 56 count is equal to the length of the list returned by :func:`.enumerate`. 57 58 The function ``activeCount`` is a deprecated alias for this function. 59 60 61.. function:: current_thread() 62 63 Return the current :class:`Thread` object, corresponding to the caller's thread 64 of control. If the caller's thread of control was not created through the 65 :mod:`threading` module, a dummy thread object with limited functionality is 66 returned. 67 68 The function ``currentThread`` is a deprecated alias for this function. 69 70 71.. function:: excepthook(args, /) 72 73 Handle uncaught exception raised by :func:`Thread.run`. 74 75 The *args* argument has the following attributes: 76 77 * *exc_type*: Exception type. 78 * *exc_value*: Exception value, can be ``None``. 79 * *exc_traceback*: Exception traceback, can be ``None``. 80 * *thread*: Thread which raised the exception, can be ``None``. 81 82 If *exc_type* is :exc:`SystemExit`, the exception is silently ignored. 83 Otherwise, the exception is printed out on :data:`sys.stderr`. 84 85 If this function raises an exception, :func:`sys.excepthook` is called to 86 handle it. 87 88 :func:`threading.excepthook` can be overridden to control how uncaught 89 exceptions raised by :func:`Thread.run` are handled. 90 91 Storing *exc_value* using a custom hook can create a reference cycle. It 92 should be cleared explicitly to break the reference cycle when the 93 exception is no longer needed. 94 95 Storing *thread* using a custom hook can resurrect it if it is set to an 96 object which is being finalized. Avoid storing *thread* after the custom 97 hook completes to avoid resurrecting objects. 98 99 .. seealso:: 100 :func:`sys.excepthook` handles uncaught exceptions. 101 102 .. versionadded:: 3.8 103 104.. data:: __excepthook__ 105 106 Holds the original value of :func:`threading.excepthook`. It is saved so that the 107 original value can be restored in case they happen to get replaced with 108 broken or alternative objects. 109 110 .. versionadded:: 3.10 111 112.. function:: get_ident() 113 114 Return the 'thread identifier' of the current thread. This is a nonzero 115 integer. Its value has no direct meaning; it is intended as a magic cookie 116 to be used e.g. to index a dictionary of thread-specific data. Thread 117 identifiers may be recycled when a thread exits and another thread is 118 created. 119 120 .. versionadded:: 3.3 121 122 123.. function:: get_native_id() 124 125 Return the native integral Thread ID of the current thread assigned by the kernel. 126 This is a non-negative integer. 127 Its value may be used to uniquely identify this particular thread system-wide 128 (until the thread terminates, after which the value may be recycled by the OS). 129 130 .. availability:: Windows, FreeBSD, Linux, macOS, OpenBSD, NetBSD, AIX, DragonFlyBSD, GNU/kFreeBSD. 131 132 .. versionadded:: 3.8 133 134 .. versionchanged:: 3.13 135 Added support for GNU/kFreeBSD. 136 137 138.. function:: enumerate() 139 140 Return a list of all :class:`Thread` objects currently active. The list 141 includes daemonic threads and dummy thread objects created by 142 :func:`current_thread`. It excludes terminated threads and threads 143 that have not yet been started. However, the main thread is always part 144 of the result, even when terminated. 145 146 147.. function:: main_thread() 148 149 Return the main :class:`Thread` object. In normal conditions, the 150 main thread is the thread from which the Python interpreter was 151 started. 152 153 .. versionadded:: 3.4 154 155 156.. function:: settrace(func) 157 158 .. index:: single: trace function 159 160 Set a trace function for all threads started from the :mod:`threading` module. 161 The *func* will be passed to :func:`sys.settrace` for each thread, before its 162 :meth:`~Thread.run` method is called. 163 164.. function:: settrace_all_threads(func) 165 166 Set a trace function for all threads started from the :mod:`threading` module 167 and all Python threads that are currently executing. 168 169 The *func* will be passed to :func:`sys.settrace` for each thread, before its 170 :meth:`~Thread.run` method is called. 171 172 .. versionadded:: 3.12 173 174.. function:: gettrace() 175 176 .. index:: 177 single: trace function 178 single: debugger 179 180 Get the trace function as set by :func:`settrace`. 181 182 .. versionadded:: 3.10 183 184 185.. function:: setprofile(func) 186 187 .. index:: single: profile function 188 189 Set a profile function for all threads started from the :mod:`threading` module. 190 The *func* will be passed to :func:`sys.setprofile` for each thread, before its 191 :meth:`~Thread.run` method is called. 192 193.. function:: setprofile_all_threads(func) 194 195 Set a profile function for all threads started from the :mod:`threading` module 196 and all Python threads that are currently executing. 197 198 The *func* will be passed to :func:`sys.setprofile` for each thread, before its 199 :meth:`~Thread.run` method is called. 200 201 .. versionadded:: 3.12 202 203.. function:: getprofile() 204 205 .. index:: single: profile function 206 207 Get the profiler function as set by :func:`setprofile`. 208 209 .. versionadded:: 3.10 210 211 212.. function:: stack_size([size]) 213 214 Return the thread stack size used when creating new threads. The optional 215 *size* argument specifies the stack size to be used for subsequently created 216 threads, and must be 0 (use platform or configured default) or a positive 217 integer value of at least 32,768 (32 KiB). If *size* is not specified, 218 0 is used. If changing the thread stack size is 219 unsupported, a :exc:`RuntimeError` is raised. If the specified stack size is 220 invalid, a :exc:`ValueError` is raised and the stack size is unmodified. 32 KiB 221 is currently the minimum supported stack size value to guarantee sufficient 222 stack space for the interpreter itself. Note that some platforms may have 223 particular restrictions on values for the stack size, such as requiring a 224 minimum stack size > 32 KiB or requiring allocation in multiples of the system 225 memory page size - platform documentation should be referred to for more 226 information (4 KiB pages are common; using multiples of 4096 for the stack size is 227 the suggested approach in the absence of more specific information). 228 229 .. availability:: Windows, pthreads. 230 231 Unix platforms with POSIX threads support. 232 233 234This module also defines the following constant: 235 236.. data:: TIMEOUT_MAX 237 238 The maximum value allowed for the *timeout* parameter of blocking functions 239 (:meth:`Lock.acquire`, :meth:`RLock.acquire`, :meth:`Condition.wait`, etc.). 240 Specifying a timeout greater than this value will raise an 241 :exc:`OverflowError`. 242 243 .. versionadded:: 3.2 244 245 246This module defines a number of classes, which are detailed in the sections 247below. 248 249The design of this module is loosely based on Java's threading model. However, 250where Java makes locks and condition variables basic behavior of every object, 251they are separate objects in Python. Python's :class:`Thread` class supports a 252subset of the behavior of Java's Thread class; currently, there are no 253priorities, no thread groups, and threads cannot be destroyed, stopped, 254suspended, resumed, or interrupted. The static methods of Java's Thread class, 255when implemented, are mapped to module-level functions. 256 257All of the methods described below are executed atomically. 258 259 260Thread-Local Data 261----------------- 262 263Thread-local data is data whose values are thread specific. To manage 264thread-local data, just create an instance of :class:`local` (or a 265subclass) and store attributes on it:: 266 267 mydata = threading.local() 268 mydata.x = 1 269 270The instance's values will be different for separate threads. 271 272 273.. class:: local() 274 275 A class that represents thread-local data. 276 277 For more details and extensive examples, see the documentation string of the 278 :mod:`!_threading_local` module: :source:`Lib/_threading_local.py`. 279 280 281.. _thread-objects: 282 283Thread Objects 284-------------- 285 286The :class:`Thread` class represents an activity that is run in a separate 287thread of control. There are two ways to specify the activity: by passing a 288callable object to the constructor, or by overriding the :meth:`~Thread.run` 289method in a subclass. No other methods (except for the constructor) should be 290overridden in a subclass. In other words, *only* override the 291``__init__()`` and :meth:`~Thread.run` methods of this class. 292 293Once a thread object is created, its activity must be started by calling the 294thread's :meth:`~Thread.start` method. This invokes the :meth:`~Thread.run` 295method in a separate thread of control. 296 297Once the thread's activity is started, the thread is considered 'alive'. It 298stops being alive when its :meth:`~Thread.run` method terminates -- either 299normally, or by raising an unhandled exception. The :meth:`~Thread.is_alive` 300method tests whether the thread is alive. 301 302Other threads can call a thread's :meth:`~Thread.join` method. This blocks 303the calling thread until the thread whose :meth:`~Thread.join` method is 304called is terminated. 305 306A thread has a name. The name can be passed to the constructor, and read or 307changed through the :attr:`~Thread.name` attribute. 308 309If the :meth:`~Thread.run` method raises an exception, 310:func:`threading.excepthook` is called to handle it. By default, 311:func:`threading.excepthook` ignores silently :exc:`SystemExit`. 312 313A thread can be flagged as a "daemon thread". The significance of this flag is 314that the entire Python program exits when only daemon threads are left. The 315initial value is inherited from the creating thread. The flag can be set 316through the :attr:`~Thread.daemon` property or the *daemon* constructor 317argument. 318 319.. note:: 320 Daemon threads are abruptly stopped at shutdown. Their resources (such 321 as open files, database transactions, etc.) may not be released properly. 322 If you want your threads to stop gracefully, make them non-daemonic and 323 use a suitable signalling mechanism such as an :class:`Event`. 324 325There is a "main thread" object; this corresponds to the initial thread of 326control in the Python program. It is not a daemon thread. 327 328There is the possibility that "dummy thread objects" are created. These are 329thread objects corresponding to "alien threads", which are threads of control 330started outside the threading module, such as directly from C code. Dummy 331thread objects have limited functionality; they are always considered alive and 332daemonic, and cannot be :ref:`joined <meth-thread-join>`. They are never deleted, 333since it is impossible to detect the termination of alien threads. 334 335 336.. class:: Thread(group=None, target=None, name=None, args=(), kwargs={}, *, \ 337 daemon=None) 338 339 This constructor should always be called with keyword arguments. Arguments 340 are: 341 342 *group* should be ``None``; reserved for future extension when a 343 :class:`!ThreadGroup` class is implemented. 344 345 *target* is the callable object to be invoked by the :meth:`run` method. 346 Defaults to ``None``, meaning nothing is called. 347 348 *name* is the thread name. By default, a unique name is constructed 349 of the form "Thread-*N*" where *N* is a small decimal number, 350 or "Thread-*N* (target)" where "target" is ``target.__name__`` if the 351 *target* argument is specified. 352 353 *args* is a list or tuple of arguments for the target invocation. Defaults to ``()``. 354 355 *kwargs* is a dictionary of keyword arguments for the target invocation. 356 Defaults to ``{}``. 357 358 If not ``None``, *daemon* explicitly sets whether the thread is daemonic. 359 If ``None`` (the default), the daemonic property is inherited from the 360 current thread. 361 362 If the subclass overrides the constructor, it must make sure to invoke the 363 base class constructor (``Thread.__init__()``) before doing anything else to 364 the thread. 365 366 .. versionchanged:: 3.3 367 Added the *daemon* parameter. 368 369 .. versionchanged:: 3.10 370 Use the *target* name if *name* argument is omitted. 371 372 .. method:: start() 373 374 Start the thread's activity. 375 376 It must be called at most once per thread object. It arranges for the 377 object's :meth:`~Thread.run` method to be invoked in a separate thread 378 of control. 379 380 This method will raise a :exc:`RuntimeError` if called more than once 381 on the same thread object. 382 383 .. method:: run() 384 385 Method representing the thread's activity. 386 387 You may override this method in a subclass. The standard :meth:`run` 388 method invokes the callable object passed to the object's constructor as 389 the *target* argument, if any, with positional and keyword arguments taken 390 from the *args* and *kwargs* arguments, respectively. 391 392 Using list or tuple as the *args* argument which passed to the :class:`Thread` 393 could achieve the same effect. 394 395 Example:: 396 397 >>> from threading import Thread 398 >>> t = Thread(target=print, args=[1]) 399 >>> t.run() 400 1 401 >>> t = Thread(target=print, args=(1,)) 402 >>> t.run() 403 1 404 405 .. _meth-thread-join: 406 407 .. method:: join(timeout=None) 408 409 Wait until the thread terminates. This blocks the calling thread until 410 the thread whose :meth:`~Thread.join` method is called terminates -- either 411 normally or through an unhandled exception -- or until the optional 412 timeout occurs. 413 414 When the *timeout* argument is present and not ``None``, it should be a 415 floating-point number specifying a timeout for the operation in seconds 416 (or fractions thereof). As :meth:`~Thread.join` always returns ``None``, 417 you must call :meth:`~Thread.is_alive` after :meth:`~Thread.join` to 418 decide whether a timeout happened -- if the thread is still alive, the 419 :meth:`~Thread.join` call timed out. 420 421 When the *timeout* argument is not present or ``None``, the operation will 422 block until the thread terminates. 423 424 A thread can be joined many times. 425 426 :meth:`~Thread.join` raises a :exc:`RuntimeError` if an attempt is made 427 to join the current thread as that would cause a deadlock. It is also 428 an error to :meth:`~Thread.join` a thread before it has been started 429 and attempts to do so raise the same exception. 430 431 .. attribute:: name 432 433 A string used for identification purposes only. It has no semantics. 434 Multiple threads may be given the same name. The initial name is set by 435 the constructor. 436 437 .. method:: getName() 438 setName() 439 440 Deprecated getter/setter API for :attr:`~Thread.name`; use it directly as a 441 property instead. 442 443 .. deprecated:: 3.10 444 445 .. attribute:: ident 446 447 The 'thread identifier' of this thread or ``None`` if the thread has not 448 been started. This is a nonzero integer. See the :func:`get_ident` 449 function. Thread identifiers may be recycled when a thread exits and 450 another thread is created. The identifier is available even after the 451 thread has exited. 452 453 .. attribute:: native_id 454 455 The Thread ID (``TID``) of this thread, as assigned by the OS (kernel). 456 This is a non-negative integer, or ``None`` if the thread has not 457 been started. See the :func:`get_native_id` function. 458 This value may be used to uniquely identify this particular thread 459 system-wide (until the thread terminates, after which the value 460 may be recycled by the OS). 461 462 .. note:: 463 464 Similar to Process IDs, Thread IDs are only valid (guaranteed unique 465 system-wide) from the time the thread is created until the thread 466 has been terminated. 467 468 .. availability:: Windows, FreeBSD, Linux, macOS, OpenBSD, NetBSD, AIX, DragonFlyBSD. 469 470 .. versionadded:: 3.8 471 472 .. method:: is_alive() 473 474 Return whether the thread is alive. 475 476 This method returns ``True`` just before the :meth:`~Thread.run` method 477 starts until just after the :meth:`~Thread.run` method terminates. The 478 module function :func:`.enumerate` returns a list of all alive threads. 479 480 .. attribute:: daemon 481 482 A boolean value indicating whether this thread is a daemon thread (``True``) 483 or not (``False``). This must be set before :meth:`~Thread.start` is called, 484 otherwise :exc:`RuntimeError` is raised. Its initial value is inherited 485 from the creating thread; the main thread is not a daemon thread and 486 therefore all threads created in the main thread default to 487 :attr:`~Thread.daemon` = ``False``. 488 489 The entire Python program exits when no alive non-daemon threads are left. 490 491 .. method:: isDaemon() 492 setDaemon() 493 494 Deprecated getter/setter API for :attr:`~Thread.daemon`; use it directly as a 495 property instead. 496 497 .. deprecated:: 3.10 498 499 500.. _lock-objects: 501 502Lock Objects 503------------ 504 505A primitive lock is a synchronization primitive that is not owned by a 506particular thread when locked. In Python, it is currently the lowest level 507synchronization primitive available, implemented directly by the :mod:`_thread` 508extension module. 509 510A primitive lock is in one of two states, "locked" or "unlocked". It is created 511in the unlocked state. It has two basic methods, :meth:`~Lock.acquire` and 512:meth:`~Lock.release`. When the state is unlocked, :meth:`~Lock.acquire` 513changes the state to locked and returns immediately. When the state is locked, 514:meth:`~Lock.acquire` blocks until a call to :meth:`~Lock.release` in another 515thread changes it to unlocked, then the :meth:`~Lock.acquire` call resets it 516to locked and returns. The :meth:`~Lock.release` method should only be 517called in the locked state; it changes the state to unlocked and returns 518immediately. If an attempt is made to release an unlocked lock, a 519:exc:`RuntimeError` will be raised. 520 521Locks also support the :ref:`context management protocol <with-locks>`. 522 523When more than one thread is blocked in :meth:`~Lock.acquire` waiting for the 524state to turn to unlocked, only one thread proceeds when a :meth:`~Lock.release` 525call resets the state to unlocked; which one of the waiting threads proceeds 526is not defined, and may vary across implementations. 527 528All methods are executed atomically. 529 530 531.. class:: Lock() 532 533 The class implementing primitive lock objects. Once a thread has acquired a 534 lock, subsequent attempts to acquire it block, until it is released; any 535 thread may release it. 536 537 .. versionchanged:: 3.13 538 ``Lock`` is now a class. In earlier Pythons, ``Lock`` was a factory 539 function which returned an instance of the underlying private lock 540 type. 541 542 543 .. method:: acquire(blocking=True, timeout=-1) 544 545 Acquire a lock, blocking or non-blocking. 546 547 When invoked with the *blocking* argument set to ``True`` (the default), 548 block until the lock is unlocked, then set it to locked and return ``True``. 549 550 When invoked with the *blocking* argument set to ``False``, do not block. 551 If a call with *blocking* set to ``True`` would block, return ``False`` 552 immediately; otherwise, set the lock to locked and return ``True``. 553 554 When invoked with the floating-point *timeout* argument set to a positive 555 value, block for at most the number of seconds specified by *timeout* 556 and as long as the lock cannot be acquired. A *timeout* argument of ``-1`` 557 specifies an unbounded wait. It is forbidden to specify a *timeout* 558 when *blocking* is ``False``. 559 560 The return value is ``True`` if the lock is acquired successfully, 561 ``False`` if not (for example if the *timeout* expired). 562 563 .. versionchanged:: 3.2 564 The *timeout* parameter is new. 565 566 .. versionchanged:: 3.2 567 Lock acquisition can now be interrupted by signals on POSIX if the 568 underlying threading implementation supports it. 569 570 571 .. method:: release() 572 573 Release a lock. This can be called from any thread, not only the thread 574 which has acquired the lock. 575 576 When the lock is locked, reset it to unlocked, and return. If any other threads 577 are blocked waiting for the lock to become unlocked, allow exactly one of them 578 to proceed. 579 580 When invoked on an unlocked lock, a :exc:`RuntimeError` is raised. 581 582 There is no return value. 583 584 .. method:: locked() 585 586 Return ``True`` if the lock is acquired. 587 588 589 590.. _rlock-objects: 591 592RLock Objects 593------------- 594 595A reentrant lock is a synchronization primitive that may be acquired multiple 596times by the same thread. Internally, it uses the concepts of "owning thread" 597and "recursion level" in addition to the locked/unlocked state used by primitive 598locks. In the locked state, some thread owns the lock; in the unlocked state, 599no thread owns it. 600 601Threads call a lock's :meth:`~RLock.acquire` method to lock it, 602and its :meth:`~Lock.release` method to unlock it. 603 604.. note:: 605 606 Reentrant locks support the :ref:`context management protocol <with-locks>`, 607 so it is recommended to use :keyword:`with` instead of manually calling 608 :meth:`~RLock.acquire` and :meth:`~RLock.release` 609 to handle acquiring and releasing the lock for a block of code. 610 611RLock's :meth:`~RLock.acquire`/:meth:`~RLock.release` call pairs may be nested, 612unlike Lock's :meth:`~Lock.acquire`/:meth:`~Lock.release`. Only the final 613:meth:`~RLock.release` (the :meth:`~Lock.release` of the outermost pair) resets 614the lock to an unlocked state and allows another thread blocked in 615:meth:`~RLock.acquire` to proceed. 616 617:meth:`~RLock.acquire`/:meth:`~RLock.release` must be used in pairs: each acquire 618must have a release in the thread that has acquired the lock. Failing to 619call release as many times the lock has been acquired can lead to deadlock. 620 621 622.. class:: RLock() 623 624 This class implements reentrant lock objects. A reentrant lock must be 625 released by the thread that acquired it. Once a thread has acquired a 626 reentrant lock, the same thread may acquire it again without blocking; the 627 thread must release it once for each time it has acquired it. 628 629 Note that ``RLock`` is actually a factory function which returns an instance 630 of the most efficient version of the concrete RLock class that is supported 631 by the platform. 632 633 634 .. method:: acquire(blocking=True, timeout=-1) 635 636 Acquire a lock, blocking or non-blocking. 637 638 .. seealso:: 639 640 :ref:`Using RLock as a context manager <with-locks>` 641 Recommended over manual :meth:`!acquire` and :meth:`release` calls 642 whenever practical. 643 644 645 When invoked with the *blocking* argument set to ``True`` (the default): 646 647 * If no thread owns the lock, acquire the lock and return immediately. 648 649 * If another thread owns the lock, block until we are able to acquire 650 lock, or *timeout*, if set to a positive float value. 651 652 * If the same thread owns the lock, acquire the lock again, and 653 return immediately. This is the difference between :class:`Lock` and 654 :class:`!RLock`; :class:`Lock` handles this case the same as the previous, 655 blocking until the lock can be acquired. 656 657 When invoked with the *blocking* argument set to ``False``: 658 659 * If no thread owns the lock, acquire the lock and return immediately. 660 661 * If another thread owns the lock, return immediately. 662 663 * If the same thread owns the lock, acquire the lock again and return 664 immediately. 665 666 In all cases, if the thread was able to acquire the lock, return ``True``. 667 If the thread was unable to acquire the lock (i.e. if not blocking or 668 the timeout was reached) return ``False``. 669 670 If called multiple times, failing to call :meth:`~RLock.release` as many times 671 may lead to deadlock. Consider using :class:`!RLock` as a context manager rather than 672 calling acquire/release directly. 673 674 .. versionchanged:: 3.2 675 The *timeout* parameter is new. 676 677 678 .. method:: release() 679 680 Release a lock, decrementing the recursion level. If after the decrement it is 681 zero, reset the lock to unlocked (not owned by any thread), and if any other 682 threads are blocked waiting for the lock to become unlocked, allow exactly one 683 of them to proceed. If after the decrement the recursion level is still 684 nonzero, the lock remains locked and owned by the calling thread. 685 686 Only call this method when the calling thread owns the lock. A 687 :exc:`RuntimeError` is raised if this method is called when the lock is 688 not acquired. 689 690 There is no return value. 691 692 693.. _condition-objects: 694 695Condition Objects 696----------------- 697 698A condition variable is always associated with some kind of lock; this can be 699passed in or one will be created by default. Passing one in is useful when 700several condition variables must share the same lock. The lock is part of 701the condition object: you don't have to track it separately. 702 703A condition variable obeys the :ref:`context management protocol <with-locks>`: 704using the ``with`` statement acquires the associated lock for the duration of 705the enclosed block. The :meth:`~Condition.acquire` and 706:meth:`~Condition.release` methods also call the corresponding methods of 707the associated lock. 708 709Other methods must be called with the associated lock held. The 710:meth:`~Condition.wait` method releases the lock, and then blocks until 711another thread awakens it by calling :meth:`~Condition.notify` or 712:meth:`~Condition.notify_all`. Once awakened, :meth:`~Condition.wait` 713re-acquires the lock and returns. It is also possible to specify a timeout. 714 715The :meth:`~Condition.notify` method wakes up one of the threads waiting for 716the condition variable, if any are waiting. The :meth:`~Condition.notify_all` 717method wakes up all threads waiting for the condition variable. 718 719Note: the :meth:`~Condition.notify` and :meth:`~Condition.notify_all` methods 720don't release the lock; this means that the thread or threads awakened will 721not return from their :meth:`~Condition.wait` call immediately, but only when 722the thread that called :meth:`~Condition.notify` or :meth:`~Condition.notify_all` 723finally relinquishes ownership of the lock. 724 725The typical programming style using condition variables uses the lock to 726synchronize access to some shared state; threads that are interested in a 727particular change of state call :meth:`~Condition.wait` repeatedly until they 728see the desired state, while threads that modify the state call 729:meth:`~Condition.notify` or :meth:`~Condition.notify_all` when they change 730the state in such a way that it could possibly be a desired state for one 731of the waiters. For example, the following code is a generic 732producer-consumer situation with unlimited buffer capacity:: 733 734 # Consume one item 735 with cv: 736 while not an_item_is_available(): 737 cv.wait() 738 get_an_available_item() 739 740 # Produce one item 741 with cv: 742 make_an_item_available() 743 cv.notify() 744 745The ``while`` loop checking for the application's condition is necessary 746because :meth:`~Condition.wait` can return after an arbitrary long time, 747and the condition which prompted the :meth:`~Condition.notify` call may 748no longer hold true. This is inherent to multi-threaded programming. The 749:meth:`~Condition.wait_for` method can be used to automate the condition 750checking, and eases the computation of timeouts:: 751 752 # Consume an item 753 with cv: 754 cv.wait_for(an_item_is_available) 755 get_an_available_item() 756 757To choose between :meth:`~Condition.notify` and :meth:`~Condition.notify_all`, 758consider whether one state change can be interesting for only one or several 759waiting threads. E.g. in a typical producer-consumer situation, adding one 760item to the buffer only needs to wake up one consumer thread. 761 762 763.. class:: Condition(lock=None) 764 765 This class implements condition variable objects. A condition variable 766 allows one or more threads to wait until they are notified by another thread. 767 768 If the *lock* argument is given and not ``None``, it must be a :class:`Lock` 769 or :class:`RLock` object, and it is used as the underlying lock. Otherwise, 770 a new :class:`RLock` object is created and used as the underlying lock. 771 772 .. versionchanged:: 3.3 773 changed from a factory function to a class. 774 775 .. method:: acquire(*args) 776 777 Acquire the underlying lock. This method calls the corresponding method on 778 the underlying lock; the return value is whatever that method returns. 779 780 .. method:: release() 781 782 Release the underlying lock. This method calls the corresponding method on 783 the underlying lock; there is no return value. 784 785 .. method:: wait(timeout=None) 786 787 Wait until notified or until a timeout occurs. If the calling thread has 788 not acquired the lock when this method is called, a :exc:`RuntimeError` is 789 raised. 790 791 This method releases the underlying lock, and then blocks until it is 792 awakened by a :meth:`notify` or :meth:`notify_all` call for the same 793 condition variable in another thread, or until the optional timeout 794 occurs. Once awakened or timed out, it re-acquires the lock and returns. 795 796 When the *timeout* argument is present and not ``None``, it should be a 797 floating-point number specifying a timeout for the operation in seconds 798 (or fractions thereof). 799 800 When the underlying lock is an :class:`RLock`, it is not released using 801 its :meth:`release` method, since this may not actually unlock the lock 802 when it was acquired multiple times recursively. Instead, an internal 803 interface of the :class:`RLock` class is used, which really unlocks it 804 even when it has been recursively acquired several times. Another internal 805 interface is then used to restore the recursion level when the lock is 806 reacquired. 807 808 The return value is ``True`` unless a given *timeout* expired, in which 809 case it is ``False``. 810 811 .. versionchanged:: 3.2 812 Previously, the method always returned ``None``. 813 814 .. method:: wait_for(predicate, timeout=None) 815 816 Wait until a condition evaluates to true. *predicate* should be a 817 callable which result will be interpreted as a boolean value. 818 A *timeout* may be provided giving the maximum time to wait. 819 820 This utility method may call :meth:`wait` repeatedly until the predicate 821 is satisfied, or until a timeout occurs. The return value is 822 the last return value of the predicate and will evaluate to 823 ``False`` if the method timed out. 824 825 Ignoring the timeout feature, calling this method is roughly equivalent to 826 writing:: 827 828 while not predicate(): 829 cv.wait() 830 831 Therefore, the same rules apply as with :meth:`wait`: The lock must be 832 held when called and is re-acquired on return. The predicate is evaluated 833 with the lock held. 834 835 .. versionadded:: 3.2 836 837 .. method:: notify(n=1) 838 839 By default, wake up one thread waiting on this condition, if any. If the 840 calling thread has not acquired the lock when this method is called, a 841 :exc:`RuntimeError` is raised. 842 843 This method wakes up at most *n* of the threads waiting for the condition 844 variable; it is a no-op if no threads are waiting. 845 846 The current implementation wakes up exactly *n* threads, if at least *n* 847 threads are waiting. However, it's not safe to rely on this behavior. 848 A future, optimized implementation may occasionally wake up more than 849 *n* threads. 850 851 Note: an awakened thread does not actually return from its :meth:`wait` 852 call until it can reacquire the lock. Since :meth:`notify` does not 853 release the lock, its caller should. 854 855 .. method:: notify_all() 856 857 Wake up all threads waiting on this condition. This method acts like 858 :meth:`notify`, but wakes up all waiting threads instead of one. If the 859 calling thread has not acquired the lock when this method is called, a 860 :exc:`RuntimeError` is raised. 861 862 The method ``notifyAll`` is a deprecated alias for this method. 863 864 865.. _semaphore-objects: 866 867Semaphore Objects 868----------------- 869 870This is one of the oldest synchronization primitives in the history of computer 871science, invented by the early Dutch computer scientist Edsger W. Dijkstra (he 872used the names ``P()`` and ``V()`` instead of :meth:`~Semaphore.acquire` and 873:meth:`~Semaphore.release`). 874 875A semaphore manages an internal counter which is decremented by each 876:meth:`~Semaphore.acquire` call and incremented by each :meth:`~Semaphore.release` 877call. The counter can never go below zero; when :meth:`~Semaphore.acquire` 878finds that it is zero, it blocks, waiting until some other thread calls 879:meth:`~Semaphore.release`. 880 881Semaphores also support the :ref:`context management protocol <with-locks>`. 882 883 884.. class:: Semaphore(value=1) 885 886 This class implements semaphore objects. A semaphore manages an atomic 887 counter representing the number of :meth:`release` calls minus the number of 888 :meth:`acquire` calls, plus an initial value. The :meth:`acquire` method 889 blocks if necessary until it can return without making the counter negative. 890 If not given, *value* defaults to 1. 891 892 The optional argument gives the initial *value* for the internal counter; it 893 defaults to ``1``. If the *value* given is less than 0, :exc:`ValueError` is 894 raised. 895 896 .. versionchanged:: 3.3 897 changed from a factory function to a class. 898 899 .. method:: acquire(blocking=True, timeout=None) 900 901 Acquire a semaphore. 902 903 When invoked without arguments: 904 905 * If the internal counter is larger than zero on entry, decrement it by 906 one and return ``True`` immediately. 907 * If the internal counter is zero on entry, block until awoken by a call to 908 :meth:`~Semaphore.release`. Once awoken (and the counter is greater 909 than 0), decrement the counter by 1 and return ``True``. Exactly one 910 thread will be awoken by each call to :meth:`~Semaphore.release`. The 911 order in which threads are awoken should not be relied on. 912 913 When invoked with *blocking* set to ``False``, do not block. If a call 914 without an argument would block, return ``False`` immediately; otherwise, do 915 the same thing as when called without arguments, and return ``True``. 916 917 When invoked with a *timeout* other than ``None``, it will block for at 918 most *timeout* seconds. If acquire does not complete successfully in 919 that interval, return ``False``. Return ``True`` otherwise. 920 921 .. versionchanged:: 3.2 922 The *timeout* parameter is new. 923 924 .. method:: release(n=1) 925 926 Release a semaphore, incrementing the internal counter by *n*. When it 927 was zero on entry and other threads are waiting for it to become larger 928 than zero again, wake up *n* of those threads. 929 930 .. versionchanged:: 3.9 931 Added the *n* parameter to release multiple waiting threads at once. 932 933 934.. class:: BoundedSemaphore(value=1) 935 936 Class implementing bounded semaphore objects. A bounded semaphore checks to 937 make sure its current value doesn't exceed its initial value. If it does, 938 :exc:`ValueError` is raised. In most situations semaphores are used to guard 939 resources with limited capacity. If the semaphore is released too many times 940 it's a sign of a bug. If not given, *value* defaults to 1. 941 942 .. versionchanged:: 3.3 943 changed from a factory function to a class. 944 945 946.. _semaphore-examples: 947 948:class:`Semaphore` Example 949^^^^^^^^^^^^^^^^^^^^^^^^^^ 950 951Semaphores are often used to guard resources with limited capacity, for example, 952a database server. In any situation where the size of the resource is fixed, 953you should use a bounded semaphore. Before spawning any worker threads, your 954main thread would initialize the semaphore:: 955 956 maxconnections = 5 957 # ... 958 pool_sema = BoundedSemaphore(value=maxconnections) 959 960Once spawned, worker threads call the semaphore's acquire and release methods 961when they need to connect to the server:: 962 963 with pool_sema: 964 conn = connectdb() 965 try: 966 # ... use connection ... 967 finally: 968 conn.close() 969 970The use of a bounded semaphore reduces the chance that a programming error which 971causes the semaphore to be released more than it's acquired will go undetected. 972 973 974.. _event-objects: 975 976Event Objects 977------------- 978 979This is one of the simplest mechanisms for communication between threads: one 980thread signals an event and other threads wait for it. 981 982An event object manages an internal flag that can be set to true with the 983:meth:`~Event.set` method and reset to false with the :meth:`~Event.clear` 984method. The :meth:`~Event.wait` method blocks until the flag is true. 985 986 987.. class:: Event() 988 989 Class implementing event objects. An event manages a flag that can be set to 990 true with the :meth:`~Event.set` method and reset to false with the 991 :meth:`clear` method. The :meth:`wait` method blocks until the flag is true. 992 The flag is initially false. 993 994 .. versionchanged:: 3.3 995 changed from a factory function to a class. 996 997 .. method:: is_set() 998 999 Return ``True`` if and only if the internal flag is true. 1000 1001 The method ``isSet`` is a deprecated alias for this method. 1002 1003 .. method:: set() 1004 1005 Set the internal flag to true. All threads waiting for it to become true 1006 are awakened. Threads that call :meth:`wait` once the flag is true will 1007 not block at all. 1008 1009 .. method:: clear() 1010 1011 Reset the internal flag to false. Subsequently, threads calling 1012 :meth:`wait` will block until :meth:`.set` is called to set the internal 1013 flag to true again. 1014 1015 .. method:: wait(timeout=None) 1016 1017 Block as long as the internal flag is false and the timeout, if given, 1018 has not expired. The return value represents the 1019 reason that this blocking method returned; ``True`` if returning because 1020 the internal flag is set to true, or ``False`` if a timeout is given and 1021 the internal flag did not become true within the given wait time. 1022 1023 When the timeout argument is present and not ``None``, it should be a 1024 floating-point number specifying a timeout for the operation in seconds, 1025 or fractions thereof. 1026 1027 .. versionchanged:: 3.1 1028 Previously, the method always returned ``None``. 1029 1030 1031.. _timer-objects: 1032 1033Timer Objects 1034------------- 1035 1036This class represents an action that should be run only after a certain amount 1037of time has passed --- a timer. :class:`Timer` is a subclass of :class:`Thread` 1038and as such also functions as an example of creating custom threads. 1039 1040Timers are started, as with threads, by calling their :meth:`Timer.start <Thread.start>` 1041method. The timer can be stopped (before its action has begun) by calling the 1042:meth:`~Timer.cancel` method. The interval the timer will wait before 1043executing its action may not be exactly the same as the interval specified by 1044the user. 1045 1046For example:: 1047 1048 def hello(): 1049 print("hello, world") 1050 1051 t = Timer(30.0, hello) 1052 t.start() # after 30 seconds, "hello, world" will be printed 1053 1054 1055.. class:: Timer(interval, function, args=None, kwargs=None) 1056 1057 Create a timer that will run *function* with arguments *args* and keyword 1058 arguments *kwargs*, after *interval* seconds have passed. 1059 If *args* is ``None`` (the default) then an empty list will be used. 1060 If *kwargs* is ``None`` (the default) then an empty dict will be used. 1061 1062 .. versionchanged:: 3.3 1063 changed from a factory function to a class. 1064 1065 .. method:: cancel() 1066 1067 Stop the timer, and cancel the execution of the timer's action. This will 1068 only work if the timer is still in its waiting stage. 1069 1070 1071Barrier Objects 1072--------------- 1073 1074.. versionadded:: 3.2 1075 1076This class provides a simple synchronization primitive for use by a fixed number 1077of threads that need to wait for each other. Each of the threads tries to pass 1078the barrier by calling the :meth:`~Barrier.wait` method and will block until 1079all of the threads have made their :meth:`~Barrier.wait` calls. At this point, 1080the threads are released simultaneously. 1081 1082The barrier can be reused any number of times for the same number of threads. 1083 1084As an example, here is a simple way to synchronize a client and server thread:: 1085 1086 b = Barrier(2, timeout=5) 1087 1088 def server(): 1089 start_server() 1090 b.wait() 1091 while True: 1092 connection = accept_connection() 1093 process_server_connection(connection) 1094 1095 def client(): 1096 b.wait() 1097 while True: 1098 connection = make_connection() 1099 process_client_connection(connection) 1100 1101 1102.. class:: Barrier(parties, action=None, timeout=None) 1103 1104 Create a barrier object for *parties* number of threads. An *action*, when 1105 provided, is a callable to be called by one of the threads when they are 1106 released. *timeout* is the default timeout value if none is specified for 1107 the :meth:`wait` method. 1108 1109 .. method:: wait(timeout=None) 1110 1111 Pass the barrier. When all the threads party to the barrier have called 1112 this function, they are all released simultaneously. If a *timeout* is 1113 provided, it is used in preference to any that was supplied to the class 1114 constructor. 1115 1116 The return value is an integer in the range 0 to *parties* -- 1, different 1117 for each thread. This can be used to select a thread to do some special 1118 housekeeping, e.g.:: 1119 1120 i = barrier.wait() 1121 if i == 0: 1122 # Only one thread needs to print this 1123 print("passed the barrier") 1124 1125 If an *action* was provided to the constructor, one of the threads will 1126 have called it prior to being released. Should this call raise an error, 1127 the barrier is put into the broken state. 1128 1129 If the call times out, the barrier is put into the broken state. 1130 1131 This method may raise a :class:`BrokenBarrierError` exception if the 1132 barrier is broken or reset while a thread is waiting. 1133 1134 .. method:: reset() 1135 1136 Return the barrier to the default, empty state. Any threads waiting on it 1137 will receive the :class:`BrokenBarrierError` exception. 1138 1139 Note that using this function may require some external 1140 synchronization if there are other threads whose state is unknown. If a 1141 barrier is broken it may be better to just leave it and create a new one. 1142 1143 .. method:: abort() 1144 1145 Put the barrier into a broken state. This causes any active or future 1146 calls to :meth:`wait` to fail with the :class:`BrokenBarrierError`. Use 1147 this for example if one of the threads needs to abort, to avoid deadlocking the 1148 application. 1149 1150 It may be preferable to simply create the barrier with a sensible 1151 *timeout* value to automatically guard against one of the threads going 1152 awry. 1153 1154 .. attribute:: parties 1155 1156 The number of threads required to pass the barrier. 1157 1158 .. attribute:: n_waiting 1159 1160 The number of threads currently waiting in the barrier. 1161 1162 .. attribute:: broken 1163 1164 A boolean that is ``True`` if the barrier is in the broken state. 1165 1166 1167.. exception:: BrokenBarrierError 1168 1169 This exception, a subclass of :exc:`RuntimeError`, is raised when the 1170 :class:`Barrier` object is reset or broken. 1171 1172 1173.. _with-locks: 1174 1175Using locks, conditions, and semaphores in the :keyword:`!with` statement 1176------------------------------------------------------------------------- 1177 1178All of the objects provided by this module that have ``acquire`` and 1179``release`` methods can be used as context managers for a :keyword:`with` 1180statement. The ``acquire`` method will be called when the block is 1181entered, and ``release`` will be called when the block is exited. Hence, 1182the following snippet:: 1183 1184 with some_lock: 1185 # do something... 1186 1187is equivalent to:: 1188 1189 some_lock.acquire() 1190 try: 1191 # do something... 1192 finally: 1193 some_lock.release() 1194 1195Currently, :class:`Lock`, :class:`RLock`, :class:`Condition`, 1196:class:`Semaphore`, and :class:`BoundedSemaphore` objects may be used as 1197:keyword:`with` statement context managers. 1198