Asynkront stödLink to this heading#

DekoratörerLink to this heading#

Följande dekoratorer kan användas med både synkrona och asynkrona vyfunktioner:

• cache_control()

• never_cache()

• no_append_slash()

• csp_override()

• csp_report_only_override()

• csrf_exempt()

• csrf_protect()

• ensure_csrf_cookie()

• requires_csrf_token()

• sensitive_variables()

• sensitive_post_parameters()

• gzip_page()

• condition()

• villkorlig_sida()

• etag()

• last_modified()

• require_http_methods()

• require_GET()

• require_POST()

• require_safe()

• vary_on_cookie()

• vary_on_headers()

• xframe_options_deny()

• xframe_options_sameorigin()

• xframe_options_exempt()

Till exempel:

from django.views.decorators.cache import never_cache


@never_cache
def my_sync_view(request): ...


@never_cache
async def my_async_view(request): ...

method_decorator() kan användas med asynkrona metoder, inklusive async def-vyhanterare. Observera dock att om du dekorerar dispatch() på en View med asynkrona hanterare måste du också åsidosätta dispatch så att den blir async def:

class MyClass(View):
    @method_decorator(never_cache)
    async def dispatch(self, *args, **kwargs):
        return super().dispatch(*args, **kwargs)

    async def get(self, request): ...

    async def post(self, request): ...

Eftersom vi här dekorerar dispatch i stället för de enskilda hanteringsmetoderna måste vi göra dispatch asynkron så att method_decorator kan markera den resulterande metoden korrekt som en korutinfunktion.

Frågor och ORMLink to this heading#

Med vissa undantag kan Django köra ORM-frågor asynkront:

async for author in Author.objects.filter(name__startswith="A"):
    book = await author.books.afirst()

Detaljerade anvisningar finns i Asynkrona förfrågningar, men i korthet:

• Alla QuerySet-metoder som orsakar en SQL-fråga har en asynkron variant med a-prefix.

• async for stöds på alla QuerySets (inklusive utdata från values() och values_list().)

Asynkrona modellmetoder som använder databasen stöds också:

async def make_book(*args, **kwargs):
    book = Book(...)
    await book.asave(using="secondary")


async def make_book_with_tags(tags, *args, **kwargs):
    book = await Book.objects.acreate(...)
    await book.tags.aset(tags)

Transaktioner fungerar ännu inte i asynkront läge. Om du har en del av koden som behöver transaktionsbeteende rekommenderar vi att du skriver den delen som en enda synkron funktion och anropar den med sync_to_async().

Beständiga databasanslutningar, som anges med inställningen CONN_MAX_AGE, bör också inaktiveras i asynkront läge. Använd i stället databasbackendens inbyggda anslutningspoolning om den finns tillgänglig, eller undersök ett tredjepartsalternativ för anslutningspoolning om det krävs. Precis som i synkront Django delar samtidiga begäranden i en process den poolen, så dimensionera den för den avsedda samtidigheten av pågående frågor.

PrestandaLink to this heading#

När du kör i ett läge som inte motsvarar vyn (t.ex. en asynkron vy under WSGI eller en traditionell synkron vy under ASGI) måste Django emulera den andra anropsstilen för att koden ska kunna köras. Kostnaden per anrop för denna anpassning är liten: tiotals mikrosekunder i ASGI-sökvägen inom begäran, där den körande händelseslingan återanvänds, och några hundra mikrosekunder i kallstartsökvägen som används av hanteringskommandon, bakgrundsuppgifter och skript. Jämfört med typiska begärandetider på millisekunder märks detta sällan i sig, men kan bli märkbart vid GIL-konkurrens när antalet aktiva trådar ökar.

Om du upptäcker att du omsluter enskilda rader eller åtgärder i en snäv loop bör du strukturera om koden så att loopen körs inom en enda övergång med sync_to_async() (eller async_to_sync()). Kostnaden per anrop för kontextväxlingen fördelas då över hela loopen och försvinner i praktiken.

Samma anpassningskostnad per anrop gäller för middleware. Django försöker minimera antalet kontextväxlingar mellan synkront och asynkront. Om du har en ASGI-server men all middleware och alla vyer är synkrona växlar den bara en gång, innan den går in i middlewarestacken.

Om du däremot lägger synkron middleware mellan en ASGI-server och en asynkron vy måste den växla till synkront läge för middleware och sedan tillbaka till asynkront läge för vyn. Django håller också den synkrona tråden öppen för spridning av middlewareundantag. För begärande-/svars-vyer som använder ORM och returnerar är detta vanligen ingen betydande kostnad. Det spelar störst roll när du använder ASGI för hög samtidig körning i processen över I/O som inte är ORM (t.ex. vidarebefordran till flera HTTP-källor, server-sända händelser eller andra långlivade begäranden), där den extra tråden per begäran begränsar samtidigheten.

Du bör göra dina egna prestandatester för att se vilken effekt ASGI kontra WSGI har på din kod. I vissa fall kan det finnas en prestandaförbättring även för en rent synkron kodbas under ASGI eftersom all kod som hanterar förfrågningar fortfarande körs asynkront. I allmänhet vill du bara aktivera ASGI-läget om du har asynkron kod i ditt projekt.

Hantering av frånkopplingarLink to this heading#

För långlivade förfrågningar kan en klient koppla från innan vyn returnerar ett svar. I detta fall kommer ett asyncio.CancelledError att uppstå i vyn. Du kan fånga detta fel och hantera det om du behöver utföra någon upprensning:

async def my_view(request):
    try:
        # Do some work
        ...
    except asyncio.CancelledError:
        # Handle disconnect
        raise

Du kan också hantera klientavbrott i strömmande svar.

async_to_sync()Link to this heading#

async_to_sync(async_function, force_new_loop=False)Link to this definition#

Tar en async-funktion och returnerar en sync-funktion som omsluter den. Kan användas som antingen en direkt omslutning eller en dekorator:

from asgiref.sync import async_to_sync


async def get_data(): ...


sync_get_data = async_to_sync(get_data)


@async_to_sync
async def get_other_data(): ...

Async-funktionen körs i händelseslingan för den aktuella tråden, om en sådan finns. Om det inte finns någon aktuell händelseslinga startas en ny händelseslinga specifikt för den enskilda async-inkallningen och stängs av igen när den är klar. I båda situationerna kommer async-funktionen att köras i en annan tråd än den anropande koden.

Värdena för Threadlocals och contextvars bevaras över gränsen i båda riktningarna.

async_to_sync() är i huvudsak en kraftfullare version av funktionen asyncio.run() i Pythons standardbibliotek. Förutom att säkerställa att trådlokala data fungerar aktiverar den också läget thread_sensitive i sync_to_async() när den omslutningen används under den. I den kalla sökvägen (ingen körande händelseslinga) betalar den kostnaden för att starta en ny händelseslinga, precis som asyncio.run(); när en händelseslinga redan körs (ASGI-fallet inom begäran) återanvänds den och kostnaden minskar därefter.

sync_to_async()Link to this heading#

sync_to_async(sync_function, thread_sensitive=True)Link to this definition#

Tar en sync-funktion och returnerar en async-funktion som omsluter den. Kan användas som antingen en direkt omslutning eller en dekorator:

from asgiref.sync import sync_to_async

async_function = sync_to_async(sync_function, thread_sensitive=False)
async_function = sync_to_async(sensitive_sync_function, thread_sensitive=True)


@sync_to_async
def sync_function(): ...

Värdena för Threadlocals och contextvars bevaras över gränsen i båda riktningarna.

Synkroniseringsfunktioner brukar skrivas med antagandet att de alla körs i huvudtråden, så sync_to_async() har två trådningslägen:

• thread_sensitive=True (standard): Synkroniseringsfunktionen körs i samma tråd som alla andra thread_sensitive funktioner. Detta kommer att vara huvudtråden, om huvudtråden är synkron och du använder async_to_sync()-omslaget.

• thread_sensitive=False: Synkroniseringsfunktionen körs i en helt ny tråd som sedan stängs när anropet har slutförts.

Trådkänsligt läge är ganska speciellt och gör en hel del arbete för att köra alla funktioner i samma tråd. Observera dock att det förlitar sig på användning av async_to_sync() över det i stacken för att korrekt köra saker på huvudtråden. Om du använder asyncio.run() eller liknande kommer den att falla tillbaka till att köra trådkänsliga funktioner i en enda, delad tråd, men detta kommer inte att vara huvudtråden.

Anledningen till att detta behövs i Django är att många bibliotek, särskilt databasadaptrar, kräver att de nås i samma tråd som de skapades i. Även en hel del befintlig Django-kod förutsätter att allt körs i samma tråd, t.ex. middleware som lägger till saker i en begäran för senare användning i vyer.

I stället för att införa potentiella kompatibilitetsproblem med den här koden valde vi istället att lägga till det här läget så att all befintlig Django sync-kod körs i samma tråd och därmed är helt kompatibel med async-läget. Observera att synkroniseringskoden alltid kommer att vara i en annan tråd än någon asynkron kod som anropar den, så du bör undvika att skicka råa databashandtag eller andra trådkänsliga referenser runt.

Inom en enskild begäran serialiseras flera thread_sensitive-anrop på begärans arbetstråd, men varje begäran får en egen arbetare per kontext, så samtidiga begäranden serialiseras inte mot varandra. Detta återspeglar Djangos modell med en anslutning per tråd, och samma begränsning gäller i andra asynkrona databasbibliotek där samtidiga frågor på en enda anslutning serialiseras med ett lås. Om du vill stödja fler samtidiga begäranden ökar du anslutningspoolens storlek i stället för att inaktivera thread_sensitive.

I praktiken innebär denna begränsning att du inte bör skicka egenskaper hos databasens connection-objekt när du anropar sync_to_async(). Om du gör det kommer det att utlösa trådsäkerhetskontrollerna:

# DJANGO_SETTINGS_MODULE=settings.py python -m asyncio
>>> import asyncio
>>> from asgiref.sync import sync_to_async
>>> from django.db import connection
>>> # In an async context so you cannot use the database directly:
>>> connection.cursor()
django.core.exceptions.SynchronousOnlyOperation: You cannot call this from
an async context - use a thread or sync_to_async.
>>> # Nor can you pass resolved connection attributes across threads:
>>> await sync_to_async(connection.cursor)()
django.db.utils.DatabaseError: DatabaseWrapper objects created in a thread
can only be used in that same thread. The object with alias 'default' was
created in thread id 4371465600 and this is thread id 6131478528.

Istället bör du kapsla in all databasåtkomst i en hjälpfunktion som kan anropas med sync_to_async() utan att förlita sig på anslutningsobjektet i den anropande koden.