Victor Stinner | db39a0d | 2014-01-16 18:58:01 +0100 | [diff] [blame] | 1 | .. currentmodule:: asyncio |
| 2 | |
Victor Stinner | 0f3e6bc | 2014-02-19 23:15:02 +0100 | [diff] [blame] | 3 | .. _asyncio-dev: |
| 4 | |
Victor Stinner | db39a0d | 2014-01-16 18:58:01 +0100 | [diff] [blame] | 5 | Develop with asyncio |
| 6 | ==================== |
| 7 | |
| 8 | Asynchronous programming is different than classical "sequential" programming. |
Eli Bendersky | 679688e | 2014-01-20 08:13:31 -0800 | [diff] [blame] | 9 | This page lists common traps and explains how to avoid them. |
Victor Stinner | db39a0d | 2014-01-16 18:58:01 +0100 | [diff] [blame] | 10 | |
| 11 | |
Victor Stinner | 62511fd | 2014-06-23 00:36:11 +0200 | [diff] [blame] | 12 | .. _asyncio-debug-mode: |
| 13 | |
| 14 | Debug mode of asyncio |
| 15 | --------------------- |
| 16 | |
Victor Stinner | 6a1b004 | 2015-02-04 16:14:33 +0100 | [diff] [blame] | 17 | The implementation of :mod:`asyncio` module has been written for performances. |
| 18 | To development with asyncio, it's required to enable the debug checks to ease |
| 19 | the development of asynchronous code. |
Victor Stinner | d71dcbb | 2014-08-25 17:04:12 +0200 | [diff] [blame] | 20 | |
Victor Stinner | 6a1b004 | 2015-02-04 16:14:33 +0100 | [diff] [blame] | 21 | Setup an application to enable all debug checks: |
Victor Stinner | d71dcbb | 2014-08-25 17:04:12 +0200 | [diff] [blame] | 22 | |
Victor Stinner | 6a1b004 | 2015-02-04 16:14:33 +0100 | [diff] [blame] | 23 | * Enable the asyncio debug mode globally by setting the environment variable |
| 24 | :envvar:`PYTHONASYNCIODEBUG` to ``1`` |
| 25 | * Set the log level of the :ref:`asyncio logger <asyncio-logger>` to |
| 26 | :py:data:`logging.DEBUG`. For example, call |
| 27 | ``logging.basicConfig(level=logging.DEBUG)`` at startup. |
| 28 | * Configure the :mod:`warnings` module to display :exc:`ResourceWarning` |
| 29 | warnings. For example, use the ``-Wdefault`` command line option of Python to |
| 30 | display them. |
| 31 | |
| 32 | Examples debug checks: |
Victor Stinner | 62511fd | 2014-06-23 00:36:11 +0200 | [diff] [blame] | 33 | |
| 34 | * Log :ref:`coroutines defined but never "yielded from" |
| 35 | <asyncio-coroutine-not-scheduled>` |
| 36 | * :meth:`~BaseEventLoop.call_soon` and :meth:`~BaseEventLoop.call_at` methods |
| 37 | raise an exception if they are called from the wrong thread. |
| 38 | * Log the execution time of the selector |
| 39 | * Log callbacks taking more than 100 ms to be executed. The |
| 40 | :attr:`BaseEventLoop.slow_callback_duration` attribute is the minimum |
| 41 | duration in seconds of "slow" callbacks. |
Victor Stinner | 6a1b004 | 2015-02-04 16:14:33 +0100 | [diff] [blame] | 42 | * :exc:`ResourceWarning` warnings are emitted when transports and event loops |
| 43 | are :ref:`not closed explicitly <asyncio-close-transports>`. |
Victor Stinner | 62511fd | 2014-06-23 00:36:11 +0200 | [diff] [blame] | 44 | |
| 45 | .. seealso:: |
| 46 | |
| 47 | The :meth:`BaseEventLoop.set_debug` method and the :ref:`asyncio logger |
| 48 | <asyncio-logger>`. |
| 49 | |
| 50 | |
Victor Stinner | 1077dee | 2015-01-30 00:55:58 +0100 | [diff] [blame] | 51 | Cancellation |
| 52 | ------------ |
| 53 | |
| 54 | Cancellation of tasks is not common in classic programming. In asynchronous |
| 55 | programming, not only it is something common, but you have to prepare your |
| 56 | code to handle it. |
| 57 | |
| 58 | Futures and tasks can be cancelled explicitly with their :meth:`Future.cancel` |
| 59 | method. The :func:`wait_for` function cancels the waited task when the timeout |
| 60 | occurs. There are many other cases where a task can be cancelled indirectly. |
| 61 | |
| 62 | Don't call :meth:`~Future.set_result` or :meth:`~Future.set_exception` method |
| 63 | of :class:`Future` if the future is cancelled: it would fail with an exception. |
| 64 | For example, write:: |
| 65 | |
| 66 | if not fut.cancelled(): |
| 67 | fut.set_result('done') |
| 68 | |
| 69 | Don't schedule directly a call to the :meth:`~Future.set_result` or the |
| 70 | :meth:`~Future.set_exception` method of a future with |
| 71 | :meth:`BaseEventLoop.call_soon`: the future can be cancelled before its method |
| 72 | is called. |
| 73 | |
| 74 | If you wait for a future, you should check early if the future was cancelled to |
| 75 | avoid useless operations. Example:: |
| 76 | |
| 77 | @coroutine |
| 78 | def slow_operation(fut): |
| 79 | if fut.cancelled(): |
| 80 | return |
| 81 | # ... slow computation ... |
| 82 | yield from fut |
| 83 | # ... |
| 84 | |
| 85 | The :func:`shield` function can also be used to ignore cancellation. |
| 86 | |
| 87 | |
Victor Stinner | 606ab03 | 2014-02-01 03:18:58 +0100 | [diff] [blame] | 88 | .. _asyncio-multithreading: |
| 89 | |
| 90 | Concurrency and multithreading |
| 91 | ------------------------------ |
| 92 | |
| 93 | An event loop runs in a thread and executes all callbacks and tasks in the same |
Victor Stinner | 86516d9 | 2014-02-18 09:22:00 +0100 | [diff] [blame] | 94 | thread. While a task is running in the event loop, no other task is running in |
Victor Stinner | 5cb84ed | 2014-02-04 18:18:27 +0100 | [diff] [blame] | 95 | the same thread. But when the task uses ``yield from``, the task is suspended |
| 96 | and the event loop executes the next task. |
Victor Stinner | 606ab03 | 2014-02-01 03:18:58 +0100 | [diff] [blame] | 97 | |
Victor Stinner | 5cb84ed | 2014-02-04 18:18:27 +0100 | [diff] [blame] | 98 | To schedule a callback from a different thread, the |
| 99 | :meth:`BaseEventLoop.call_soon_threadsafe` method should be used. Example to |
Guido van Rossum | 3c9bb69 | 2014-02-04 13:49:34 -0800 | [diff] [blame] | 100 | schedule a coroutine from a different thread:: |
Victor Stinner | 5cb84ed | 2014-02-04 18:18:27 +0100 | [diff] [blame] | 101 | |
Yury Selivanov | 04356e1 | 2015-06-30 22:13:22 -0400 | [diff] [blame] | 102 | loop.call_soon_threadsafe(asyncio.ensure_future, coro_func()) |
Victor Stinner | 606ab03 | 2014-02-01 03:18:58 +0100 | [diff] [blame] | 103 | |
Victor Stinner | 790202d | 2014-02-07 19:03:05 +0100 | [diff] [blame] | 104 | Most asyncio objects are not thread safe. You should only worry if you access |
| 105 | objects outside the event loop. For example, to cancel a future, don't call |
| 106 | directly its :meth:`Future.cancel` method, but:: |
| 107 | |
| 108 | loop.call_soon_threadsafe(fut.cancel) |
| 109 | |
Victor Stinner | 606ab03 | 2014-02-01 03:18:58 +0100 | [diff] [blame] | 110 | To handle signals and to execute subprocesses, the event loop must be run in |
| 111 | the main thread. |
| 112 | |
| 113 | The :meth:`BaseEventLoop.run_in_executor` method can be used with a thread pool |
| 114 | executor to execute a callback in different thread to not block the thread of |
| 115 | the event loop. |
| 116 | |
| 117 | .. seealso:: |
| 118 | |
Zachary Ware | 5819cfa | 2015-01-06 00:40:43 -0600 | [diff] [blame] | 119 | The :ref:`Synchronization primitives <asyncio-sync>` section describes ways |
| 120 | to synchronize tasks. |
Victor Stinner | 606ab03 | 2014-02-01 03:18:58 +0100 | [diff] [blame] | 121 | |
Victor Stinner | 399c59d | 2015-01-09 01:32:02 +0100 | [diff] [blame] | 122 | The :ref:`Subprocess and threads <asyncio-subprocess-threads>` section lists |
| 123 | asyncio limitations to run subprocesses from different threads. |
| 124 | |
| 125 | |
| 126 | |
Victor Stinner | 606ab03 | 2014-02-01 03:18:58 +0100 | [diff] [blame] | 127 | |
Victor Stinner | 45b27ed | 2014-02-01 02:36:43 +0100 | [diff] [blame] | 128 | .. _asyncio-handle-blocking: |
| 129 | |
Eli Bendersky | b73c833 | 2014-02-09 06:07:47 -0800 | [diff] [blame] | 130 | Handle blocking functions correctly |
Victor Stinner | db39a0d | 2014-01-16 18:58:01 +0100 | [diff] [blame] | 131 | ----------------------------------- |
| 132 | |
| 133 | Blocking functions should not be called directly. For example, if a function |
| 134 | blocks for 1 second, other tasks are delayed by 1 second which can have an |
| 135 | important impact on reactivity. |
| 136 | |
| 137 | For networking and subprocesses, the :mod:`asyncio` module provides high-level |
Victor Stinner | 9592edb | 2014-02-02 15:03:02 +0100 | [diff] [blame] | 138 | APIs like :ref:`protocols <asyncio-protocol>`. |
Victor Stinner | db39a0d | 2014-01-16 18:58:01 +0100 | [diff] [blame] | 139 | |
| 140 | An executor can be used to run a task in a different thread or even in a |
| 141 | different process, to not block the thread of the event loop. See the |
Victor Stinner | 606ab03 | 2014-02-01 03:18:58 +0100 | [diff] [blame] | 142 | :meth:`BaseEventLoop.run_in_executor` method. |
Victor Stinner | db39a0d | 2014-01-16 18:58:01 +0100 | [diff] [blame] | 143 | |
Victor Stinner | 45b27ed | 2014-02-01 02:36:43 +0100 | [diff] [blame] | 144 | .. seealso:: |
| 145 | |
| 146 | The :ref:`Delayed calls <asyncio-delayed-calls>` section details how the |
| 147 | event loop handles time. |
| 148 | |
Victor Stinner | db39a0d | 2014-01-16 18:58:01 +0100 | [diff] [blame] | 149 | |
| 150 | .. _asyncio-logger: |
| 151 | |
Victor Stinner | 45b27ed | 2014-02-01 02:36:43 +0100 | [diff] [blame] | 152 | Logging |
| 153 | ------- |
Victor Stinner | db39a0d | 2014-01-16 18:58:01 +0100 | [diff] [blame] | 154 | |
Victor Stinner | 45b27ed | 2014-02-01 02:36:43 +0100 | [diff] [blame] | 155 | The :mod:`asyncio` module logs information with the :mod:`logging` module in |
| 156 | the logger ``'asyncio'``. |
Victor Stinner | db39a0d | 2014-01-16 18:58:01 +0100 | [diff] [blame] | 157 | |
Victor Stinner | db39a0d | 2014-01-16 18:58:01 +0100 | [diff] [blame] | 158 | |
| 159 | .. _asyncio-coroutine-not-scheduled: |
| 160 | |
| 161 | Detect coroutine objects never scheduled |
| 162 | ---------------------------------------- |
| 163 | |
Victor Stinner | 530ef2f | 2014-07-08 12:39:10 +0200 | [diff] [blame] | 164 | When a coroutine function is called and its result is not passed to |
Yury Selivanov | 04356e1 | 2015-06-30 22:13:22 -0400 | [diff] [blame] | 165 | :func:`ensure_future` or to the :meth:`BaseEventLoop.create_task` method, |
| 166 | the execution of the coroutine object will never be scheduled which is |
| 167 | probably a bug. :ref:`Enable the debug mode of asyncio <asyncio-debug-mode>` |
| 168 | to :ref:`log a warning <asyncio-logger>` to detect it. |
Victor Stinner | db39a0d | 2014-01-16 18:58:01 +0100 | [diff] [blame] | 169 | |
| 170 | Example with the bug:: |
| 171 | |
| 172 | import asyncio |
Victor Stinner | db39a0d | 2014-01-16 18:58:01 +0100 | [diff] [blame] | 173 | |
| 174 | @asyncio.coroutine |
| 175 | def test(): |
| 176 | print("never scheduled") |
| 177 | |
| 178 | test() |
| 179 | |
| 180 | Output in debug mode:: |
| 181 | |
Victor Stinner | 530ef2f | 2014-07-08 12:39:10 +0200 | [diff] [blame] | 182 | Coroutine test() at test.py:3 was never yielded from |
| 183 | Coroutine object created at (most recent call last): |
| 184 | File "test.py", line 7, in <module> |
| 185 | test() |
Victor Stinner | db39a0d | 2014-01-16 18:58:01 +0100 | [diff] [blame] | 186 | |
Yury Selivanov | 04356e1 | 2015-06-30 22:13:22 -0400 | [diff] [blame] | 187 | The fix is to call the :func:`ensure_future` function or the |
Victor Stinner | 530ef2f | 2014-07-08 12:39:10 +0200 | [diff] [blame] | 188 | :meth:`BaseEventLoop.create_task` method with the coroutine object. |
| 189 | |
| 190 | .. seealso:: |
| 191 | |
| 192 | :ref:`Pending task destroyed <asyncio-pending-task-destroyed>`. |
Victor Stinner | db39a0d | 2014-01-16 18:58:01 +0100 | [diff] [blame] | 193 | |
| 194 | |
Victor Stinner | 530ef2f | 2014-07-08 12:39:10 +0200 | [diff] [blame] | 195 | Detect exceptions never consumed |
| 196 | -------------------------------- |
Victor Stinner | db39a0d | 2014-01-16 18:58:01 +0100 | [diff] [blame] | 197 | |
| 198 | Python usually calls :func:`sys.displayhook` on unhandled exceptions. If |
Victor Stinner | 530ef2f | 2014-07-08 12:39:10 +0200 | [diff] [blame] | 199 | :meth:`Future.set_exception` is called, but the exception is never consumed, |
Zachary Ware | 5819cfa | 2015-01-06 00:40:43 -0600 | [diff] [blame] | 200 | :func:`sys.displayhook` is not called. Instead, :ref:`a log is emitted |
Victor Stinner | 530ef2f | 2014-07-08 12:39:10 +0200 | [diff] [blame] | 201 | <asyncio-logger>` when the future is deleted by the garbage collector, with the |
| 202 | traceback where the exception was raised. |
Victor Stinner | db39a0d | 2014-01-16 18:58:01 +0100 | [diff] [blame] | 203 | |
| 204 | Example of unhandled exception:: |
| 205 | |
| 206 | import asyncio |
| 207 | |
| 208 | @asyncio.coroutine |
| 209 | def bug(): |
| 210 | raise Exception("not consumed") |
| 211 | |
| 212 | loop = asyncio.get_event_loop() |
Yury Selivanov | d7e19bb | 2015-05-11 16:33:41 -0400 | [diff] [blame] | 213 | asyncio.ensure_future(bug()) |
Victor Stinner | db39a0d | 2014-01-16 18:58:01 +0100 | [diff] [blame] | 214 | loop.run_forever() |
Victor Stinner | b8064a8 | 2015-02-23 11:41:56 +0100 | [diff] [blame] | 215 | loop.close() |
Victor Stinner | db39a0d | 2014-01-16 18:58:01 +0100 | [diff] [blame] | 216 | |
| 217 | Output:: |
| 218 | |
Victor Stinner | 530ef2f | 2014-07-08 12:39:10 +0200 | [diff] [blame] | 219 | Task exception was never retrieved |
Victor Stinner | ab1c853 | 2014-10-12 21:37:16 +0200 | [diff] [blame] | 220 | future: <Task finished coro=<coro() done, defined at asyncio/coroutines.py:139> exception=Exception('not consumed',)> |
Victor Stinner | db39a0d | 2014-01-16 18:58:01 +0100 | [diff] [blame] | 221 | Traceback (most recent call last): |
Victor Stinner | ab1c853 | 2014-10-12 21:37:16 +0200 | [diff] [blame] | 222 | File "asyncio/tasks.py", line 237, in _step |
Victor Stinner | db39a0d | 2014-01-16 18:58:01 +0100 | [diff] [blame] | 223 | result = next(coro) |
Victor Stinner | 530ef2f | 2014-07-08 12:39:10 +0200 | [diff] [blame] | 224 | File "asyncio/coroutines.py", line 141, in coro |
Victor Stinner | db39a0d | 2014-01-16 18:58:01 +0100 | [diff] [blame] | 225 | res = func(*args, **kw) |
Victor Stinner | ab1c853 | 2014-10-12 21:37:16 +0200 | [diff] [blame] | 226 | File "test.py", line 5, in bug |
Victor Stinner | db39a0d | 2014-01-16 18:58:01 +0100 | [diff] [blame] | 227 | raise Exception("not consumed") |
| 228 | Exception: not consumed |
| 229 | |
Victor Stinner | 530ef2f | 2014-07-08 12:39:10 +0200 | [diff] [blame] | 230 | :ref:`Enable the debug mode of asyncio <asyncio-debug-mode>` to get the |
Victor Stinner | ab1c853 | 2014-10-12 21:37:16 +0200 | [diff] [blame] | 231 | traceback where the task was created. Output in debug mode:: |
| 232 | |
| 233 | Task exception was never retrieved |
| 234 | future: <Task finished coro=<bug() done, defined at test.py:3> exception=Exception('not consumed',) created at test.py:8> |
| 235 | source_traceback: Object created at (most recent call last): |
| 236 | File "test.py", line 8, in <module> |
Yury Selivanov | d7e19bb | 2015-05-11 16:33:41 -0400 | [diff] [blame] | 237 | asyncio.ensure_future(bug()) |
Victor Stinner | ab1c853 | 2014-10-12 21:37:16 +0200 | [diff] [blame] | 238 | Traceback (most recent call last): |
| 239 | File "asyncio/tasks.py", line 237, in _step |
| 240 | result = next(coro) |
| 241 | File "asyncio/coroutines.py", line 79, in __next__ |
| 242 | return next(self.gen) |
| 243 | File "asyncio/coroutines.py", line 141, in coro |
| 244 | res = func(*args, **kw) |
| 245 | File "test.py", line 5, in bug |
| 246 | raise Exception("not consumed") |
| 247 | Exception: not consumed |
Victor Stinner | 530ef2f | 2014-07-08 12:39:10 +0200 | [diff] [blame] | 248 | |
Zachary Ware | 5819cfa | 2015-01-06 00:40:43 -0600 | [diff] [blame] | 249 | There are different options to fix this issue. The first option is to chain the |
Victor Stinner | db39a0d | 2014-01-16 18:58:01 +0100 | [diff] [blame] | 250 | coroutine in another coroutine and use classic try/except:: |
| 251 | |
| 252 | @asyncio.coroutine |
| 253 | def handle_exception(): |
| 254 | try: |
| 255 | yield from bug() |
| 256 | except Exception: |
| 257 | print("exception consumed") |
| 258 | |
| 259 | loop = asyncio.get_event_loop() |
Yury Selivanov | d7e19bb | 2015-05-11 16:33:41 -0400 | [diff] [blame] | 260 | asyncio.ensure_future(handle_exception()) |
Victor Stinner | db39a0d | 2014-01-16 18:58:01 +0100 | [diff] [blame] | 261 | loop.run_forever() |
Victor Stinner | b8064a8 | 2015-02-23 11:41:56 +0100 | [diff] [blame] | 262 | loop.close() |
Victor Stinner | db39a0d | 2014-01-16 18:58:01 +0100 | [diff] [blame] | 263 | |
| 264 | Another option is to use the :meth:`BaseEventLoop.run_until_complete` |
| 265 | function:: |
| 266 | |
Yury Selivanov | d7e19bb | 2015-05-11 16:33:41 -0400 | [diff] [blame] | 267 | task = asyncio.ensure_future(bug()) |
Victor Stinner | db39a0d | 2014-01-16 18:58:01 +0100 | [diff] [blame] | 268 | try: |
| 269 | loop.run_until_complete(task) |
| 270 | except Exception: |
| 271 | print("exception consumed") |
| 272 | |
Zachary Ware | 5819cfa | 2015-01-06 00:40:43 -0600 | [diff] [blame] | 273 | .. seealso:: |
| 274 | |
| 275 | The :meth:`Future.exception` method. |
Victor Stinner | db39a0d | 2014-01-16 18:58:01 +0100 | [diff] [blame] | 276 | |
| 277 | |
Zachary Ware | 5819cfa | 2015-01-06 00:40:43 -0600 | [diff] [blame] | 278 | Chain coroutines correctly |
Victor Stinner | db39a0d | 2014-01-16 18:58:01 +0100 | [diff] [blame] | 279 | -------------------------- |
| 280 | |
| 281 | When a coroutine function calls other coroutine functions and tasks, they |
Eli Bendersky | 679688e | 2014-01-20 08:13:31 -0800 | [diff] [blame] | 282 | should be chained explicitly with ``yield from``. Otherwise, the execution is |
| 283 | not guaranteed to be sequential. |
Victor Stinner | db39a0d | 2014-01-16 18:58:01 +0100 | [diff] [blame] | 284 | |
Eli Bendersky | 679688e | 2014-01-20 08:13:31 -0800 | [diff] [blame] | 285 | Example with different bugs using :func:`asyncio.sleep` to simulate slow |
| 286 | operations:: |
Victor Stinner | db39a0d | 2014-01-16 18:58:01 +0100 | [diff] [blame] | 287 | |
| 288 | import asyncio |
| 289 | |
| 290 | @asyncio.coroutine |
| 291 | def create(): |
| 292 | yield from asyncio.sleep(3.0) |
| 293 | print("(1) create file") |
| 294 | |
| 295 | @asyncio.coroutine |
| 296 | def write(): |
| 297 | yield from asyncio.sleep(1.0) |
| 298 | print("(2) write into file") |
| 299 | |
| 300 | @asyncio.coroutine |
| 301 | def close(): |
| 302 | print("(3) close file") |
| 303 | |
| 304 | @asyncio.coroutine |
| 305 | def test(): |
Yury Selivanov | d7e19bb | 2015-05-11 16:33:41 -0400 | [diff] [blame] | 306 | asyncio.ensure_future(create()) |
| 307 | asyncio.ensure_future(write()) |
| 308 | asyncio.ensure_future(close()) |
Victor Stinner | db39a0d | 2014-01-16 18:58:01 +0100 | [diff] [blame] | 309 | yield from asyncio.sleep(2.0) |
| 310 | loop.stop() |
| 311 | |
| 312 | loop = asyncio.get_event_loop() |
Yury Selivanov | d7e19bb | 2015-05-11 16:33:41 -0400 | [diff] [blame] | 313 | asyncio.ensure_future(test()) |
Victor Stinner | db39a0d | 2014-01-16 18:58:01 +0100 | [diff] [blame] | 314 | loop.run_forever() |
| 315 | print("Pending tasks at exit: %s" % asyncio.Task.all_tasks(loop)) |
Victor Stinner | f40c663 | 2014-01-28 23:32:40 +0100 | [diff] [blame] | 316 | loop.close() |
Victor Stinner | db39a0d | 2014-01-16 18:58:01 +0100 | [diff] [blame] | 317 | |
| 318 | Expected output:: |
| 319 | |
| 320 | (1) create file |
| 321 | (2) write into file |
| 322 | (3) close file |
| 323 | Pending tasks at exit: set() |
| 324 | |
| 325 | Actual output:: |
| 326 | |
| 327 | (3) close file |
| 328 | (2) write into file |
Victor Stinner | 530ef2f | 2014-07-08 12:39:10 +0200 | [diff] [blame] | 329 | Pending tasks at exit: {<Task pending create() at test.py:7 wait_for=<Future pending cb=[Task._wakeup()]>>} |
| 330 | Task was destroyed but it is pending! |
| 331 | task: <Task pending create() done at test.py:5 wait_for=<Future pending cb=[Task._wakeup()]>> |
Victor Stinner | db39a0d | 2014-01-16 18:58:01 +0100 | [diff] [blame] | 332 | |
| 333 | The loop stopped before the ``create()`` finished, ``close()`` has been called |
| 334 | before ``write()``, whereas coroutine functions were called in this order: |
| 335 | ``create()``, ``write()``, ``close()``. |
| 336 | |
| 337 | To fix the example, tasks must be marked with ``yield from``:: |
| 338 | |
| 339 | @asyncio.coroutine |
| 340 | def test(): |
Yury Selivanov | d7e19bb | 2015-05-11 16:33:41 -0400 | [diff] [blame] | 341 | yield from asyncio.ensure_future(create()) |
| 342 | yield from asyncio.ensure_future(write()) |
| 343 | yield from asyncio.ensure_future(close()) |
Victor Stinner | db39a0d | 2014-01-16 18:58:01 +0100 | [diff] [blame] | 344 | yield from asyncio.sleep(2.0) |
| 345 | loop.stop() |
| 346 | |
Yury Selivanov | d7e19bb | 2015-05-11 16:33:41 -0400 | [diff] [blame] | 347 | Or without ``asyncio.ensure_future()``:: |
Victor Stinner | db39a0d | 2014-01-16 18:58:01 +0100 | [diff] [blame] | 348 | |
| 349 | @asyncio.coroutine |
| 350 | def test(): |
| 351 | yield from create() |
| 352 | yield from write() |
| 353 | yield from close() |
| 354 | yield from asyncio.sleep(2.0) |
| 355 | loop.stop() |
| 356 | |
Victor Stinner | 530ef2f | 2014-07-08 12:39:10 +0200 | [diff] [blame] | 357 | |
| 358 | .. _asyncio-pending-task-destroyed: |
| 359 | |
| 360 | Pending task destroyed |
| 361 | ---------------------- |
| 362 | |
| 363 | If a pending task is destroyed, the execution of its wrapped :ref:`coroutine |
| 364 | <coroutine>` did not complete. It is probably a bug and so a warning is logged. |
| 365 | |
| 366 | Example of log:: |
| 367 | |
| 368 | Task was destroyed but it is pending! |
Victor Stinner | ab1c853 | 2014-10-12 21:37:16 +0200 | [diff] [blame] | 369 | task: <Task pending coro=<kill_me() done, defined at test.py:5> wait_for=<Future pending cb=[Task._wakeup()]>> |
Victor Stinner | 530ef2f | 2014-07-08 12:39:10 +0200 | [diff] [blame] | 370 | |
| 371 | :ref:`Enable the debug mode of asyncio <asyncio-debug-mode>` to get the |
Victor Stinner | ab1c853 | 2014-10-12 21:37:16 +0200 | [diff] [blame] | 372 | traceback where the task was created. Example of log in debug mode:: |
| 373 | |
| 374 | Task was destroyed but it is pending! |
| 375 | source_traceback: Object created at (most recent call last): |
| 376 | File "test.py", line 15, in <module> |
Yury Selivanov | d7e19bb | 2015-05-11 16:33:41 -0400 | [diff] [blame] | 377 | task = asyncio.ensure_future(coro, loop=loop) |
Victor Stinner | ab1c853 | 2014-10-12 21:37:16 +0200 | [diff] [blame] | 378 | 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> |
| 379 | |
Victor Stinner | 530ef2f | 2014-07-08 12:39:10 +0200 | [diff] [blame] | 380 | |
| 381 | .. seealso:: |
| 382 | |
| 383 | :ref:`Detect coroutine objects never scheduled <asyncio-coroutine-not-scheduled>`. |
| 384 | |
Victor Stinner | 6a1b004 | 2015-02-04 16:14:33 +0100 | [diff] [blame] | 385 | .. _asyncio-close-transports: |
Victor Stinner | 188f2c0 | 2015-01-30 01:35:14 +0100 | [diff] [blame] | 386 | |
Victor Stinner | 6a1b004 | 2015-02-04 16:14:33 +0100 | [diff] [blame] | 387 | Close transports and event loops |
| 388 | -------------------------------- |
Victor Stinner | 188f2c0 | 2015-01-30 01:35:14 +0100 | [diff] [blame] | 389 | |
| 390 | When a transport is no more needed, call its ``close()`` method to release |
Victor Stinner | 6a1b004 | 2015-02-04 16:14:33 +0100 | [diff] [blame] | 391 | resources. Event loops must also be closed explicitly. |
Victor Stinner | 188f2c0 | 2015-01-30 01:35:14 +0100 | [diff] [blame] | 392 | |
Victor Stinner | 6a1b004 | 2015-02-04 16:14:33 +0100 | [diff] [blame] | 393 | If a transport or an event loop is not closed explicitly, a |
| 394 | :exc:`ResourceWarning` warning will be emitted in its destructor. By default, |
| 395 | :exc:`ResourceWarning` warnings are ignored. The :ref:`Debug mode of asyncio |
| 396 | <asyncio-debug-mode>` section explains how to display them. |