diff --git a/Doc/library/asyncio-task.rst b/Doc/library/asyncio-task.rst index f825ae92ec7471..18f4476e367904 100644 --- a/Doc/library/asyncio-task.rst +++ b/Doc/library/asyncio-task.rst @@ -1222,7 +1222,7 @@ Task Object To cancel a running Task use the :meth:`cancel` method. Calling it will cause the Task to throw a :exc:`CancelledError` exception into the wrapped coroutine. If a coroutine is awaiting on a Future - object during cancellation, the Future object will be cancelled. + or Task object during cancellation, the awaited object will be cancelled. :meth:`cancelled` can be used to check if the Task was cancelled. The method returns ``True`` if the wrapped coroutine did not @@ -1231,7 +1231,8 @@ Task Object :class:`asyncio.Task` inherits from :class:`Future` all of its APIs except :meth:`Future.set_result` and - :meth:`Future.set_exception`. + :meth:`Future.set_exception`. This includes the cancellation + behavior: Tasks can be cancelled in the same way as Futures. An optional keyword-only *context* argument allows specifying a custom :class:`contextvars.Context` for the *coro* to run in. @@ -1410,6 +1411,10 @@ Task Object discouraged. Should the coroutine nevertheless decide to suppress the cancellation, it needs to call :meth:`Task.uncancel` in addition to catching the exception. + + If the Task being cancelled is currently awaiting another Task or + Future, that awaited object will also be cancelled. This cancellation + propagates down the entire chain of awaited objects. .. versionchanged:: 3.9 Added the *msg* parameter. diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index 97e7e08364e0bd..e329fe271b2ab4 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -164,7 +164,7 @@ This table summarizes the comparison operations: pair: object; numeric pair: objects; comparing -Objects of different types, except different numeric types, never compare equal. +Objects of different types, unless documented otherwise, never compare equal. The ``==`` operator is always defined but for some object types (for example, class objects) is equivalent to :keyword:`is`. The ``<``, ``<=``, ``>`` and ``>=`` operators are only defined where they make sense; for example, they raise a diff --git a/Doc/library/threading.rst b/Doc/library/threading.rst index 19cc4f191dff8d..b149a222115ec4 100644 --- a/Doc/library/threading.rst +++ b/Doc/library/threading.rst @@ -1144,9 +1144,11 @@ Semaphores also support the :ref:`context management protocol `. one and return ``True`` immediately. * If the internal counter is zero on entry, block until awoken by a call to :meth:`~Semaphore.release`. Once awoken (and the counter is greater - than 0), decrement the counter by 1 and return ``True``. Exactly one - thread will be awoken by each call to :meth:`~Semaphore.release`. The - order in which threads are awoken should not be relied on. + than 0), decrement the counter by 1 and return ``True``. Each call to + :meth:`~Semaphore.release` will wake up threads according to its *n* + parameter (default 1): if *j* threads are waiting and ``release(n)`` + is called, ``min(j, n)`` threads will be awoken. The order in which + threads are awoken should not be relied on. When invoked with *blocking* set to ``False``, do not block. If a call without an argument would block, return ``False`` immediately; otherwise, do @@ -1166,7 +1168,8 @@ Semaphores also support the :ref:`context management protocol `. Release a semaphore, incrementing the internal counter by *n*. When it was zero on entry and other threads are waiting for it to become larger - than zero again, wake up *n* of those threads. + than zero again, wake up to *n* of those threads (or all of them if + fewer than *n* are waiting). .. versionchanged:: 3.9 Added the *n* parameter to release multiple waiting threads at once.