Краткий ответ

asyncio.to_thread запускает синхронную функцию в отдельном потоке из пула исполнителя, поэтому она не выполняется в потоке event loop. Event loop ожидает результат через объект, совместимый с asyncio, и может в это время обслуживать другие корутины.

Исторический контекст

Асинхронная модель эффективна, когда операции ввода-вывода представлены неблокирующими awaitable-объектами. Однако приложения часто используют старые или сторонние библиотеки с обычными блокирующими функциями, которые нельзя быстро переписать на нативный asyncio.

Для таких случаев в Python существовал запуск функций через исполнитель потоков, а asyncio.to_thread предоставил более удобный высокоуровневый способ перенести синхронную работу из event loop в поток.

Постановка проблемы

Если вызвать блокирующую функцию непосредственно внутри корутины, поток event loop остановится до её завершения. Все другие задачи, обслуживаемые этим loop, будут ждать, даже если сами готовы продолжать выполнение.

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

Подробное решение

При вызове asyncio.to_thread синхронная функция планируется для выполнения в отдельном рабочем потоке. Корутина получает awaitable-результат и приостанавливается, не занимая поток event loop; после завершения функции её результат или исключение передаются обратно в корутину.

import asyncio
import time

def blocking_io():
    time.sleep(1)
    return 'готово'

async def heartbeat():
    for _ in range(3):
        print('event loop работает')
        await asyncio.sleep(0.3)

async def main():
    result, _ = await asyncio.gather(
        asyncio.to_thread(blocking_io), heartbeat()
    )
    print(result)

asyncio.run(main())

Пока blocking_io ожидает в рабочем потоке, heartbeat продолжает выполняться в event loop. Вызов to_thread сам по себе возвращает корутину; фактическое планирование функции происходит, когда эта корутина начинает выполняться, например через await или asyncio.gather.

to_thread особенно полезен для блокирующего ввода-вывода: файлов, синхронных сетевых клиентов, архиваторов или библиотек, не поддерживающих asyncio. Для CPU-bound кода в CPython перенос в поток обычно не даёт настоящего параллельного ускорения из-за GIL; для такой нагрузки чаще рассматривают процессы или нативные расширения, освобождающие GIL.

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

Ситуация из практики

Асинхронный HTTP-сервис использует библиотеку для чтения документов, у которой API полностью синхронный. Прямой вызов внутри обработчика периодически задерживает ответы всем клиентам, потому что блокирует event loop.

Можно переписать библиотеку или заменить её на асинхронную: это обычно даёт лучшую масштабируемость, но требует времени и может изменить поведение системы. Можно использовать процессы, однако для обычного ввода-вывода это сложнее и создаёт дополнительные расходы на межпроцессное взаимодействие.

Практичным решением становится ограниченный по конкуренции вызов через asyncio.to_thread. Он сохраняет существующую библиотеку и освобождает event loop, а ограничение числа одновременно отправленных операций предотвращает переполнение пула и внешней системы. Для CPU-bound обработки документов такой выбор был бы неоптимален: там следует отдельно оценить процессы или библиотеку, освобождающую GIL.

Что кандидаты часто упускают

Останавливает ли отмена задачи asyncio функцию, выполняющуюся в рабочем потоке?

Нет. Отмена прерывает ожидание результата вызывающей asyncio-задачей и обычно приводит к CancelledError, но уже запущенный поток не получает гарантированного механизма принудительной остановки. Функция может изменить состояние, завершить запись или освободить ресурсы уже после отмены.

Поэтому блокирующая функция должна по возможности поддерживать собственные тайм-ауты, безопасное завершение и идемпотентность. Нельзя считать отмену корутины доказательством того, что внешняя операция прекратилась.

Даст ли to_thread ускорение для чистого CPU-bound Python-кода в CPython?

Обычно нет. Потоки могут выполняться конкурентно, но GIL ограничивает одновременное выполнение Python-байткода несколькими потоками, поэтому вычислительная задача чаще не ускоряется и дополнительно получает накладные расходы на переключение.

Исключение возможно для кода нативного расширения, которое освобождает GIL во время вычислений. Для независимых CPU-bound задач на чистом Python обычно рассматривают ProcessPoolExecutor или отдельные процессы, принимая расходы на сериализацию и межпроцессный обмен.

Какие данные безопасно использовать внутри функции, переданной в рабочий поток?

Передача функции в поток не делает общие объекты потокобезопасными. Обычные изменяемые структуры, например словари и списки, могут одновременно читаться и изменяться несколькими потоками; для составных операций нужны синхронизация или другая схема владения данными.

При этом контекстные переменные contextvars при использовании asyncio.to_thread копируются в рабочий поток на момент запуска. Это удобно для идентификаторов запроса и других контекстных значений, но изменения контекста в рабочем потоке не становятся автоматической двусторонней синхронизацией с исходной корутиной.