1.. currentmodule:: asyncio 2 3 4.. _asyncio-futures: 5 6======= 7Futures 8======= 9 10**Source code:** :source:`Lib/asyncio/futures.py`, 11:source:`Lib/asyncio/base_futures.py` 12 13------------------------------------- 14 15*Future* objects are used to bridge **low-level callback-based code** 16with high-level async/await code. 17 18 19Future Functions 20================ 21 22.. function:: isfuture(obj) 23 24 Return ``True`` if *obj* is either of: 25 26 * an instance of :class:`asyncio.Future`, 27 * an instance of :class:`asyncio.Task`, 28 * a Future-like object with a ``_asyncio_future_blocking`` 29 attribute. 30 31 .. versionadded:: 3.5 32 33 34.. function:: ensure_future(obj, *, loop=None) 35 36 Return: 37 38 * *obj* argument as is, if *obj* is a :class:`Future`, 39 a :class:`Task`, or a Future-like object (:func:`isfuture` 40 is used for the test.) 41 42 * a :class:`Task` object wrapping *obj*, if *obj* is a 43 coroutine (:func:`iscoroutine` is used for the test); 44 in this case the coroutine will be scheduled by 45 ``ensure_future()``. 46 47 * a :class:`Task` object that would await on *obj*, if *obj* is an 48 awaitable (:func:`inspect.isawaitable` is used for the test.) 49 50 If *obj* is neither of the above a :exc:`TypeError` is raised. 51 52 .. important:: 53 54 See also the :func:`create_task` function which is the 55 preferred way for creating new Tasks. 56 57 Save a reference to the result of this function, to avoid 58 a task disappearing mid execution. 59 60 .. versionchanged:: 3.5.1 61 The function accepts any :term:`awaitable` object. 62 63 .. deprecated:: 3.10 64 Deprecation warning is emitted if *obj* is not a Future-like object 65 and *loop* is not specified and there is no running event loop. 66 67 68.. function:: wrap_future(future, *, loop=None) 69 70 Wrap a :class:`concurrent.futures.Future` object in a 71 :class:`asyncio.Future` object. 72 73 .. deprecated:: 3.10 74 Deprecation warning is emitted if *future* is not a Future-like object 75 and *loop* is not specified and there is no running event loop. 76 77 78Future Object 79============= 80 81.. class:: Future(*, loop=None) 82 83 A Future represents an eventual result of an asynchronous 84 operation. Not thread-safe. 85 86 Future is an :term:`awaitable` object. Coroutines can await on 87 Future objects until they either have a result or an exception 88 set, or until they are cancelled. 89 90 Typically Futures are used to enable low-level 91 callback-based code (e.g. in protocols implemented using asyncio 92 :ref:`transports <asyncio-transports-protocols>`) 93 to interoperate with high-level async/await code. 94 95 The rule of thumb is to never expose Future objects in user-facing 96 APIs, and the recommended way to create a Future object is to call 97 :meth:`loop.create_future`. This way alternative event loop 98 implementations can inject their own optimized implementations 99 of a Future object. 100 101 .. versionchanged:: 3.7 102 Added support for the :mod:`contextvars` module. 103 104 .. deprecated:: 3.10 105 Deprecation warning is emitted if *loop* is not specified 106 and there is no running event loop. 107 108 .. method:: result() 109 110 Return the result of the Future. 111 112 If the Future is *done* and has a result set by the 113 :meth:`set_result` method, the result value is returned. 114 115 If the Future is *done* and has an exception set by the 116 :meth:`set_exception` method, this method raises the exception. 117 118 If the Future has been *cancelled*, this method raises 119 a :exc:`CancelledError` exception. 120 121 If the Future's result isn't yet available, this method raises 122 a :exc:`InvalidStateError` exception. 123 124 .. method:: set_result(result) 125 126 Mark the Future as *done* and set its result. 127 128 Raises a :exc:`InvalidStateError` error if the Future is 129 already *done*. 130 131 .. method:: set_exception(exception) 132 133 Mark the Future as *done* and set an exception. 134 135 Raises a :exc:`InvalidStateError` error if the Future is 136 already *done*. 137 138 .. method:: done() 139 140 Return ``True`` if the Future is *done*. 141 142 A Future is *done* if it was *cancelled* or if it has a result 143 or an exception set with :meth:`set_result` or 144 :meth:`set_exception` calls. 145 146 .. method:: cancelled() 147 148 Return ``True`` if the Future was *cancelled*. 149 150 The method is usually used to check if a Future is not 151 *cancelled* before setting a result or an exception for it:: 152 153 if not fut.cancelled(): 154 fut.set_result(42) 155 156 .. method:: add_done_callback(callback, *, context=None) 157 158 Add a callback to be run when the Future is *done*. 159 160 The *callback* is called with the Future object as its only 161 argument. 162 163 If the Future is already *done* when this method is called, 164 the callback is scheduled with :meth:`loop.call_soon`. 165 166 An optional keyword-only *context* argument allows specifying a 167 custom :class:`contextvars.Context` for the *callback* to run in. 168 The current context is used when no *context* is provided. 169 170 :func:`functools.partial` can be used to pass parameters 171 to the callback, e.g.:: 172 173 # Call 'print("Future:", fut)' when "fut" is done. 174 fut.add_done_callback( 175 functools.partial(print, "Future:")) 176 177 .. versionchanged:: 3.7 178 The *context* keyword-only parameter was added. 179 See :pep:`567` for more details. 180 181 .. method:: remove_done_callback(callback) 182 183 Remove *callback* from the callbacks list. 184 185 Returns the number of callbacks removed, which is typically 1, 186 unless a callback was added more than once. 187 188 .. method:: cancel(msg=None) 189 190 Cancel the Future and schedule callbacks. 191 192 If the Future is already *done* or *cancelled*, return ``False``. 193 Otherwise, change the Future's state to *cancelled*, 194 schedule the callbacks, and return ``True``. 195 196 .. versionchanged:: 3.9 197 Added the ``msg`` parameter. 198 199 .. method:: exception() 200 201 Return the exception that was set on this Future. 202 203 The exception (or ``None`` if no exception was set) is 204 returned only if the Future is *done*. 205 206 If the Future has been *cancelled*, this method raises a 207 :exc:`CancelledError` exception. 208 209 If the Future isn't *done* yet, this method raises an 210 :exc:`InvalidStateError` exception. 211 212 .. method:: get_loop() 213 214 Return the event loop the Future object is bound to. 215 216 .. versionadded:: 3.7 217 218 219.. _asyncio_example_future: 220 221This example creates a Future object, creates and schedules an 222asynchronous Task to set result for the Future, and waits until 223the Future has a result:: 224 225 async def set_after(fut, delay, value): 226 # Sleep for *delay* seconds. 227 await asyncio.sleep(delay) 228 229 # Set *value* as a result of *fut* Future. 230 fut.set_result(value) 231 232 async def main(): 233 # Get the current event loop. 234 loop = asyncio.get_running_loop() 235 236 # Create a new Future object. 237 fut = loop.create_future() 238 239 # Run "set_after()" coroutine in a parallel Task. 240 # We are using the low-level "loop.create_task()" API here because 241 # we already have a reference to the event loop at hand. 242 # Otherwise we could have just used "asyncio.create_task()". 243 loop.create_task( 244 set_after(fut, 1, '... world')) 245 246 print('hello ...') 247 248 # Wait until *fut* has a result (1 second) and print it. 249 print(await fut) 250 251 asyncio.run(main()) 252 253 254.. important:: 255 256 The Future object was designed to mimic 257 :class:`concurrent.futures.Future`. Key differences include: 258 259 - unlike asyncio Futures, :class:`concurrent.futures.Future` 260 instances cannot be awaited. 261 262 - :meth:`asyncio.Future.result` and :meth:`asyncio.Future.exception` 263 do not accept the *timeout* argument. 264 265 - :meth:`asyncio.Future.result` and :meth:`asyncio.Future.exception` 266 raise an :exc:`InvalidStateError` exception when the Future is not 267 *done*. 268 269 - Callbacks registered with :meth:`asyncio.Future.add_done_callback` 270 are not called immediately. They are scheduled with 271 :meth:`loop.call_soon` instead. 272 273 - asyncio Future is not compatible with the 274 :func:`concurrent.futures.wait` and 275 :func:`concurrent.futures.as_completed` functions. 276 277 - :meth:`asyncio.Future.cancel` accepts an optional ``msg`` argument, 278 but :func:`concurrent.futures.cancel` does not. 279