Futures

Функции Futures

asyncio.isfuture(obj)

Возвращает True, если obj является одним из следующих:

• экземпляром asyncio.Future,
• экземпляром asyncio.Task,
• объектом, подобным Future, с атрибутом _asyncio_future_blocking.

Новая функция в версии 3.5.

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

Возвращает:

• аргумент obj как есть, если obj является Future, Task, или объектом, подобным Future (isfuture() используется для проверки).
• объект Task, оборачивающий obj, если obj — это корутина (iscoroutine() используется для проверки); в этом случае корутина будет запланирована ensure_future().
• объект Task, который бы ожидал obj, если obj — это объект, поддерживающий ожидание (inspect.isawaitable() используется для проверки).

Если obj ни то, ни другое, то генерируется исключение TypeError.

Важно

См. также функцию create_task(), которая является предпочтительным способом создания новых задач.

Сохраняйте ссылку на результат этой функции, чтобы избежать исчезновения задачи во время выполнения.

Изменено в версии 3.5.1: Функция принимает любой объект awaitable.

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

Оборачивает объект concurrent.futures.Future в объект asyncio.Future.

Объект Future

class asyncio.Future(*, loop=None)

Объект Future представляет собой конечный результат асинхронной операции. Не потокобезопасен.

Future является awaitable объектом. Корутины могут ожидать выполнения Future-объектов, пока те не получат результат или исключение, или пока не будут отменены.

Как правило, Future используются для обеспечения взаимодействия низкоуровневого кода на основе обратных вызовов (например, в протоколах, реализованных с помощью asyncio транспортов) с высокоуровневым кодом async/await.

Правило гласит, что Future-объекты никогда не должны быть доступны в API, ориентированных на пользователя, и рекомендуемый способ создания Future-объекта — вызов loop.create_future(). Таким образом, альтернативные реализации цикла событий могут вставлять свои собственные оптимизированные реализации объекта Future.

Изменено в версии 3.7: Добавлена поддержка модуля contextvars.

result()

Возвращает результат Future.

Если Future завершён и имеет установленный результат методом set_result(), возвращается значение результата.

Если Future завершён и имеет установленное исключение методом set_exception(), этот метод вызывает исключение.

Если Future был отменён, этот метод вызывает исключение CancelledError.

Если результат Future ещё недоступен, этот метод вызывает исключение InvalidStateError.

set_result(result)

Помечает Future как завершённый и устанавливает его результат.

Вызывает ошибку InvalidStateError, если Future уже завершён.

set_exception(exception)

Помечает Future как завершённый и устанавливает исключение.

Вызывает ошибку InvalidStateError, если Future уже завершён.

done()

Возвращает True, если Future завершён.

Future считается завершённым, если он был отменён или если для него был установлен результат или исключение с помощью вызовов set_result() или set_exception().

cancelled()

Возвращает True, если Future был отменён.

Метод обычно используется для проверки того, что Future не отменён перед установкой результата или исключения для него:

if not fut.cancelled():
    fut.set_result(42)

add_done_callback(callback, *, context=None)

Добавляет обратный вызов, который будет выполнен, когда Future завершён.

Обратный вызов вызывается с Future-объектом в качестве единственного аргумента.

Если Future уже завершён при вызове этого метода, обратный вызов планируется с помощью loop.call_soon().

Необязательный ключевой аргумент context позволяет указать пользовательский contextvars.Context для выполнения обратного вызова. Текущий контекст используется, если параметр context не задан.

functools.partial() можно использовать для передачи параметров обратному вызову, например:

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

Изменено в версии 3.7: Добавлен ключевой параметр context. Подробнее см. PEP 567.

remove_done_callback(callback)

Удаляет callback из списка обратных вызовов.

Возвращает количество удалённых обратных вызовов, которое обычно равно 1, если обратный вызов был добавлен более одного раза.

cancel(msg=None)

Отменяет Future и планирует обратные вызовы.

Если Future уже завершён или отменён, возвращается False. В противном случае, состояние Future изменяется на отменённый, планируются обратные вызовы, и возвращается True.

Изменено в версии 3.9: Добавлен параметр msg.

exception()

Возвращает исключение, которое было установлено для этого Future.

Исключение (или None, если исключение не было установлено) возвращается только если Future завершён.

Если Future был отменён, этот метод вызывает исключение CancelledError.

Если Future ещё не завершён, этот метод вызывает исключение InvalidStateError.

get_loop()

Возвращает цикл событий, к которому привязан объект Future.

Добавлен в версии 3.7.

В этом примере создаётся объект Future, создаётся и планируется асинхронная задача для установки результата для Future и ожидается, пока Future не получит результат:

async def set_after(fut, delay, value):
    # Sleep for *delay* seconds.
    await asyncio.sleep(delay)

    # Set *value* as a result of *fut* Future.
    fut.set_result(value)

async def main():
    # 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(await fut)

asyncio.run(main())