Python usually calls :func:`sys.excepthook` on unhandled exceptions. If
:meth:`Future.set_exception` is called, but the exception is never consumed,
:func:`sys.excepthook` is not called. Instead, :ref:`a log is emitted
<asyncio-logger>` when the future is deleted by the garbage collector, with the
traceback where the exception was raised.
If a :meth:`Future.set_exception` is called but the Future object is
never awaited on, the exception would never be propagated to the
user code. In this case, asyncio would emit a log message when the
Future object is garbage collected.
Example of unhandled exception::
Example of an unhandled exception::
import asyncio
@asyncio.coroutine
def bug():
async def bug():
raise Exception("not consumed")
loop = asyncio.get_event_loop()
asyncio.ensure_future(bug())
loop.run_forever()
loop.close()
async def main():
asyncio.create_task(bug())
asyncio.run(main())
Output::
Task exception was never retrieved
future: <Task finished coro=<coro() done, defined at asyncio/coroutines.py:139> exception=Exception('not consumed',)>
Traceback (most recent call last):
File "asyncio/tasks.py", line 237, in _step
result = next(coro)
File "asyncio/coroutines.py", line 141, in coro
res = func(*args, **kw)
File "test.py", line 5, in bug
raise Exception("not consumed")
Exception: not consumed
future: <Task finished coro=<bug() done, defined at test.py:3>
exception=Exception('not consumed')>
:ref:`Enable the debug mode of asyncio <asyncio-debug-mode>` to get the
traceback where the task was created. Output in debug mode::
Task exception was never retrieved
future: <Task finished coro=<bug() done, defined at test.py:3> exception=Exception('not consumed',) created at test.py:8>
source_traceback: Object created at (most recent call last):
File "test.py", line 8, in <module>
asyncio.ensure_future(bug())
Traceback (most recent call last):
File "asyncio/tasks.py", line 237, in _step
result = next(coro)
File "asyncio/coroutines.py", line 79, in __next__
return next(self.gen)
File "asyncio/coroutines.py", line 141, in coro
res = func(*args, **kw)
File "test.py", line 5, in bug
File "test.py", line 4, in bug
raise Exception("not consumed")
Exception: not consumed
There are different options to fix this issue. The first option is to chain the
coroutine in another coroutine and use classic try/except::
async def handle_exception():
try:
await bug()
except Exception:
print("exception consumed")
loop = asyncio.get_event_loop()
asyncio.ensure_future(handle_exception())
loop.run_forever()
loop.close()
Another option is to use the :meth:`asyncio.run` function::
asyncio.run(bug())
.. seealso::
The :meth:`Future.exception` method.
:ref:`Enable the debug mode <asyncio-debug-mode>` to get the
traceback where the task was created::
Chain coroutines correctly
--------------------------
asyncio.run(main(), debug=True)
When a coroutine function calls other coroutine functions and tasks, they
should be chained explicitly with ``await``. Otherwise, the execution is
not guaranteed to be sequential.
Example with different bugs using :func:`asyncio.sleep` to simulate slow
operations::
import asyncio
async def create():
await asyncio.sleep(3.0)
print("(1) create file")
async def write():
await asyncio.sleep(1.0)
print("(2) write into file")
async def close():
print("(3) close file")
async def test():
asyncio.ensure_future(create())
asyncio.ensure_future(write())
asyncio.ensure_future(close())
await asyncio.sleep(2.0)
loop.stop()
loop = asyncio.get_event_loop()
asyncio.ensure_future(test())
loop.run_forever()
print("Pending tasks at exit: %s" % asyncio.Task.all_tasks(loop))
loop.close()
Expected output:
.. code-block:: none
(1) create file
(2) write into file
(3) close file
Pending tasks at exit: set()
Actual output:
.. code-block:: none
(3) close file
(2) write into file
Pending tasks at exit: {<Task pending create() at test.py:7 wait_for=<Future pending cb=[Task._wakeup()]>>}
Task was destroyed but it is pending!
task: <Task pending create() done at test.py:5 wait_for=<Future pending cb=[Task._wakeup()]>>
The loop stopped before the ``create()`` finished, ``close()`` has been called
before ``write()``, whereas coroutine functions were called in this order:
``create()``, ``write()``, ``close()``.
To fix the example, tasks must be marked with ``await``::
async def test():
await asyncio.ensure_future(create())
await asyncio.ensure_future(write())
await asyncio.ensure_future(close())
await asyncio.sleep(2.0)
loop.stop()
Or without ``asyncio.ensure_future()``::
async def test():
await create()
await write()
await close()
await asyncio.sleep(2.0)
loop.stop()
.. _asyncio-pending-task-destroyed:
Pending task destroyed
----------------------
If a pending task is destroyed, the execution of its wrapped :ref:`coroutine
<coroutine>` did not complete. It is probably a bug and so a warning is logged.
Example of log:
.. code-block:: none
Task was destroyed but it is pending!
task: <Task pending coro=<kill_me() done, defined at test.py:5> wait_for=<Future pending cb=[Task._wakeup()]>>
:ref:`Enable the debug mode of asyncio <asyncio-debug-mode>` to get the
traceback where the task was created. Example of log in debug mode:
Output in debug mode::
.. code-block:: none
Task exception was never retrieved
future: <Task finished coro=<bug() done, defined at test.py:3>
exception=Exception('not consumed') created at asyncio/tasks.py:321>
Task was destroyed but it is pending!
source_traceback: Object created at (most recent call last):
File "test.py", line 15, in <module>
task = asyncio.ensure_future(coro, loop=loop)
task: <Task pending coro=<kill_me() done, defined at test.py:5> wait_for=<Future pending cb=[Task._wakeup()] created at test.py:7> created at test.py:15>
.. seealso::
:ref:`Detect coroutine objects never scheduled <asyncio-coroutine-not-scheduled>`.
File "../t.py", line 9, in <module>
asyncio.run(main(), debug=True)
.. _asyncio-close-transports:
< .. >
Close transports and event loops
--------------------------------
When a transport is no longer needed, call its ``close()`` method to release
resources. Event loops must also be closed explicitly.
If a transport or an event loop is not closed explicitly, a
:exc:`ResourceWarning` warning will be emitted in its destructor. By default,
:exc:`ResourceWarning` warnings are ignored. The :ref:`Debug mode of asyncio
<asyncio-debug-mode>` section explains how to display them.
