Python asyncio.to_thread 传递上下文变量的边界

Python 异步服务经常用 ContextVar 保存请求 ID、租户标识或日志字段，再把阻塞的文件、压缩和 SDK 调用交给 asyncio.to_thread()。它的边界可以先记成一句话：to_thread 复制当前上下文的绑定，让线程函数能读取；线程里重新绑定不会自动回写事件循环，而上下文中的可变对象仍可能被两个执行单元共同引用。

一、to_thread 传过去的是 Context 的副本

Python 官方文档把 to_thread() 定义为“在单独线程异步运行函数”，并说明当前 contextvars.Context 会传播。CPython 的实现先调用 contextvars.copy_context()，再把同步函数包装成 ctx.run(func, ...)，最后交给默认执行器。

这意味着线程函数可以直接读取调用方已经设置的 ContextVar，但它进入的是一个新的上下文执行栈，不是把事件循环线程的 Context 对象搬过去。上下文变量的“绑定关系”被带过去，生命周期和后续写入仍由各自的执行上下文管理。

二、读取能传递，set() 不会回写

下面的示例只展示语义，不依赖特定线程调度顺序。工作函数能读到 request_id，但它调用 set() 后，事件循环中的值仍然是原来的绑定。

import asyncio
from contextvars import ContextVar

request_id = ContextVar("request_id", default="missing")

def blocking_work():
    # to_thread 会在复制的上下文中执行，因此这里能读到调用方的值。
    before = request_id.get()
    request_id.set("worker-value")
    # set() 只改变工作线程当前的 Context，不修改事件循环线程的绑定。
    return before, request_id.get()

async def main():
    # 请求入口先建立本次任务的上下文绑定。
    request_id.set("request-42")
    worker_before, worker_after = await asyncio.to_thread(blocking_work)
    # 回到事件循环后仍读到 request-42，线程内的重新绑定没有回写。
    print(worker_before, worker_after, request_id.get())

因此，跨线程函数需要返回“线程内计算出的新上下文值”时，应该把它作为普通返回值交给调用方，而不是期待 ContextVar 自动同步。请求 ID 这类只读元数据适合传播；线程要产生状态变化时，应显式返回结果或使用有明确并发约束的共享对象。

三、不可变绑定与可变对象不是一回事

copy_context() 复制的是变量到值的映射。若值是字符串、整数或不可变数据，线程内重新 set() 很容易保持清晰的隔离；但如果值是列表或字典，副本中的绑定可能仍指向同一个 Python 对象。此时线程对对象做原地修改，调用方可能观察到内容变化。

import asyncio
from contextvars import ContextVar

labels = ContextVar("labels", default=None)

def add_label():
    # 这里没有重新绑定 ContextVar，而是修改共享列表对象的内容。
    labels.get().append("worker")
    return labels.get()

async def main():
    labels.set(["event-loop"])
    result = await asyncio.to_thread(add_label)
    # 列表可能包含 worker；这属于对象引用共享，不是上下文回写。
    print(result, labels.get())

工程上更稳妥的做法是把上下文值当作只读快照：绑定字符串、整数、不可变元组，或者在线程入口复制列表和字典后再处理。不要把可变请求状态塞进 ContextVar，再把它当成跨线程同步工具。

四、真正复制上下文的时机要看任务形态

asyncio.to_thread() 是异步函数。单纯写下 coro = asyncio.to_thread(fn) 时，函数体还没有执行；如果之后才修改 ContextVar 并开始等待，复制上下文的时机就会落在协程真正运行处。相反，asyncio.create_task() 会为任务保存创建时的上下文，所以任务内部看到的上下文又受任务创建时机影响。

这类代码最好把“设置请求上下文、创建任务、等待线程结果”放在同一个清晰的作用域内，避免把协程对象放进队列后才猜测它会继承哪个请求。需要固定上下文时，可以在明确的任务边界创建 Task，或直接把关键参数作为普通函数参数传入。

五、取消和异常也属于传递边界

取消等待 to_thread() 的 Task，通常只表示调用方不再等待这个结果，并不等于可以强制杀掉已经开始运行的工作线程。同步函数应自行响应超时、停止标记或底层库提供的取消机制；文件句柄、临时目录和连接也要在线程函数内部用 try/finally 释放。

相关问题

to_thread 能传递线程本地变量吗？

它传播的是 contextvars 上下文，不是普通 threading.local() 的状态。需要共享的线程本地数据应显式初始化或通过参数传入。

线程里 set() 后怎样让协程拿到新值？

把新值作为同步函数的返回值，或返回一个不可变结果对象；不要依赖 ContextVar 跨线程回写。

ContextVar 适合保存数据库连接吗？

通常不适合。连接对象有线程归属、生命周期和并发约束，应该由连接池或明确的资源管理器负责，ContextVar 只保存轻量的请求元数据。