Futures

Källkod: Lib/asyncio/futures.py, Lib/asyncio/base_futures.py

Future-objekt används för att överbrygga kallelsebaserad kod på låg nivå med async/await-kod på hög nivå.

Framtida funktioner

asyncio.isfuture(obj)

Returnera True om obj är något av:

Tillagd i version 3.5.

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

Returnera:

  • obj argument som det är, om obj är en Future, en Task, eller ett Future-liknande objekt (isfuture() används för testet.)

  • ett Task-objekt som omsluter obj, om obj är en coroutine (iscoroutine() används för testet); i detta fall kommer coroutinen att schemaläggas med ensure_future().

  • ett Task-objekt som skulle awaita på obj, om obj är en awaitable (inspect.isawaitable() används för testet.)

Om obj inte är någon av de ovan nämnda händelserna uppstår ett TypeError.

Viktigt

Spara en referens till resultatet av denna funktion, för att undvika att en uppgift försvinner mitt under utförandet.

Se även funktionen create_task() som är det föredragna sättet att skapa nya uppgifter eller använd asyncio.TaskGroup som håller referensen till uppgiften internt.

Ändrad i version 3.5.1: Funktionen accepterar alla awaitable-objekt.

Föråldrad sedan version 3.10: Deprecation-varning utfärdas om obj inte är ett Future-liknande objekt och loop inte anges och det inte finns någon pågående händelseslinga.

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

Packa in ett concurrent.futures.Future-objekt i ett asyncio.Future-objekt.

Föråldrad sedan version 3.10: Deprecation-varning utfärdas om future inte är ett Future-liknande objekt och loop inte anges och det inte finns någon pågående händelseslinga.

Framtida objekt

class asyncio.Future(*, loop=None)

En Future representerar ett eventuellt resultat av en asynkron operation. Inte tråd-säker.

Future är ett awaitable-objekt. Coroutines kan vänta på Future-objekt tills de antingen har ett resultat eller ett undantag inställt, eller tills de avbryts. En Future kan väntas flera gånger och resultatet blir detsamma.

Futures används vanligtvis för att göra det möjligt för callback-baserad kod på låg nivå (t.ex. i protokoll som implementeras med asyncio transports) att samverka med async/await-kod på hög nivå.

Tumregeln är att aldrig exponera Future-objekt i API:er som vänder sig till användare, och det rekommenderade sättet att skapa ett Future-objekt är att anropa loop.create_future(). På så sätt kan alternativa implementeringar av händelseslingor injicera sina egna optimerade implementeringar av ett Future-objekt.

Ändrad i version 3.7: Lagt till stöd för modulen contextvars.

Föråldrad sedan version 3.10: Deprecation-varning utfärdas om loop inte anges och det inte finns någon pågående händelseslinga.

result()

Returnera resultatet av Future.

Om Future är done och har ett resultat som ställts in med metoden set_result(), returneras resultatvärdet.

Om Future är done och har ett undantag som ställts in med metoden set_exception(), kommer undantaget att tas upp med denna metod.

Om framtiden har avbrutits, ger denna metod upphov till ett CancelledError-undantag.

Om framtidens resultat ännu inte är tillgängligt, ger denna metod upphov till ett InvalidStateError-undantag.

set_result(result)

Markera Future som utförd och ange dess resultat.

Utlöser ett InvalidStateError-fel om Future redan är done.

set_exception(exception)

Markera Future som done och ställ in ett undantag.

Utlöser ett InvalidStateError-fel om Future redan är done.

done()

Returnerar True om framtiden är done.

En Future är done om den cancelled eller om den har ett resultat eller ett undantag som ställts in med set_result() eller set_exception() anrop.

cancelled()

Returnerar True om Framtiden var avbruten.

Metoden används vanligtvis för att kontrollera om en Future inte är cancelled innan ett resultat eller ett undantag anges för den:

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

Lägg till en återuppringning som ska köras när Future är done.

Callback anropas med Future-objektet som enda argument.

Om Future redan är färdig när den här metoden anropas, schemaläggs återuppringningen med loop.call_soon().

Ett valfritt argument context med endast nyckelord gör det möjligt att ange en anpassad contextvars.Context som callback ska köras i. Den aktuella kontexten används när ingen kontext anges.

functools.partial() kan användas för att skicka parametrar till återuppringningen, t.ex.:

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

Ändrad i version 3.7: Parametern context (endast nyckelord) har lagts till. Se PEP 567 för mer information.

remove_done_callback(callback)

Ta bort callback från listan över callbacks.

Returnerar antalet borttagna återuppringningar, vilket vanligtvis är 1, såvida inte en återuppringning har lagts till mer än en gång.

cancel(msg=None)

Avbryt Future och schemalägg callbacks.

Om framtiden redan är done eller cancelled, returneras False. I annat fall ändras Framtidens tillstånd till avbruten, schemalägger återuppringningarna och returnerar True.

Ändrad i version 3.9: Parametern msg har lagts till.

exception()

Returnerar det undantag som ställdes in för denna Future.

Undantaget (eller None om inget undantag har angetts) returneras endast om Future är done.

Om framtiden har avbrutits, ger denna metod upphov till ett CancelledError-undantag.

Om Future inte är färdig ännu, ger denna metod upphov till ett InvalidStateError-undantag.

get_loop()

Returnerar den händelseslinga som Future-objektet är bundet till.

Tillagd i version 3.7.

I det här exemplet skapas ett Future-objekt, en asynkron Task skapas och schemaläggs för att ange resultat för Future och väntar tills Future har ett resultat:

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

Viktigt

Future-objektet har utformats för att efterlikna concurrent.futures.Future. Viktiga skillnader inkluderar: