> ## Documentation Index
> Fetch the complete documentation index at: https://fluxon.tabooproject.org/llms.txt
> Use this file to discover all available pages before exploring further.

# 解释器执行流

> 解释器如何评估 AST 并派发函数调用

Fluxon 的解释器建立在 `Function` / `FunctionContext` / `Environment` 三个核心抽象之上。解析器产出 AST，解释器按节点类型派发
evaluator；在函数调用处，则交由运行时标准库（`Intrinsics`）统一处理 `async` / `primarySync` 等语义。

## 执行入口

典型路径：

* `Fluxon.eval(source)` → 解析 → `Interpreter.execute(parseResults)`
* `Interpreter` 在执行过程中会维护 `Environment`（变量、函数、扩展函数与上下文目标 `target`）。

<Note>编译执行（字节码生成与 `RuntimeScriptBase`）见 [编译执行引擎](/runtime/execution-engine)。</Note>

## 函数抽象：`Function`

* `Function` 定义函数名、命名空间、参数个数、`async`/`primarySync` 标记，以及 `call(FunctionContext)`。
* 系统/扩展函数通常以 `NativeFunction` 承载；脚本 `def/async def/sync def` 生成的函数也实现 `Function`，因此共享同一套调用语义。

## 调用上下文：`FunctionContext`

`FunctionContext` 封装一次调用所需的信息：

* `function`：当前函数
* `target`：上下文调用（`::`）时的目标对象
* `environment`：共享环境
* `arguments`：参数与参数数量（解释器会对高频路径做池化与优化，但对文档使用者而言语义不变）

常用的参数读取 API：`getInt` / `getLong` / `getDouble` / `getString` / `getRef` / `getAsDouble` 等；类型不匹配时会抛出 `ArgumentTypeMismatchError`。

## async 与 primarySync

函数调用的调度逻辑由 `Intrinsics.callResolvedFunction(...)` 统一处理：

* `async = true`：调用会被提交到运行时线程池，返回 `Future/CompletableFuture`。
* `primarySync = true`：调用会被转发到主线程执行器（由宿主通过 `FluxonRuntime#setPrimaryThreadExecutor` 提供）。
* 其他情况：同步执行并直接返回结果。

`await expr` 会在 `expr` 返回 `Future/CompletableFuture` 时等待其完成，否则直接返回 `expr` 的值。

## 全局对象与上下文调用

* `Environment` 维护一个 `target` 槽位以实现上下文调用：`value :: func(...)` 会临时将 `target` 设为 `value`，
  并在执行结束后恢复旧值。
* 扩展函数的解析与匹配依赖 `target` 的宿主类型（参见 [扩展函数 API](/developer/extension-api)）。

## 调试建议

* 当遇到“函数找不到”或“参数类型错误”时，可以直接打印 `FunctionContext#toString()`，其中包含函数名、目标对象与参数信息。
* 需要追踪异步/主线程调度时：结合 `Function#isAsync` / `Function#isPrimarySync` 与 `ThreadPoolManager` 的观测信息排查。
* 参考：[运行时配置与调试](/developer/runtime-config) 与 [故障排查](/developer/troubleshooting)。

## 相关链接

* [环境与作用域](/runtime/environment)
* [编译执行引擎](/runtime/execution-engine)
* [运行时注册 API](/developer/runtime-registry)
* [运行时配置与调试](/developer/runtime-config)
* [故障排查](/developer/troubleshooting)