Futures

Source code:Lib/asyncio/futures.py,Lib/asyncio/base_futures.py

Future objects are used to bridgelow-level callback-based codewith high-level async/await code.

Future Functions

asyncio.isfuture(obj)

ReturnTrue ifobj is either of:

New in version 3.5.

asyncio.ensure_future(obj,*,loop=None)

Return:

  • obj argument as is, ifobj is aFuture,aTask, or a Future-like object (isfuture()is used for the test.)

  • aTask object wrappingobj, ifobj is acoroutine (iscoroutine() is used for the test);in this case the coroutine will be scheduled byensure_future().

  • aTask object that would await onobj, ifobj is anawaitable (inspect.isawaitable() is used for the test.)

Ifobj is neither of the above aTypeError is raised.

Important

See also thecreate_task() function which is thepreferred way for creating new Tasks.

Save a reference to the result of this function, to avoida task disappearing mid execution.

Changed in version 3.5.1:The function accepts anyawaitable object.

asyncio.wrap_future(future,*,loop=None)

Wrap aconcurrent.futures.Future object in aasyncio.Future object.

Future Object

classasyncio.Future(*,loop=None)

A Future represents an eventual result of an asynchronousoperation. Not thread-safe.

Future is anawaitable object. Coroutines can await onFuture objects until they either have a result or an exceptionset, or until they are cancelled.

Typically Futures are used to enable low-levelcallback-based code (e.g. in protocols implemented using asynciotransports)to interoperate with high-level async/await code.

The rule of thumb is to never expose Future objects in user-facingAPIs, and the recommended way to create a Future object is to callloop.create_future(). This way alternative event loopimplementations can inject their own optimized implementationsof a Future object.

Changed in version 3.7:Added support for thecontextvars module.

result()

Return the result of the Future.

If the Future isdone and has a result set by theset_result() method, the result value is returned.

If the Future isdone and has an exception set by theset_exception() method, this method raises the exception.

If the Future has beencancelled, this method raisesaCancelledError exception.

If the Future’s result isn’t yet available, this method raisesaInvalidStateError exception.

set_result(result)

Mark the Future asdone and set its result.

Raises aInvalidStateError error if the Future isalreadydone.

set_exception(exception)

Mark the Future asdone and set an exception.

Raises aInvalidStateError error if the Future isalreadydone.

done()

ReturnTrue if the Future isdone.

A Future isdone if it wascancelled or if it has a resultor an exception set withset_result() orset_exception() calls.

cancelled()

ReturnTrue if the Future wascancelled.

The method is usually used to check if a Future is notcancelled before setting a result or an exception for it:

ifnotfut.cancelled():fut.set_result(42)
add_done_callback(callback,*,context=None)

Add a callback to be run when the Future isdone.

Thecallback is called with the Future object as its onlyargument.

If the Future is alreadydone when this method is called,the callback is scheduled withloop.call_soon().

An optional keyword-onlycontext argument allows specifying acustomcontextvars.Context for thecallback to run in.The current context is used when nocontext is provided.

functools.partial() can be used to pass parametersto the callback, e.g.:

# Call 'print("Future:", fut)' when "fut" is done.fut.add_done_callback(functools.partial(print,"Future:"))

Changed in version 3.7:Thecontext keyword-only parameter was added.SeePEP 567 for more details.

remove_done_callback(callback)

Removecallback from the callbacks list.

Returns the number of callbacks removed, which is typically 1,unless a callback was added more than once.

cancel(msg=None)

Cancel the Future and schedule callbacks.

If the Future is alreadydone orcancelled, returnFalse.Otherwise, change the Future’s state tocancelled,schedule the callbacks, and returnTrue.

Changed in version 3.9:Added themsg parameter.

exception()

Return the exception that was set on this Future.

The exception (orNone if no exception was set) isreturned only if the Future isdone.

If the Future has beencancelled, this method raises aCancelledError exception.

If the Future isn’tdone yet, this method raises anInvalidStateError exception.

get_loop()

Return the event loop the Future object is bound to.

New in version 3.7.

This example creates a Future object, creates and schedules anasynchronous Task to set result for the Future, and waits untilthe Future has a result:

asyncdefset_after(fut,delay,value):# Sleep for *delay* seconds.awaitasyncio.sleep(delay)# Set *value* as a result of *fut* Future.fut.set_result(value)asyncdefmain():# Get the current event loop.loop=asyncio.get_running_loop()# Create a new Future object.fut=loop.create_future()# Run "set_after()" coroutine in a parallel Task.# We are using the low-level "loop.create_task()" API here because# we already have a reference to the event loop at hand.# Otherwise we could have just used "asyncio.create_task()".loop.create_task(set_after(fut,1,'... world'))print('hello ...')# Wait until *fut* has a result (1 second) and print it.print(awaitfut)asyncio.run(main())

Important

The Future object was designed to mimicconcurrent.futures.Future. Key differences include: