Futures

Quellcode: Lib/asyncio/futures.py, Lib/asyncio/base_futures.py

Future-Objekte werden verwendet, um **Callback-basierten Low-Level-Code** mit High-Level-Async/Await-Code zu verbinden.

Zukunftsfunktionen

asyncio.isfuture(obj)

Gibt True zurück, wenn obj eines der folgenden ist:

  • eine Instanz von asyncio.Future,

  • eine Instanz von asyncio.Task,

  • ein zukunftsähnliches Objekt mit einem Attribut _asyncio_future_blocking.

Hinzugefügt in Version 3.5.

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

Gibt das obj-Argument unverändert zurück, wenn obj ein Future, ein Task oder ein zukunftsähnliches Objekt ist (für den Test wird isfuture() verwendet).

  • Gibt das obj-Argument unverändert zurück, wenn obj ein Future, ein Task oder ein zukunftsähnliches Objekt ist (isfuture() wird für den Test verwendet).

  • ein Task-Objekt, das obj umschließt, wenn obj eine Coroutine ist (iscoroutine() wird für den Test verwendet); in diesem Fall wird die Coroutine von ensure_future() geplant.

  • ein Task-Objekt, das auf obj wartet, wenn obj ein Awaitable ist (inspect.isawaitable() wird für den Test verwendet).

Wenn obj keiner der oben genannten Typen ist, wird ein TypeError ausgelöst.

Wichtig

Speichern Sie eine Referenz auf das Ergebnis dieser Funktion, um zu verhindern, dass eine Aufgabe mitten in der Ausführung verschwindet.

Siehe auch die Funktion create_task(), die die bevorzugte Methode zum Erstellen neuer Aufgaben ist, oder verwenden Sie asyncio.TaskGroup, die die Referenz auf die Aufgabe intern speichert.

Geändert in Version 3.5.1: Die Funktion akzeptiert jedes awaitable-Objekt.

Veraltet seit Version 3.10: Eine Deprecation-Warnung wird ausgegeben, wenn obj kein zukunftsähnliches Objekt ist und loop nicht angegeben ist und keine laufende Ereignisschleife vorhanden ist.

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

Wickelt ein concurrent.futures.Future-Objekt in ein asyncio.Future-Objekt.

Veraltet seit Version 3.10: Eine Deprecation-Warnung wird ausgegeben, wenn future kein zukunftsähnliches Objekt ist und loop nicht angegeben ist und keine laufende Ereignisschleife vorhanden ist.

Future-Objekt

class asyncio.Future(*, loop=None)

Ein Future repräsentiert ein zukünftiges Ergebnis einer asynchronen Operation. Nicht threadsicher.

Future ist ein awaitable-Objekt. Coroutinen können auf Future-Objekte warten, bis sie entweder ein Ergebnis oder eine Ausnahme gesetzt haben oder bis sie abgebrochen wurden. Ein Future kann mehrmals abgefragt werden und das Ergebnis ist dasselbe.

Futures werden typischerweise verwendet, um Callback-basierten Low-Level-Code (z. B. in Protokollen, die mit asyncio Transports implementiert sind) mit High-Level-Async/Await-Code interoperabel zu machen.

Die Faustregel ist, niemals Future-Objekte in benutzersichtbaren APIs preiszugeben. Die empfohlene Methode zum Erstellen eines Future-Objekts ist der Aufruf von loop.create_future(). Auf diese Weise können alternative Ereignisschleifenimplementierungen ihre eigenen optimierten Implementierungen eines Future-Objekts injizieren.

Geändert in Version 3.7: Unterstützung für das Modul contextvars hinzugefügt.

Veraltet seit Version 3.10: Eine Deprecation-Warnung wird ausgegeben, wenn loop nicht angegeben ist und keine laufende Ereignisschleife vorhanden ist.

result()

Gibt das Ergebnis des Future zurück.

Wenn das Future done ist und ein Ergebnis durch die Methode set_result() gesetzt wurde, wird der Ergebniswert zurückgegeben.

Wenn das Future done ist und eine Ausnahme durch die Methode set_exception() gesetzt wurde, löst diese Methode die Ausnahme aus.

Wenn das Future *abgebrochen* wurde, löst diese Methode eine CancelledError-Ausnahme aus.

Wenn das Ergebnis des Future noch nicht verfügbar ist, löst diese Methode eine InvalidStateError-Ausnahme aus.

set_result(result)

Markiert das Future als done und setzt sein Ergebnis.

Löst eine InvalidStateError aus, wenn das Future bereits done ist.

set_exception(exception)

Markiert das Future als done und setzt eine Ausnahme.

Löst eine InvalidStateError aus, wenn das Future bereits done ist.

done()

Gibt True zurück, wenn das Future done ist.

Ein Future ist done, wenn es *abgebrochen* wurde oder wenn es ein Ergebnis oder eine Ausnahme hat, die mit den Methoden set_result() oder set_exception() gesetzt wurde.

cancelled()

Gibt True zurück, wenn das Future *abgebrochen* wurde.

Die Methode wird normalerweise verwendet, um zu überprüfen, ob ein Future nicht *abgebrochen* wurde, bevor ihm ein Ergebnis oder eine Ausnahme zugewiesen wird.

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

Fügt einen Callback hinzu, der aufgerufen werden soll, wenn das Future done ist.

Der callback wird mit dem Future-Objekt als einzigem Argument aufgerufen.

Wenn das Future bereits done ist, wenn diese Methode aufgerufen wird, wird der Callback mit loop.call_soon() geplant.

Ein optionales Keyword-only context-Argument ermöglicht die Angabe eines benutzerdefinierten contextvars.Context, in dem der callback ausgeführt werden soll. Der aktuelle Kontext wird verwendet, wenn kein context angegeben wird.

functools.partial() kann verwendet werden, um Parameter an den Callback zu übergeben, z. B.

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

Geändert in Version 3.7: Das Keyword-only-Parameter context wurde hinzugefügt. Siehe PEP 567 für weitere Details.

remove_done_callback(callback)

Entfernt callback aus der Callback-Liste.

Gibt die Anzahl der entfernten Callbacks zurück, was typischerweise 1 ist, es sei denn, ein Callback wurde mehrmals hinzugefügt.

cancel(msg=None)

Bricht das Future ab und plant die Callbacks.

Wenn das Future bereits done oder cancelled ist, wird False zurückgegeben. Andernfalls wird der Zustand des Future auf cancelled geändert, die Callbacks werden geplant und es wird True zurückgegeben.

Geändert in Version 3.9: Der Parameter msg wurde hinzugefügt.

exception()

Gibt die Ausnahme zurück, die für dieses Future gesetzt wurde.

Die Ausnahme (oder None, wenn keine Ausnahme gesetzt wurde) wird nur zurückgegeben, wenn das Future done ist.

Wenn das Future *abgebrochen* wurde, löst diese Methode eine CancelledError-Ausnahme aus.

Wenn das Future noch nicht done ist, löst diese Methode eine InvalidStateError-Ausnahme aus.

get_loop()

Gibt die Ereignisschleife zurück, an die das Future-Objekt gebunden ist.

Hinzugefügt in Version 3.7.

Dieses Beispiel erstellt ein Future-Objekt, erstellt und plant eine asynchrone Aufgabe, um das Ergebnis für das Future zu setzen, und wartet, bis das Future ein Ergebnis hat.

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())

Wichtig

Das Future-Objekt wurde so konzipiert, dass es concurrent.futures.Future imitiert. Wesentliche Unterschiede sind: