🧠 WorldContext：运行时上下文管理器¶
WorldContext 是 TongSim Python SDK 的核心模块之一，负责管理与一个 TongSim Unreal 实例绑定的所有运行时资源。
它统一封装了：
- 异步事件循环（AsyncLoop）
- gRPC 通信连接（主连接和 legacy 连接）
为什么需要 WorldContext？¶
在 TongSim 中，智能体行为控制、图像流采集、PG 数据订阅等大量操作，都是基于 gRPC 协议的 I/O 密集型调用，而非计算密集型。传统的多线程方案不仅复杂、容易引发同步问题，并且容易增加上下文切换开销。
为了提升性能并降低并发访问冲突，TongSim 采用以下设计理念：
所有与一个 TongSim 实例相关的异步任务，统一调度到一个独立线程中的事件循环（即 AsyncLoop）执行。
这一机制确保了：
- 所有 gRPC 调用在事件循环内调度，避免多线程锁竞争
- 用户同步代码可通过
sync_run()安全地阻塞等待异步任务结果 - WorldContext 会自动清理未完成的任务和连接，确保资源释放干净
计算密集型任务的注意事项
AsyncLoop 主要适用于 I/O 密集型操作（如 gRPC、订阅图像等）。
如果你需要执行 计算密集型逻辑（如图像处理、路径规划），请将其 offload 到专用的线程池或进程池中，避免阻塞异步调度线程。
AsyncLoop：挂载所有协程的专属线程¶
TongSim 的 AsyncLoop 是一个封装好的后台线程，它在内部维护：
- 一个独立的 asyncio 事件循环
- 一个主任务组（TaskGroup），用于挂载用户或系统级的异步任务
- 任务崩溃时自动传播异常、取消所有相关协程
✅ 对用户意味着什么？¶
对用户而言
- 你无需手动管理线程或事件循环
- 所有异步任务都在一个线程中运行，天然避免锁竞争
- 你只需调用
context.sync_run(...)提交协程，即可同步等待其执行完成 - 若你需要非阻塞式的提交异步任务，可以调用
context.async_task(...)将任务提交到专属线程执行
TongSim SDK 即兼容 同步阻塞调用，也适配 异步高并发管控，无需用户显式切换上下文。
常用接口¶
| 功能 | 接口名 | 说明 |
|---|---|---|
| 提交协程并同步等待结果 | context.sync_run(coro) |
当前线程中阻塞等待异步任务完成 |
| 提交协程为后台任务 | context.async_task(coro, name) |
非阻塞后台运行，返回 Future |
| 获取 gRPC 主连接 | context.conn |
用于绝大多数数据接口 |
| 获取 legacy gRPC 连接 | context.conn_legacy |
一个遗留的gRPC链接，维护一些比较旧的通信功能 |