threading.rst 38.2 KB
Newer Older
1 2
:mod:`threading` --- Thread-based parallelism
=============================================
3 4

.. module:: threading
5
   :synopsis: Thread-based parallelism.
6

7
**Source code:** :source:`Lib/threading.py`
8

9 10
--------------

11 12
This module constructs higher-level threading interfaces on top of the lower
level :mod:`_thread` module.  See also the :mod:`queue` module.
13 14

The :mod:`dummy_threading` module is provided for situations where
15
:mod:`threading` cannot be used because :mod:`_thread` is missing.
16

17 18
.. note::

19 20 21
   While they are not listed below, the ``camelCase`` names used for some
   methods and functions in this module in the Python 2.x series are still
   supported by this module.
22

23

24
This module defines the following functions:
25 26


27
.. function:: active_count()
28 29

   Return the number of :class:`Thread` objects currently alive.  The returned
Benjamin Peterson's avatar
Benjamin Peterson committed
30
   count is equal to the length of the list returned by :func:`.enumerate`.
31 32


33
.. function:: current_thread()
34 35 36 37 38 39 40

   Return the current :class:`Thread` object, corresponding to the caller's thread
   of control.  If the caller's thread of control was not created through the
   :mod:`threading` module, a dummy thread object with limited functionality is
   returned.


41 42 43 44 45 46 47 48 49 50 51
.. function:: get_ident()

   Return the 'thread identifier' of the current thread.  This is a nonzero
   integer.  Its value has no direct meaning; it is intended as a magic cookie
   to be used e.g. to index a dictionary of thread-specific data.  Thread
   identifiers may be recycled when a thread exits and another thread is
   created.

   .. versionadded:: 3.3


52 53
.. function:: enumerate()

54 55 56 57
   Return a list of all :class:`Thread` objects currently alive.  The list
   includes daemonic threads, dummy thread objects created by
   :func:`current_thread`, and the main thread.  It excludes terminated threads
   and threads that have not yet been started.
58 59


60 61 62 63 64 65 66 67 68
.. function:: main_thread()

   Return the main :class:`Thread` object.  In normal conditions, the
   main thread is the thread from which the Python interpreter was
   started.

   .. versionadded:: 3.4


69 70 71 72 73 74
.. function:: settrace(func)

   .. index:: single: trace function

   Set a trace function for all threads started from the :mod:`threading` module.
   The *func* will be passed to  :func:`sys.settrace` for each thread, before its
75
   :meth:`~Thread.run` method is called.
76 77 78 79 80 81 82 83


.. function:: setprofile(func)

   .. index:: single: profile function

   Set a profile function for all threads started from the :mod:`threading` module.
   The *func* will be passed to  :func:`sys.setprofile` for each thread, before its
84
   :meth:`~Thread.run` method is called.
85 86 87 88 89 90 91


.. function:: stack_size([size])

   Return the thread stack size used when creating new threads.  The optional
   *size* argument specifies the stack size to be used for subsequently created
   threads, and must be 0 (use platform or configured default) or a positive
92
   integer value of at least 32,768 (32 KiB). If changing the thread stack size is
93
   unsupported, a :exc:`RuntimeError` is raised.  If the specified stack size is
94
   invalid, a :exc:`ValueError` is raised and the stack size is unmodified.  32 KiB
95 96 97
   is currently the minimum supported stack size value to guarantee sufficient
   stack space for the interpreter itself.  Note that some platforms may have
   particular restrictions on values for the stack size, such as requiring a
98
   minimum stack size > 32 KiB or requiring allocation in multiples of the system
99
   memory page size - platform documentation should be referred to for more
100
   information (4 KiB pages are common; using multiples of 4096 for the stack size is
101 102 103 104
   the suggested approach in the absence of more specific information).
   Availability: Windows, systems with POSIX threads.


105 106 107 108 109 110
This module also defines the following constant:

.. data:: TIMEOUT_MAX

   The maximum value allowed for the *timeout* parameter of blocking functions
   (:meth:`Lock.acquire`, :meth:`RLock.acquire`, :meth:`Condition.wait`, etc.).
Georg Brandl's avatar
Georg Brandl committed
111
   Specifying a timeout greater than this value will raise an
112 113
   :exc:`OverflowError`.

114
   .. versionadded:: 3.2
115

116

117 118
This module defines a number of classes, which are detailed in the sections
below.
119 120 121 122 123 124 125 126 127 128 129 130

The design of this module is loosely based on Java's threading model. However,
where Java makes locks and condition variables basic behavior of every object,
they are separate objects in Python.  Python's :class:`Thread` class supports a
subset of the behavior of Java's Thread class; currently, there are no
priorities, no thread groups, and threads cannot be destroyed, stopped,
suspended, resumed, or interrupted.  The static methods of Java's Thread class,
when implemented, are mapped to module-level functions.

All of the methods described below are executed atomically.


131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151
Thread-Local Data
-----------------

Thread-local data is data whose values are thread specific.  To manage
thread-local data, just create an instance of :class:`local` (or a
subclass) and store attributes on it::

  mydata = threading.local()
  mydata.x = 1

The instance's values will be different for separate threads.


.. class:: local()

   A class that represents thread-local data.

   For more details and extensive examples, see the documentation string of the
   :mod:`_threading_local` module.


152 153 154 155 156
.. _thread-objects:

Thread Objects
--------------

157 158 159 160 161 162
The :class:`Thread` class represents an activity that is run in a separate
thread of control.  There are two ways to specify the activity: by passing a
callable object to the constructor, or by overriding the :meth:`~Thread.run`
method in a subclass.  No other methods (except for the constructor) should be
overridden in a subclass.  In other words, *only*  override the
:meth:`~Thread.__init__` and :meth:`~Thread.run` methods of this class.
163 164

Once a thread object is created, its activity must be started by calling the
165 166
thread's :meth:`~Thread.start` method.  This invokes the :meth:`~Thread.run`
method in a separate thread of control.
167 168

Once the thread's activity is started, the thread is considered 'alive'. It
169 170 171
stops being alive when its :meth:`~Thread.run` method terminates -- either
normally, or by raising an unhandled exception.  The :meth:`~Thread.is_alive`
method tests whether the thread is alive.
172

173 174 175
Other threads can call a thread's :meth:`~Thread.join` method.  This blocks
the calling thread until the thread whose :meth:`~Thread.join` method is
called is terminated.
176 177

A thread has a name.  The name can be passed to the constructor, and read or
178
changed through the :attr:`~Thread.name` attribute.
179 180 181 182

A thread can be flagged as a "daemon thread".  The significance of this flag is
that the entire Python program exits when only daemon threads are left.  The
initial value is inherited from the creating thread.  The flag can be set
Antoine Pitrou's avatar
Antoine Pitrou committed
183 184
through the :attr:`~Thread.daemon` property or the *daemon* constructor
argument.
185

186 187 188 189 190 191
.. note::
   Daemon threads are abruptly stopped at shutdown.  Their resources (such
   as open files, database transactions, etc.) may not be released properly.
   If you want your threads to stop gracefully, make them non-daemonic and
   use a suitable signalling mechanism such as an :class:`Event`.

192 193 194 195 196 197 198
There is a "main thread" object; this corresponds to the initial thread of
control in the Python program.  It is not a daemon thread.

There is the possibility that "dummy thread objects" are created. These are
thread objects corresponding to "alien threads", which are threads of control
started outside the threading module, such as directly from C code.  Dummy
thread objects have limited functionality; they are always considered alive and
199 200
daemonic, and cannot be :meth:`~Thread.join`\ ed.  They are never deleted,
since it is impossible to detect the termination of alien threads.
201 202


Ezio Melotti's avatar
Ezio Melotti committed
203 204
.. class:: Thread(group=None, target=None, name=None, args=(), kwargs={}, *, \
                  daemon=None)
205

206 207
   This constructor should always be called with keyword arguments.  Arguments
   are:
208 209 210 211 212 213 214

   *group* should be ``None``; reserved for future extension when a
   :class:`ThreadGroup` class is implemented.

   *target* is the callable object to be invoked by the :meth:`run` method.
   Defaults to ``None``, meaning nothing is called.

215 216
   *name* is the thread name.  By default, a unique name is constructed of the
   form "Thread-*N*" where *N* is a small decimal number.
217 218 219 220 221 222

   *args* is the argument tuple for the target invocation.  Defaults to ``()``.

   *kwargs* is a dictionary of keyword arguments for the target invocation.
   Defaults to ``{}``.

223 224 225 226
   If not ``None``, *daemon* explicitly sets whether the thread is daemonic.
   If ``None`` (the default), the daemonic property is inherited from the
   current thread.

227 228 229
   If the subclass overrides the constructor, it must make sure to invoke the
   base class constructor (``Thread.__init__()``) before doing anything else to
   the thread.
230

231 232 233
   .. versionchanged:: 3.3
      Added the *daemon* argument.

234
   .. method:: start()
235

236
      Start the thread's activity.
237

238
      It must be called at most once per thread object.  It arranges for the
239 240
      object's :meth:`~Thread.run` method to be invoked in a separate thread
      of control.
241

242
      This method will raise a :exc:`RuntimeError` if called more than once
243
      on the same thread object.
244

245
   .. method:: run()
246

247
      Method representing the thread's activity.
248

249 250 251 252
      You may override this method in a subclass.  The standard :meth:`run`
      method invokes the callable object passed to the object's constructor as
      the *target* argument, if any, with sequential and keyword arguments taken
      from the *args* and *kwargs* arguments, respectively.
253

254
   .. method:: join(timeout=None)
255

256 257 258 259
      Wait until the thread terminates. This blocks the calling thread until
      the thread whose :meth:`~Thread.join` method is called terminates -- either
      normally or through an unhandled exception --, or until the optional
      timeout occurs.
260

261 262
      When the *timeout* argument is present and not ``None``, it should be a
      floating point number specifying a timeout for the operation in seconds
263 264 265 266
      (or fractions thereof). As :meth:`~Thread.join` always returns ``None``,
      you must call :meth:`~Thread.is_alive` after :meth:`~Thread.join` to
      decide whether a timeout happened -- if the thread is still alive, the
      :meth:`~Thread.join` call timed out.
267

268 269
      When the *timeout* argument is not present or ``None``, the operation will
      block until the thread terminates.
270

271
      A thread can be :meth:`~Thread.join`\ ed many times.
272

273 274 275 276
      :meth:`~Thread.join` raises a :exc:`RuntimeError` if an attempt is made
      to join the current thread as that would cause a deadlock. It is also
      an error to :meth:`~Thread.join` a thread before it has been started
      and attempts to do so raise the same exception.
277

278
   .. attribute:: name
279

280 281 282
      A string used for identification purposes only. It has no semantics.
      Multiple threads may be given the same name.  The initial name is set by
      the constructor.
283

284 285
   .. method:: getName()
               setName()
286

287 288
      Old getter/setter API for :attr:`~Thread.name`; use it directly as a
      property instead.
289

290
   .. attribute:: ident
291

292 293
      The 'thread identifier' of this thread or ``None`` if the thread has not
      been started.  This is a nonzero integer.  See the
294
      :func:`_thread.get_ident()` function.  Thread identifiers may be recycled
295 296
      when a thread exits and another thread is created.  The identifier is
      available even after the thread has exited.
297

298
   .. method:: is_alive()
299

300
      Return whether the thread is alive.
301

302 303 304
      This method returns ``True`` just before the :meth:`~Thread.run` method
      starts until just after the :meth:`~Thread.run` method terminates.  The
      module function :func:`.enumerate` returns a list of all alive threads.
305

306
   .. attribute:: daemon
307

308
      A boolean value indicating whether this thread is a daemon thread (True)
309
      or not (False).  This must be set before :meth:`~Thread.start` is called,
310 311
      otherwise :exc:`RuntimeError` is raised.  Its initial value is inherited
      from the creating thread; the main thread is not a daemon thread and
312 313
      therefore all threads created in the main thread default to
      :attr:`~Thread.daemon` = ``False``.
314

315
      The entire Python program exits when no alive non-daemon threads are left.
316

317 318
   .. method:: isDaemon()
               setDaemon()
319

320 321
      Old getter/setter API for :attr:`~Thread.daemon`; use it directly as a
      property instead.
322 323


324 325
.. impl-detail::

Ezio Melotti's avatar
Ezio Melotti committed
326
   In CPython, due to the :term:`Global Interpreter Lock`, only one thread
327 328
   can execute Python code at once (even though certain performance-oriented
   libraries might overcome this limitation).
Ezio Melotti's avatar
Ezio Melotti committed
329
   If you want your application to make better use of the computational
330 331 332 333 334 335
   resources of multi-core machines, you are advised to use
   :mod:`multiprocessing` or :class:`concurrent.futures.ProcessPoolExecutor`.
   However, threading is still an appropriate model if you want to run
   multiple I/O-bound tasks simultaneously.


336 337 338 339 340 341 342
.. _lock-objects:

Lock Objects
------------

A primitive lock is a synchronization primitive that is not owned by a
particular thread when locked.  In Python, it is currently the lowest level
343
synchronization primitive available, implemented directly by the :mod:`_thread`
344 345 346
extension module.

A primitive lock is in one of two states, "locked" or "unlocked". It is created
347 348 349 350 351 352 353 354 355 356
in the unlocked state.  It has two basic methods, :meth:`~Lock.acquire` and
:meth:`~Lock.release`.  When the state is unlocked, :meth:`~Lock.acquire`
changes the state to locked and returns immediately.  When the state is locked,
:meth:`~Lock.acquire` blocks until a call to :meth:`~Lock.release` in another
thread changes it to unlocked, then the :meth:`~Lock.acquire` call resets it
to locked and returns.  The :meth:`~Lock.release` method should only be
called in the locked state; it changes the state to unlocked and returns
immediately. If an attempt is made to release an unlocked lock, a
:exc:`RuntimeError` will be raised.

357
Locks also support the :ref:`context management protocol <with-locks>`.
358

359 360 361 362
When more than one thread is blocked in :meth:`~Lock.acquire` waiting for the
state to turn to unlocked, only one thread proceeds when a :meth:`~Lock.release`
call resets the state to unlocked; which one of the waiting threads proceeds
is not defined, and may vary across implementations.
363 364 365 366

All methods are executed atomically.


367
.. class:: Lock()
368

369 370 371
   The class implementing primitive lock objects.  Once a thread has acquired a
   lock, subsequent attempts to acquire it block, until it is released; any
   thread may release it.
372

373 374
   .. versionchanged:: 3.3
      Changed from a factory function to a class.
375 376


377
   .. method:: acquire(blocking=True, timeout=-1)
378

379
      Acquire a lock, blocking or non-blocking.
380

381 382
      When invoked with the *blocking* argument set to ``True`` (the default),
      block until the lock is unlocked, then set it to locked and return ``True``.
383

384 385 386
      When invoked with the *blocking* argument set to ``False``, do not block.
      If a call with *blocking* set to ``True`` would block, return ``False``
      immediately; otherwise, set the lock to locked and return ``True``.
387

388 389
      When invoked with the floating-point *timeout* argument set to a positive
      value, block for at most the number of seconds specified by *timeout*
390
      and as long as the lock cannot be acquired.  A *timeout* argument of ``-1``
391 392
      specifies an unbounded wait.  It is forbidden to specify a *timeout*
      when *blocking* is false.
393

394 395
      The return value is ``True`` if the lock is acquired successfully,
      ``False`` if not (for example if the *timeout* expired).
396

397 398
      .. versionchanged:: 3.2
         The *timeout* parameter is new.
399

400 401 402 403 404 405 406 407 408 409 410 411
      .. versionchanged:: 3.2
         Lock acquires can now be interrupted by signals on POSIX.


   .. method:: release()

      Release a lock.  This can be called from any thread, not only the thread
      which has acquired the lock.

      When the lock is locked, reset it to unlocked, and return.  If any other threads
      are blocked waiting for the lock to become unlocked, allow exactly one of them
      to proceed.
412

413
      When invoked on an unlocked lock, a :exc:`RuntimeError` is raised.
414

415
      There is no return value.
416 417 418 419 420 421 422 423 424 425 426 427 428


.. _rlock-objects:

RLock Objects
-------------

A reentrant lock is a synchronization primitive that may be acquired multiple
times by the same thread.  Internally, it uses the concepts of "owning thread"
and "recursion level" in addition to the locked/unlocked state used by primitive
locks.  In the locked state, some thread owns the lock; in the unlocked state,
no thread owns it.

429 430 431 432 433 434
To lock the lock, a thread calls its :meth:`~RLock.acquire` method; this
returns once the thread owns the lock.  To unlock the lock, a thread calls
its :meth:`~Lock.release` method. :meth:`~Lock.acquire`/:meth:`~Lock.release`
call pairs may be nested; only the final :meth:`~Lock.release` (the
:meth:`~Lock.release` of the outermost pair) resets the lock to unlocked and
allows another thread blocked in :meth:`~Lock.acquire` to proceed.
435

436
Reentrant locks also support the :ref:`context management protocol <with-locks>`.
437 438


439
.. class:: RLock()
440

441 442 443 444
   This class implements reentrant lock objects.  A reentrant lock must be
   released by the thread that acquired it.  Once a thread has acquired a
   reentrant lock, the same thread may acquire it again without blocking; the
   thread must release it once for each time it has acquired it.
445

446 447 448
   Note that ``RLock`` is actually a factory function which returns an instance
   of the most efficient version of the concrete RLock class that is supported
   by the platform.
449 450


451
   .. method:: acquire(blocking=True, timeout=-1)
452

453
      Acquire a lock, blocking or non-blocking.
454

455 456 457 458 459 460 461
      When invoked without arguments: if this thread already owns the lock, increment
      the recursion level by one, and return immediately.  Otherwise, if another
      thread owns the lock, block until the lock is unlocked.  Once the lock is
      unlocked (not owned by any thread), then grab ownership, set the recursion level
      to one, and return.  If more than one thread is blocked waiting until the lock
      is unlocked, only one at a time will be able to grab ownership of the lock.
      There is no return value in this case.
462

463 464
      When invoked with the *blocking* argument set to true, do the same thing as when
      called without arguments, and return true.
465

466 467 468
      When invoked with the *blocking* argument set to false, do not block.  If a call
      without an argument would block, return false immediately; otherwise, do the
      same thing as when called without arguments, and return true.
469

470 471 472 473
      When invoked with the floating-point *timeout* argument set to a positive
      value, block for at most the number of seconds specified by *timeout*
      and as long as the lock cannot be acquired.  Return true if the lock has
      been acquired, false if the timeout has elapsed.
474

475 476
      .. versionchanged:: 3.2
         The *timeout* parameter is new.
477

478 479 480 481 482 483 484 485 486 487 488 489 490 491

   .. method:: release()

      Release a lock, decrementing the recursion level.  If after the decrement it is
      zero, reset the lock to unlocked (not owned by any thread), and if any other
      threads are blocked waiting for the lock to become unlocked, allow exactly one
      of them to proceed.  If after the decrement the recursion level is still
      nonzero, the lock remains locked and owned by the calling thread.

      Only call this method when the calling thread owns the lock. A
      :exc:`RuntimeError` is raised if this method is called when the lock is
      unlocked.

      There is no return value.
492 493 494 495 496 497 498 499


.. _condition-objects:

Condition Objects
-----------------

A condition variable is always associated with some kind of lock; this can be
500 501 502 503
passed in or one will be created by default.  Passing one in is useful when
several condition variables must share the same lock.  The lock is part of
the condition object: you don't have to track it separately.

504
A condition variable obeys the :ref:`context management protocol <with-locks>`:
505 506 507 508
using the ``with`` statement acquires the associated lock for the duration of
the enclosed block.  The :meth:`~Condition.acquire` and
:meth:`~Condition.release` methods also call the corresponding methods of
the associated lock.
509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526

Other methods must be called with the associated lock held.  The
:meth:`~Condition.wait` method releases the lock, and then blocks until
another thread awakens it by calling :meth:`~Condition.notify` or
:meth:`~Condition.notify_all`.  Once awakened, :meth:`~Condition.wait`
re-acquires the lock and returns.  It is also possible to specify a timeout.

The :meth:`~Condition.notify` method wakes up one of the threads waiting for
the condition variable, if any are waiting.  The :meth:`~Condition.notify_all`
method wakes up all threads waiting for the condition variable.

Note: the :meth:`~Condition.notify` and :meth:`~Condition.notify_all` methods
don't release the lock; this means that the thread or threads awakened will
not return from their :meth:`~Condition.wait` call immediately, but only when
the thread that called :meth:`~Condition.notify` or :meth:`~Condition.notify_all`
finally relinquishes ownership of the lock.

The typical programming style using condition variables uses the lock to
527
synchronize access to some shared state; threads that are interested in a
528 529 530 531 532 533
particular change of state call :meth:`~Condition.wait` repeatedly until they
see the desired state, while threads that modify the state call
:meth:`~Condition.notify` or :meth:`~Condition.notify_all` when they change
the state in such a way that it could possibly be a desired state for one
of the waiters.  For example, the following code is a generic
producer-consumer situation with unlimited buffer capacity::
534 535

   # Consume one item
536 537 538 539
   with cv:
       while not an_item_is_available():
           cv.wait()
       get_an_available_item()
540 541

   # Produce one item
542 543
   with cv:
       make_an_item_available()
544
       cv.notify()
545 546 547

The ``while`` loop checking for the application's condition is necessary
because :meth:`~Condition.wait` can return after an arbitrary long time,
548 549 550 551
and the condition which prompted the :meth:`~Condition.notify` call may
no longer hold true.  This is inherent to multi-threaded programming.  The
:meth:`~Condition.wait_for` method can be used to automate the condition
checking, and eases the computation of timeouts::
552

553 554 555 556
   # Consume an item
   with cv:
       cv.wait_for(an_item_is_available)
       get_an_available_item()
557

558 559 560 561
To choose between :meth:`~Condition.notify` and :meth:`~Condition.notify_all`,
consider whether one state change can be interesting for only one or several
waiting threads.  E.g. in a typical producer-consumer situation, adding one
item to the buffer only needs to wake up one consumer thread.
Kristján Valur Jónsson's avatar
Kristján Valur Jónsson committed
562

563

564
.. class:: Condition(lock=None)
565

566 567 568
   This class implements condition variable objects.  A condition variable
   allows one or more threads to wait until they are notified by another thread.

569 570 571
   If the *lock* argument is given and not ``None``, it must be a :class:`Lock`
   or :class:`RLock` object, and it is used as the underlying lock.  Otherwise,
   a new :class:`RLock` object is created and used as the underlying lock.
572

573 574 575
   .. versionchanged:: 3.3
      changed from a factory function to a class.

576
   .. method:: acquire(*args)
577

578 579
      Acquire the underlying lock. This method calls the corresponding method on
      the underlying lock; the return value is whatever that method returns.
580

581
   .. method:: release()
582

583 584
      Release the underlying lock. This method calls the corresponding method on
      the underlying lock; there is no return value.
585

586
   .. method:: wait(timeout=None)
587

588 589 590
      Wait until notified or until a timeout occurs. If the calling thread has
      not acquired the lock when this method is called, a :exc:`RuntimeError` is
      raised.
591

592 593 594 595
      This method releases the underlying lock, and then blocks until it is
      awakened by a :meth:`notify` or :meth:`notify_all` call for the same
      condition variable in another thread, or until the optional timeout
      occurs.  Once awakened or timed out, it re-acquires the lock and returns.
596

597 598 599
      When the *timeout* argument is present and not ``None``, it should be a
      floating point number specifying a timeout for the operation in seconds
      (or fractions thereof).
600

601 602 603 604 605 606 607
      When the underlying lock is an :class:`RLock`, it is not released using
      its :meth:`release` method, since this may not actually unlock the lock
      when it was acquired multiple times recursively.  Instead, an internal
      interface of the :class:`RLock` class is used, which really unlocks it
      even when it has been recursively acquired several times. Another internal
      interface is then used to restore the recursion level when the lock is
      reacquired.
608

609 610 611 612 613 614
      The return value is ``True`` unless a given *timeout* expired, in which
      case it is ``False``.

      .. versionchanged:: 3.2
         Previously, the method always returned ``None``.

Kristján Valur Jónsson's avatar
Kristján Valur Jónsson committed
615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637
   .. method:: wait_for(predicate, timeout=None)

      Wait until a condition evaluates to True.  *predicate* should be a
      callable which result will be interpreted as a boolean value.
      A *timeout* may be provided giving the maximum time to wait.

      This utility method may call :meth:`wait` repeatedly until the predicate
      is satisfied, or until a timeout occurs. The return value is
      the last return value of the predicate and will evaluate to
      ``False`` if the method timed out.

      Ignoring the timeout feature, calling this method is roughly equivalent to
      writing::

        while not predicate():
            cv.wait()

      Therefore, the same rules apply as with :meth:`wait`: The lock must be
      held when called and is re-aquired on return.  The predicate is evaluated
      with the lock held.

      .. versionadded:: 3.2

638
   .. method:: notify(n=1)
639

640 641
      By default, wake up one thread waiting on this condition, if any.  If the
      calling thread has not acquired the lock when this method is called, a
642
      :exc:`RuntimeError` is raised.
643

644 645
      This method wakes up at most *n* of the threads waiting for the condition
      variable; it is a no-op if no threads are waiting.
646

647 648 649 650
      The current implementation wakes up exactly *n* threads, if at least *n*
      threads are waiting.  However, it's not safe to rely on this behavior.
      A future, optimized implementation may occasionally wake up more than
      *n* threads.
651

652
      Note: an awakened thread does not actually return from its :meth:`wait`
653 654
      call until it can reacquire the lock.  Since :meth:`notify` does not
      release the lock, its caller should.
655

656
   .. method:: notify_all()
657

658 659 660 661
      Wake up all threads waiting on this condition.  This method acts like
      :meth:`notify`, but wakes up all waiting threads instead of one. If the
      calling thread has not acquired the lock when this method is called, a
      :exc:`RuntimeError` is raised.
662 663 664 665 666 667 668 669 670


.. _semaphore-objects:

Semaphore Objects
-----------------

This is one of the oldest synchronization primitives in the history of computer
science, invented by the early Dutch computer scientist Edsger W. Dijkstra (he
671 672
used the names ``P()`` and ``V()`` instead of :meth:`~Semaphore.acquire` and
:meth:`~Semaphore.release`).
673 674

A semaphore manages an internal counter which is decremented by each
675 676 677 678
:meth:`~Semaphore.acquire` call and incremented by each :meth:`~Semaphore.release`
call.  The counter can never go below zero; when :meth:`~Semaphore.acquire`
finds that it is zero, it blocks, waiting until some other thread calls
:meth:`~Semaphore.release`.
679

680
Semaphores also support the :ref:`context management protocol <with-locks>`.
681 682


683
.. class:: Semaphore(value=1)
684

685 686 687 688 689 690
   This class implements semaphore objects.  A semaphore manages a counter
   representing the number of :meth:`release` calls minus the number of
   :meth:`acquire` calls, plus an initial value.  The :meth:`acquire` method
   blocks if necessary until it can return without making the counter negative.
   If not given, *value* defaults to 1.

691 692 693 694
   The optional argument gives the initial *value* for the internal counter; it
   defaults to ``1``. If the *value* given is less than 0, :exc:`ValueError` is
   raised.

695 696 697
   .. versionchanged:: 3.3
      changed from a factory function to a class.

698
   .. method:: acquire(blocking=True, timeout=None)
699

700
      Acquire a semaphore.
701

702 703 704
      When invoked without arguments: if the internal counter is larger than
      zero on entry, decrement it by one and return immediately.  If it is zero
      on entry, block, waiting until some other thread has called
705 706 707 708 709 710
      :meth:`~Semaphore.release` to make it larger than zero.  This is done
      with proper interlocking so that if multiple :meth:`acquire` calls are
      blocked, :meth:`~Semaphore.release` will wake exactly one of them up.
      The implementation may pick one at random, so the order in which
      blocked threads are awakened should not be relied on.  Returns
      true (or blocks indefinitely).
711

712
      When invoked with *blocking* set to false, do not block.  If a call
713 714 715 716 717 718 719 720 721
      without an argument would block, return false immediately; otherwise,
      do the same thing as when called without arguments, and return true.

      When invoked with a *timeout* other than None, it will block for at
      most *timeout* seconds.  If acquire does not complete successfully in
      that interval, return false.  Return true otherwise.

      .. versionchanged:: 3.2
         The *timeout* parameter is new.
722

723
   .. method:: release()
724

725 726 727
      Release a semaphore, incrementing the internal counter by one.  When it
      was zero on entry and another thread is waiting for it to become larger
      than zero again, wake up that thread.
728 729


730 731 732 733 734 735 736 737 738 739 740 741
.. class:: BoundedSemaphore(value=1)

   Class implementing bounded semaphore objects.  A bounded semaphore checks to
   make sure its current value doesn't exceed its initial value.  If it does,
   :exc:`ValueError` is raised. In most situations semaphores are used to guard
   resources with limited capacity.  If the semaphore is released too many times
   it's a sign of a bug.  If not given, *value* defaults to 1.

   .. versionchanged:: 3.3
      changed from a factory function to a class.


742 743 744 745 746 747
.. _semaphore-examples:

:class:`Semaphore` Example
^^^^^^^^^^^^^^^^^^^^^^^^^^

Semaphores are often used to guard resources with limited capacity, for example,
Georg Brandl's avatar
Georg Brandl committed
748 749 750
a database server.  In any situation where the size of the resource is fixed,
you should use a bounded semaphore.  Before spawning any worker threads, your
main thread would initialize the semaphore::
751 752

   maxconnections = 5
753
   # ...
754 755 756 757 758
   pool_sema = BoundedSemaphore(value=maxconnections)

Once spawned, worker threads call the semaphore's acquire and release methods
when they need to connect to the server::

759 760 761
   with pool_sema:
       conn = connectdb()
       try:
762
           # ... use connection ...
763 764
       finally:
           conn.close()
765 766 767 768 769 770 771 772 773 774 775 776 777 778

The use of a bounded semaphore reduces the chance that a programming error which
causes the semaphore to be released more than it's acquired will go undetected.


.. _event-objects:

Event Objects
-------------

This is one of the simplest mechanisms for communication between threads: one
thread signals an event and other threads wait for it.

An event object manages an internal flag that can be set to true with the
779 780
:meth:`~Event.set` method and reset to false with the :meth:`~Event.clear`
method.  The :meth:`~Event.wait` method blocks until the flag is true.
781 782 783 784


.. class:: Event()

785 786 787 788 789 790 791
   Class implementing event objects.  An event manages a flag that can be set to
   true with the :meth:`~Event.set` method and reset to false with the
   :meth:`clear` method.  The :meth:`wait` method blocks until the flag is true.
   The flag is initially false.

   .. versionchanged:: 3.3
      changed from a factory function to a class.
792

793
   .. method:: is_set()
794

795
      Return true if and only if the internal flag is true.
796

797
   .. method:: set()
798

799 800 801
      Set the internal flag to true. All threads waiting for it to become true
      are awakened. Threads that call :meth:`wait` once the flag is true will
      not block at all.
802

803
   .. method:: clear()
804

805
      Reset the internal flag to false. Subsequently, threads calling
806
      :meth:`wait` will block until :meth:`.set` is called to set the internal
807
      flag to true again.
808

809
   .. method:: wait(timeout=None)
810

811 812
      Block until the internal flag is true.  If the internal flag is true on
      entry, return immediately.  Otherwise, block until another thread calls
813
      :meth:`.set` to set the flag to true, or until the optional timeout occurs.
814

815 816 817
      When the timeout argument is present and not ``None``, it should be a
      floating point number specifying a timeout for the operation in seconds
      (or fractions thereof).
818

819 820 821 822
      This method returns true if and only if the internal flag has been set to
      true, either before the wait call or after the wait starts, so it will
      always return ``True`` except if a timeout is given and the operation
      times out.
823

824 825
      .. versionchanged:: 3.1
         Previously, the method always returned ``None``.
Benjamin Peterson's avatar
Benjamin Peterson committed
826

827 828 829 830 831 832 833 834 835 836

.. _timer-objects:

Timer Objects
-------------

This class represents an action that should be run only after a certain amount
of time has passed --- a timer.  :class:`Timer` is a subclass of :class:`Thread`
and as such also functions as an example of creating custom threads.

837 838 839 840 841
Timers are started, as with threads, by calling their :meth:`~Timer.start`
method.  The timer can be stopped (before its action has begun) by calling the
:meth:`~Timer.cancel` method.  The interval the timer will wait before
executing its action may not be exactly the same as the interval specified by
the user.
842 843 844 845

For example::

   def hello():
846
       print("hello, world")
847 848 849 850 851

   t = Timer(30.0, hello)
   t.start() # after 30 seconds, "hello, world" will be printed


852
.. class:: Timer(interval, function, args=None, kwargs=None)
853 854 855

   Create a timer that will run *function* with arguments *args* and  keyword
   arguments *kwargs*, after *interval* seconds have passed.
856 857
   If *args* is None (the default) then an empty list will be used.
   If *kwargs* is None (the default) then an empty dict will be used.
858

859 860 861
   .. versionchanged:: 3.3
      changed from a factory function to a class.

862
   .. method:: cancel()
863

864 865
      Stop the timer, and cancel the execution of the timer's action.  This will
      only work if the timer is still in its waiting stage.
866 867


Kristján Valur Jónsson's avatar
Kristján Valur Jónsson committed
868 869 870
Barrier Objects
---------------

Georg Brandl's avatar
Georg Brandl committed
871 872 873 874
.. versionadded:: 3.2

This class provides a simple synchronization primitive for use by a fixed number
of threads that need to wait for each other.  Each of the threads tries to pass
875 876
the barrier by calling the :meth:`~Barrier.wait` method and will block until
all of the threads have made the call.  At this points, the threads are released
877
simultaneously.
Kristján Valur Jónsson's avatar
Kristján Valur Jónsson committed
878 879 880 881 882 883

The barrier can be reused any number of times for the same number of threads.

As an example, here is a simple way to synchronize a client and server thread::

   b = Barrier(2, timeout=5)
Georg Brandl's avatar
Georg Brandl committed
884 885

   def server():
Kristján Valur Jónsson's avatar
Kristján Valur Jónsson committed
886 887 888 889 890 891
       start_server()
       b.wait()
       while True:
           connection = accept_connection()
           process_server_connection(connection)

Georg Brandl's avatar
Georg Brandl committed
892
   def client():
Kristján Valur Jónsson's avatar
Kristján Valur Jónsson committed
893 894
       b.wait()
       while True:
Georg Brandl's avatar
Georg Brandl committed
895 896 897
           connection = make_connection()
           process_client_connection(connection)

Kristján Valur Jónsson's avatar
Kristján Valur Jónsson committed
898 899 900

.. class:: Barrier(parties, action=None, timeout=None)

Georg Brandl's avatar
Georg Brandl committed
901 902 903 904
   Create a barrier object for *parties* number of threads.  An *action*, when
   provided, is a callable to be called by one of the threads when they are
   released.  *timeout* is the default timeout value if none is specified for
   the :meth:`wait` method.
Kristján Valur Jónsson's avatar
Kristján Valur Jónsson committed
905 906 907 908

   .. method:: wait(timeout=None)

      Pass the barrier.  When all the threads party to the barrier have called
Georg Brandl's avatar
Georg Brandl committed
909
      this function, they are all released simultaneously.  If a *timeout* is
Ezio Melotti's avatar
Ezio Melotti committed
910
      provided, it is used in preference to any that was supplied to the class
Georg Brandl's avatar
Georg Brandl committed
911
      constructor.
Kristján Valur Jónsson's avatar
Kristján Valur Jónsson committed
912

Georg Brandl's avatar
Georg Brandl committed
913
      The return value is an integer in the range 0 to *parties* -- 1, different
914
      for each thread.  This can be used to select a thread to do some special
Georg Brandl's avatar
Georg Brandl committed
915
      housekeeping, e.g.::
Kristján Valur Jónsson's avatar
Kristján Valur Jónsson committed
916 917 918

         i = barrier.wait()
         if i == 0:
Georg Brandl's avatar
Georg Brandl committed
919 920
             # Only one thread needs to print this
             print("passed the barrier")
Kristján Valur Jónsson's avatar
Kristján Valur Jónsson committed
921

Georg Brandl's avatar
Georg Brandl committed
922 923 924
      If an *action* was provided to the constructor, one of the threads will
      have called it prior to being released.  Should this call raise an error,
      the barrier is put into the broken state.
Kristján Valur Jónsson's avatar
Kristján Valur Jónsson committed
925 926 927 928

      If the call times out, the barrier is put into the broken state.

      This method may raise a :class:`BrokenBarrierError` exception if the
Georg Brandl's avatar
Georg Brandl committed
929
      barrier is broken or reset while a thread is waiting.
Kristján Valur Jónsson's avatar
Kristján Valur Jónsson committed
930 931 932

   .. method:: reset()

Georg Brandl's avatar
Georg Brandl committed
933 934
      Return the barrier to the default, empty state.  Any threads waiting on it
      will receive the :class:`BrokenBarrierError` exception.
Kristján Valur Jónsson's avatar
Kristján Valur Jónsson committed
935 936

      Note that using this function may can require some external
Georg Brandl's avatar
Georg Brandl committed
937 938
      synchronization if there are other threads whose state is unknown.  If a
      barrier is broken it may be better to just leave it and create a new one.
Kristján Valur Jónsson's avatar
Kristján Valur Jónsson committed
939 940 941 942

   .. method:: abort()

      Put the barrier into a broken state.  This causes any active or future
Georg Brandl's avatar
Georg Brandl committed
943 944 945
      calls to :meth:`wait` to fail with the :class:`BrokenBarrierError`.  Use
      this for example if one of the needs to abort, to avoid deadlocking the
      application.
Kristján Valur Jónsson's avatar
Kristján Valur Jónsson committed
946 947

      It may be preferable to simply create the barrier with a sensible
Georg Brandl's avatar
Georg Brandl committed
948 949
      *timeout* value to automatically guard against one of the threads going
      awry.
Kristján Valur Jónsson's avatar
Kristján Valur Jónsson committed
950 951 952 953 954 955 956 957 958 959 960 961 962 963

   .. attribute:: parties

      The number of threads required to pass the barrier.

   .. attribute:: n_waiting

      The number of threads currently waiting in the barrier.

   .. attribute:: broken

      A boolean that is ``True`` if the barrier is in the broken state.


Georg Brandl's avatar
Georg Brandl committed
964
.. exception:: BrokenBarrierError
Kristján Valur Jónsson's avatar
Kristján Valur Jónsson committed
965

Georg Brandl's avatar
Georg Brandl committed
966 967
   This exception, a subclass of :exc:`RuntimeError`, is raised when the
   :class:`Barrier` object is reset or broken.
Kristján Valur Jónsson's avatar
Kristján Valur Jónsson committed
968 969


970 971 972 973 974 975 976
.. _with-locks:

Using locks, conditions, and semaphores in the :keyword:`with` statement
------------------------------------------------------------------------

All of the objects provided by this module that have :meth:`acquire` and
:meth:`release` methods can be used as context managers for a :keyword:`with`
977 978 979
statement.  The :meth:`acquire` method will be called when the block is
entered, and :meth:`release` will be called when the block is exited.  Hence,
the following snippet::
980

981 982
   with some_lock:
       # do something...
983

984
is equivalent to::
985

986 987 988 989 990
   some_lock.acquire()
   try:
       # do something...
   finally:
       some_lock.release()
991

992 993 994
Currently, :class:`Lock`, :class:`RLock`, :class:`Condition`,
:class:`Semaphore`, and :class:`BoundedSemaphore` objects may be used as
:keyword:`with` statement context managers.