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