Python Executor

职责与边界

Python Executor 在 CPython 宿主进程中运行用户函数。它接收 Worker 派发的函数执行工作，并通过宿主桥接路由挂起的后端操作。EVM 查询携带函数提供的链与区块。编程流程见编写 EVM 数据函数。本页说明执行组件。

代码位置

BlockX 仓库中的来源	职责
`pyhost/src/main.c`、`pyhost/src/embed.c`	宿主启动与嵌入式解释器
`pyhost/src/sched.c`、`pyhost/src/coro.c`	宿主调度与协程支持
`pyhost/src/bridge.c`、`pyhost/src/proto.c`	宿主桥接与协议处理
`python/blockx_runtime/`	函数入口、模块加载与后端桥接
`python/blockx_audit/`	静态源码审计与能力表
`internal/worker/adapters/executor/`	Worker 侧宿主进程与连接管理

核心类型与接口

接口	作用
`bxpy_coro`	为驻留的调用持有独立原生栈与 `PyThreadState`
`bxpy_coro_park` / `bxpy_coro_resume`	挂起跨边界操作，并在所属解释器线程恢复
`bxpy_cross`	在挂起期间保存桥接操作的输入、输出与失败
`execute` / `release_task` / `release_tasks`	执行单次请求，并释放已完成任务的命名空间
`CallContext` / `call_scope`	跟踪调用身份、调试状态、参数及配对的上下文进入与退出
`ModuleRegistry.load_callable`	按摘要加载源码，并从命名空间返回解析后的入口
`resolve_entry_name`	让源码审计与运行时加载共用入口选择规则
`HostProvider`	通过宿主桥接实现 SDK 读取、写入、子调用与协作式休眠
`host.io_value` / `host.io_json` / `host.io_rpc`	跨宿主边界传递后端请求
`host.fetch_source` / `host.subcall`	获取函数源码并派发子调用
`wire.pack`	在宿主编码前应用 Python 返回值转换规则
`NodeRPCBridgeProvider`	通过 `host.io_rpc` 路由 EVM 节点请求
`EVM`	函数可见的对象，携带链与区块上下文
`install_noderpc_bridge`	安装运行时的逐链桥接 provider

python/blockx_runtime/host.py 定义面向 Python 的宿主桥接。审计代码可用的能力名称维护在 python/blockx_audit/tables.py。

数据流 / 执行流程

Worker 向 Executor 宿主派发函数及其参数。
运行时加载函数定义并调用入口。
状态读取与合约查询经 NodeRPCBridgeProvider 传递链和请求参数。
Worker IO 处理后端请求，宿主恢复计算。
函数返回输出，Worker 收集结果并交给选定 Writer Plugin。

函数的 EVM 对象提供读取上下文。任务的函数代码快照固定定义，与数据读取使用的区块相互独立。

函数加载与入口解析

ModuleRegistry 按摘要缓存编译后的源码，并维护每个任务的命名空间。它可以通过 host.fetch_source 获取缺失源码。释放任务时移除其命名空间；函数身份与版本选择见 Function Code View。 python/blockx_audit/tables.py 中的 resolve_entry_name 提供共用的选择规则。运行时将其应用于 entrySelector：

选择器的最后一段如果命中符合条件的顶层函数，就使用该函数。
否则使用 _，它可以是函数定义，也可以是指向顶层函数的别名。
否则按源码顺序使用第一个符合条件的公开顶层函数。
如果都不存在，则解析为 _，并在加载时报告缺少可调用入口。

命名入口规则不能选择以 __ 开头的名称或危险内建名称。公开函数回退规则跳过以 _ 开头的名称和危险内建名称。审计绑定检查会拒绝对已有 _ 定义重新绑定的别名。

返回值序列化

python/blockx_runtime/wire.py 先转换 Python 值，宿主再将其打包为值程序。Worker 将值程序转换为结果携带的 JSON。

Python 值	输出行为
`int`，包括 `2**256 - 1`	保留整数，不收窄为浮点值
`datetime`	RFC 3339；无时区值与 `timezone.utc` 使用 `Z`，其他带时区值保留偏移量；保留非零微秒
`date`	ISO 日期字符串
Dataclass 实例	通过 `dataclasses.asdict` 转换；优先返回普通字典
非有限 `float`	JSON `null`
不支持的值，例如 `set`	编码失败并返回 `terminal_encode_failed`，标记为不可重试

计算过程中将 EVM uint256 值保留为 Python 整数。消费方也必须无精度损失地解码 JSON 整数。协议转换不会额外授予审计函数导入权限或能力。

状态与生命周期

Worker 管理 Executor 宿主进程及其连接。运行时初始化安装桥接并准备函数执行。函数源码加载和版本身份与 Function Code View 协作。

挂起与恢复不变量

原生宿主在一个解释器线程上驻留多个调用，每次运行一个协程。修改调度或桥接时，需要保持以下不变量：

不变量	实现约束
调用在执行期间持续持有自己的原生栈与 `PyThreadState`	`bxpy_coro_resume` 要求所属 OS 线程与解释器 GIL
挂起请求在恢复前保持有效	`bxpy_cross` 及其借用的输入保留在协程栈上
后端等待将控制权交还调度器	IO、源码获取、子调用与休眠挂起协程；预算读取、检查点与日志就地执行
响应只恢复当前等待	`handle_resume` 检查调用状态与请求 ID，忽略过期响应
调用上下文成对进入与退出	`call_scope` 压入和弹出同一个 `CallContext`；栈不匹配时报错
复用不能继承上次调用的执行状态	`bxpy_coro_reset` 清理逐调用状态，检查执行已经退栈，并分配新身份

调度器跟踪 CS_QUEUED、CS_RUNNABLE、CS_RUNNING、CS_WAIT_IO、CS_WAIT_FUNCTION_CODE、CS_WAIT_SUBCALL、CS_WAIT_SLEEP 和 CS_DONE。取消与截止时间由宿主调度器裁定，运行时编码对应终态。EVM 后端响应在既有调用上下文中恢复等待的函数。

配置

设置	作用
`EXECUTOR_HOST_BIN`	宿主可执行文件，默认为 `blockx-pyhost`
`PYTHON_BIN`	审计进程使用的解释器
`PYTHONPATH`	运行时模块与已安装的函数依赖
`EXECUTOR_COUNT`	Executor 进程数量

宿主嵌入 CPython 3.14 或更高版本。按照快速开始构建，并提供虚拟环境的包目录。

扩展点

通过运行时桥接和对应后端适配器增加函数可见能力。修改允许的函数接口时，同步更新审计能力表。验证链与区块上下文原样传递到后端请求。

测试

BlockX 仓库中的以下测试覆盖桥接集成、入口选择、模块命名空间及返回值转换，按需使用宿主替身：

cd python
.venv/bin/python -m unittest \
  tests.test_runtime_leafage tests.test_noderpc_bridge \
  tests.test_runtime_entry tests.test_runtime_module_registry tests.test_runtime_wire

宿主与进程测试还覆盖原生执行边界，共享环境准备位于 internal/testutil/pyhost.go。

开始使用

核心概念

使用指南

参考

架构

组件

开发指南

职责与边界

代码位置

核心类型与接口

数据流 / 执行流程

函数加载与入口解析

返回值序列化

状态与生命周期

挂起与恢复不变量

配置

扩展点

测试

相关文档

​职责与边界

​代码位置

​核心类型与接口

​数据流 / 执行流程

​函数加载与入口解析

​返回值序列化

​状态与生命周期

​挂起与恢复不变量

​配置

​扩展点

​测试

​相关文档

职责与边界

代码位置

核心类型与接口

数据流 / 执行流程

函数加载与入口解析

返回值序列化

状态与生命周期

挂起与恢复不变量

配置

扩展点

测试

相关文档