비동기 지원

Django has support for writing asynchronous (“async”) views, along with an entirely async-enabled request stack if you are running under ASGI. Async views will still work under WSGI, but with a small per-request adaptation cost (see 성능), and without the ability to have efficient long-running requests.

Many parts of Django provide asynchronous APIs, including the ORM, the cache framework, authentication, sessions, and signals. For other code, the sync_to_async() adapter is a low-cost bridge (see 성능). A wide range of async-native Python libraries can also be integrated.

비동기 뷰

모든 뷰는 비동기로 선언될 수있다. 일반적으로 ``async def``를 사용해 뷰의 호출 가능 부분이 coroutine을 반환하도록 하면 된다. 즉, 함수 기반 뷰의 경우 전체 함수에 ``async def``를, 클래스 기반 뷰는 내부 ``get()``과 ``post()``와 같은 HTTP 요청 처리 메서드( ``__init__()``나 ``as_view()``가 아닌)에 ``async def``를 사용하는 것을 의미한다.

참고

장고는 ``asgiref.sync.iscoroutinefunction``으로 뷰의 비동기 여부를 검사한다. corutine을 반환하는 별도의 방법을 적용한 경우 ``asgiref.sync.markcoroutinefunction``을 사용하여 위 함수가 ``True``를 반환하도록 하자.

WSGI 서버에서, 비동기 view는 자체 일회성 이벤트 루프에서 실행된다. 문제 없이 비동기 동시성 HTTP 요청과 같은 기능을 사용할 수 있으나 비동기식 스택의 장점은 얻을 수 없다.

주요 이점은 수백개의 연결을 Python 스레드를 이용하지 않고 서비스를 할 수 있는 것이다. 이는 느린 스트리밍, 긴 폴링과 다른 흥미로운 응답 유형을 사용할 수 있도록 한다.

이를 이용하고 싶다면, :doc:`ASGI를 이용하여 Django를 배포해야한다.

참고

A fully asynchronous request stack requires async middleware end-to-end. Where a piece of synchronous middleware sits between an ASGI server and an async view, Django adapts it by running it in its own thread; see 성능 for the cost trade-off.

Django’s bundled middleware supports both sync and async. Third-party middleware may not. To see which middleware Django adapts, turn on debug logging for the django.request logger and look for log messages about “Asynchronous handler adapted for middleware …”.

ASGI와 WSGI 모드에서 모두, 연속적으로보다 코드를 동시에 실행하여 비동기식 지원을 안전하게 사용할 수 있다. 외부 API나 데이터 저장소를 다룰 때 특히 유용하다

아직 동기식로 되어있는 장고 요소를 호출하고 싶다면 해당 요소를 sync_to_async() 호출로 wrapping해야 한다. 예:

from asgiref.sync import sync_to_async

results = await sync_to_async(sync_function, thread_sensitive=True)(pk=123)

장고의 요소 중 동기 전용 요소를 비동기 뷰에서 호출할 경우 비동기 안전 보호 발생시키게 되는데 이는 데이터 손상 방지를 위함이다.

데코레이터

아래 목록의 데코레이터는 동기와 비동기 뷰 함수 모두에서 사용할 수 있습니다.

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

• conditional_page()

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

예시:

from django.views.decorators.cache import never_cache


@never_cache
def my_sync_view(request): ...


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

쿼리 & ORM

With some exceptions, Django can run ORM queries asynchronously:

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

자세한 내용은 :ref:`async-queries`에서 확인 가능하다. 요약하면:

• SQL 쿼리를 발생시키는 ``QuerySet``의 모든 메서드는 접두사 ``a``가 붙은 비동기 메서드가 있다.

• 모든 QuerySets(``values()``와 ``values_list()``의 결과 값 포함)에서 ``async for``가 지원된다.

Asynchronous model methods that use the database are also supported:

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)

아직 트랜잭션 처리는 비동기로 동작하지 않는다. 코드 중 트랙젝션으로 처리가 필요한 부분에 대해서는 별도 동기 함수로 작성한 다음 :func:`sync_to_async`를 사용해 호출하자.

Persistent database connections, set via the CONN_MAX_AGE setting, should also be disabled in async mode. Instead, use your database backend’s built-in connection pooling if available, or investigate a third-party connection pooling option if required. As in synchronous Django, concurrent requests in a single process share that pool, so size it to the target in-flight query concurrency.

성능

When running in a mode that does not match the view (e.g. an async view under WSGI, or a traditional sync view under ASGI), Django must emulate the other call style to allow your code to run. The per-call cost of this adaptation is small: tens of microseconds in the in-request ASGI path, where the running event loop is reused, and a few hundred microseconds in the cold-start path used by management commands, background tasks, and scripts. Against typical request times measured in milliseconds, this is rarely visible in itself, but can become so under GIL contention as the number of active threads grows.

If you find yourself wrapping individual rows or operations in a tight loop, restructure your code so the loop runs inside a single sync_to_async() (or async_to_sync()) crossing. The per-call cost of the context switch is then spread across the whole loop and effectively disappears.

The same per-call adaptation cost applies to middleware. Django will attempt to minimize the number of context-switches between sync and async. If you have an ASGI server, but all your middleware and views are synchronous, it will switch just once, before it enters the middleware stack.

However, if you put synchronous middleware between an ASGI server and an asynchronous view, it will have to switch into sync mode for the middleware and then back to async mode for the view. Django will also hold the sync thread open for middleware exception propagation. For request/response views that hit the ORM and return, this is not usually a meaningful penalty. It matters most when you are using ASGI for high in-process concurrency over non-ORM I/O (for example upstream HTTP fan-out, server-sent events, or other long-lived requests), where the extra thread per request caps that concurrency.

ASGI와 WSGI 코드에 어떤 영향을 끼치는지 자체 성능 테스팅을 해야한다. 일부 케이스에서는 요청 핸들링 코드는 여전히 비동기식으로 실행되고 있기 때문에 심지어 순전히 ASGI 서버에서의 동기식 코드베이스이나 성능이 향상될 수 있다. 일반적인 경우, 비동기식 코드가 프로젝트에 있는 경우에만 ASGI 모드를 쓸 수 있게 하다.

Handling disconnects

For long-lived requests, a client may disconnect before the view returns a response. In this case, an asyncio.CancelledError will be raised in the view. You can catch this error and handle it if you need to perform any cleanup:

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

You can also handle client disconnects in streaming responses.

비동기 안전성

DJANGO_ALLOW_ASYNC_UNSAFE

Certain key parts of Django are not able to operate safely in an async environment, as they have global state that is not coroutine-aware. These parts of Django are classified as “async-unsafe”, and are protected from execution in an async environment. The synchronous API of the ORM is the main example, but there are other parts that are also protected in this way.

“running event loop”가 있는 스레드에서 이러한 부분을 실행하고자 하면, SynchronousOnlyOperation error가 발생한다. 이 오류를 발생하기 위해서 비동기식 함수 내부에 직접적으로 있을 필요가 없다. 동기식 함수에서 동기식 함수를 직접적으로 호출하면, :func:`sync_to_async`을 사용하지 않고도 오류가 발생할 수 있다. 비동기식 코드로 선언되었음에도 불구하고, 활성 이벤트 루프가 있는 스레드 안에서 코드는 여전히 실행중이기 때문이다.

오류가 발생하면, 비동식 컨텍스트에서 문제가 있는 코드를 호출하지 않도록 코드를 수정해야 한다. 대신에, 자체적인 비동기식의 안전하지 않은 함수와 동기식 함수와 통신하는 코드를 작성하고, :func:`asgiref.sync.sync_to_async`(또는 자체 스레드에서 동기식 코드를 실행하는 다른 방법)을 이용하여 호출한다.

비동기식 컨텍스트는 django 코드를 실행하는 환경에 의해 부과될 수 있다. 예를 들어, Jupyter notebooks and IPython interactive shells 모두 비동기식 API와 상호작용을 더 쉽게 할 수 있도록 투명하게 활성 이벤트 루프를 제공한다.

IPython shell의 경우 아래와 같이 이벤트 루프를 비활성화 할 수 있다:

%autoawait off

IPython 프롬프트에 이 명령을 입력하면 동기 전용 코드를 SynchronousOnlyOperation 에러 없이 실행가능하다. 반면 비동기 API들에 대해서는 ``await``와 함께 사용할 수 없게 된다. 다시 이벤트 루프를 활성화하려면 다음을 실행한다:

%autoawait on

If you’re in an environment other than IPython (or you can’t turn off autoawait in IPython for some reason), you are certain there is no chance of your code being run concurrently, and you absolutely need to run your sync code from an async context, then you can disable the warning by setting the DJANGO_ALLOW_ASYNC_UNSAFE environment variable to any value.

경고

이 옵션을 쓸 수 있게 하고 안전하지 않은 비동기식 django의 부분으로 동시 접속이 있다면, 데이터 손실이나 오염을 입을 수 있다. 매우 주의 해야하고 프로덕션 환경에서 사용하지 않는다.

파이썬 내에서 수행해야한다면, ``os.environ``으로 수행한다.:

import os

os.environ["DJANGO_ALLOW_ASYNC_UNSAFE"] = "true"

비동기식 어댑터 함수

비동기식 컨텍스트에서의 동기식 코드를 호출할 때, 또는 그 반대의 경우일 때, 호출 방식을 어댑트하는 것이 필요하다. 이를 위해 asgiref.sync 모듈에 async_to_sync() and sync_to_async() 두 개의 어댑터 함수가 있다. 호환성을 유지하면서 호출 방식을 전환하는 데에 사용한다.

이 어댑터 함수들은 장고에서 광범위하게 사용된다. asgiref 패키지는 장고 프로젝트의 일부이며 ``pip``으로 장고를 설치 시 의존 패키지로 자동 설치된다.

async_to_sync()

async_to_sync(async_function, force_new_loop=False)

비동기식 함수를 사용하고, 이를 감싼 동기식 함수를 반환하다. 직접적인 래퍼나 데코레이터 모두 쓰일 수 있다.:

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

이벤트 루프가 존재한다면, 비동기식 함수는 현재의 스레드에 대한 이벤트 루프에서 실행된다. 현재의 이벤트 루프가 없다면, 새로운 이벤트 루프가 단일 비동기식 호출에 대해서만 스핀업 하고, 완료하면 다시 종료된다. 두 상황 모두, 비동기식 함수는 호출 코드에 대한 다른 스레드에서 실행될 것이다.

Threadlocals와 contextvars 값은 양 방향의 경계를 넘어 유지된다.

async_to_sync() is essentially a more powerful version of the asyncio.run() function in Python’s standard library. As well as ensuring threadlocals work, it also enables the thread_sensitive mode of sync_to_async() when that wrapper is used below it. In the cold path (no running event loop) it pays the cost of starting a fresh event loop, like asyncio.run(); when an event loop is already running (the in-request ASGI case), the running loop is reused and the cost drops accordingly.

sync_to_async()

sync_to_async(sync_function, thread_sensitive=True)

동기식 함수를 사용하고, 이를 감싼 비동기식 함수를 반환하다. 직접적인 래퍼나 데코레이터 모두 쓰일 수 있다.:

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

Threadlocals와 contextvars 값은 양 방향의 경계를 넘어 유지된다.

동기식 함수는 메인 스레드에서 모두 실행된다고 가정하여 쓰이는 경향이 있어서, :func:`sync_to_async`는 두 개의 스레딩 모드를 가진다.

• thread_sensitive=True (디폴트): 동기식 함수는 다른 모든``thread_sensitive`` 함수처럼 같은 스레드에서 실행할 것이다. 만일, 메인 스레드가 동기식이고 async_to_sync() 래퍼를 이용하면, 이것이 메인 스레드일 것이다.

• thread_sensitive=False: 동기식 함수는 호출이 한 번 완료하면 종료되는 완전 새로운 스레드에서 실행될 것이다.

Thread-sensitive 모드는 특별하고, 같은 스레드의 모든 함수를 실행하기 위해 많은 작업을 수행한다. 그럼에도 불구하고, 메인 스레드에서 올바르게 실행하기 위해 스택에서 async_to_sync`의 *용례를 필요로 하다*. ``asyncio.run()`() 또는 유사한 것을 사용한다면, 단일의, 공유되는 스레드의 thread-sensitive 함수를 실행하는 것으로 돌아갈 것이지만, 이는 메인 스레드는 아닐 것이다.

django에서 필요한 이유는 많은 라이브러리들 중 특히 데이터베이스 어댑터들은, 라이브러리들이 생성된 같은 스레드에 액세스하는 것을 필요로 하기 때문이다. 또한 기존의 많은 django 코드는 같은 스레드에서 모두 실행하는 것을 가정하고, 예를 들어, 미들웨어는 뷰에서 이후에 사용할 것을 위한 것을 요청에 추가한다

이 코드의 잠재적인 호환성 문제를 내놓는 것 대신에, 존재하는 모든 django 동기식 코드가 같은 스레드에서 실행하고 비동기식 모드와 완전히 호환이 될 수 있도록 이 모드를 추가하기로 선택하였다. 동기식 코드는 항상 호출하는 비동기식 코드와 다른 스레드에 있으므로, 원시 데이터베이스 핸들이나 다른 thread-sensitive 참조를 전달하지 않아야 한다.

Within a single request, multiple thread_sensitive calls serialize on that request’s worker thread, but each request gets its own per-context worker, so concurrent requests do not serialize against each other. This mirrors Django’s connection-per-thread model, and the same constraint applies in other async database libraries, where concurrent queries on a single connection serialize on a lock. To support more concurrent requests, increase the connection pool size accordingly rather than disabling thread_sensitive.

즉, 실 사용 시 데이터베이스 connection 객체의 기능들을 ``sync_to_async()``에 전달해서는 안된다. 전달할 경우 스레드 안정성 검사를 일으킨다.:

# 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.

Rather, you should encapsulate all database access within a helper function that can be called with sync_to_async() without relying on the connection object in the calling code.