Mojo 的 `@__parameter` 装饰器：遗留捕获闭包的完整实战与源码解析

Mojo 的@__parameter装饰器：遗留捕获闭包的完整实战与源码解析

【免费下载链接】mojoThe Modular Platform (includes MAX & Mojo)项目地址: https://gitcode.com/GitHub_Trending/mo/mojo

导读

@__parameter是 Mojo 语言中一个用于声明遗留（legacy）捕获闭包（capturing closure）的装饰器：被它修饰的嵌套函数会捕获外层作用域中的值（无论这些值是运行时变量还是编译期参数），并将闭包整体提升为可在编译期作为参数传递的实体。本文以 Mojo 官方参考文档（Mojo/docs/site/reference/decorators/parameter.mdx）为主线，结合仓库中的可运行示例（legacy_capturing_closure.mojo）、构建与测试配置（BUILD.bazel）以及编译器前端实现（DeclResolution.cpp），完整讲解其用法、capturing[_]捕获来源标记、弃用状态与迁移路径，并深入源码揭示它的解析与捕获来源（origins）收集机制。读完本文，你将能准确识别遗留闭包代码、正确书写capturing[_]类型签名，并掌握迁移到新闭包语法的依据。

重要前置提示：@__parameter已被官方标记为Deprecated（弃用），将在未来版本中移除，官方建议改用当前的闭包语法（见 闭包手册）。本文保留其详细讲解，是为了帮助读者理解历史代码、读懂编译器行为，并为迁移提供依据。

---

一、@__parameter是什么：一句话定位

在 Mojo 中，@__parameter是一个无参数装饰器，只能作用于嵌套函数（nested function）。它声明一个遗留捕获闭包：

• 该闭包可以捕获外层作用域中的值——无论是运行时变量（variable）还是编译期参数（parameter）；
• 该闭包可以作为参数（parameter）被传入其他函数，参与编译期类型/值计算。

官方参考文档的描述是（parameter.mdx）：

You can add@__parameteron a nested function to create a legacy capturing closure. This means you can create a closure function that captures values from the outer scope (regardless of whether they are variables or parameters), and then use that closure as a parameter.

值得注意的细节：它真正的拼写是双下划线@__parameter；历史上写作@parameter的拼写仍然被接受，但会触发弃用警告（详情见下文“源码实现”一节）。

---

二、从官方示例理解核心用法

官方文档在parameter.mdx中给出了完整可运行的示例，该示例与仓库中的独立示例文件 legacy_capturing_closure.mojo 完全一致：

def use_closure[func: def(Int) capturing[_] -> Int](num: Int) -> Int: return func(num) def create_closure(): var x = 1 @__parameter def add(i: Int) -> Int: return x + i var y = use_closureadd print(y) def main(): create_closure()

运行输出：

3

逐段拆解

1. 定义接受闭包参数的函数use_closure：它的类型参数func的类型是def(Int) capturing[_] -> Int——这是一个接受一个Int、返回Int的函数类型，并带有capturing[_]标记（见下一节）。注意这里的def表示该函数类型对应动态（def）函数语义。

2. 在普通函数create_closure内部：声明局部变量var x = 1。

3. 用@__parameter装饰嵌套函数add：add的函数体return x + i引用了外层作用域的变量x，这正是“捕获”（capture）行为。

4. 把add作为类型参数传给use_closure：use_closureadd中，add出现在方括号[...]的参数位置——这就是“把闭包当作参数”的含义。use_closure内部调用func(num)，即add(2)，得到x + 2 = 1 + 2 = 3并打印。

关键点

• 捕获可以同时涵盖变量和参数：官方文档明确说 “regardless of whether they are variables or parameters”。这意味着闭包体内既可以引用外层var变量，也可以引用外层函数的编译期参数。
• 闭包以参数形式（而非运行时值）被使用，这正是它与普通闭包最本质的区别：普通非参数化闭包在解析完成后会立即物化为运行时值，无法作为参数使用（见 DeclResolution.cpp 中 “Upon fully resolving a nonparametric closure, immediately materialize it as a runtime value. It cannot be used as a parameter.” 的注释）。

---

三、理解capturing[_]：函数类型中的来源标记

官方文档特别提醒注意use_closure函数类型签名中的[_]：

def use_closure[func: def(Int) capturing[_] -> Int](num: Int) -> Int:

[_]表示什么

[_]是一个origin specifier（来源指示符），它代表遗留闭包所捕获的所有值的来源（origins）集合。在 Mojo 的生命周期（lifetimes）体系中，每个值都有其“来源”——即该值的所有权/生命周期归属，而闭包捕获外部值后，编译器必须知道这些值的来源，才能正确地延长（extend）这些值的生命周期，确保闭包在被调用的时刻，捕获的值仍然存活、有效。

从语法上看：

• capturing[_]中的_是一个通配符，表示“捕获了任意来源集合的值”；
• 在实际的源码中，这个位置可以出现更具体的来源集合描述。

为什么需要它

Mojo 采用严格的“生命周期与来源”模型（lifetimes and provenance）：当函数类型的值（这里指闭包）被当作参数传递并在另一处调用时，编译器需要静态地知道该函数体可能访问哪些外部来源，从而决定是否需要延长这些来源对应值的生命周期，以及何时可以安全地结束它们。capturing[_]就是把“这个函数会捕获外部值”这一事实显式写进类型签名，让类型系统能够参与生命周期推理。

官方文档建议，想深入了解来源与生命周期的读者参阅 Lifetimes, origins and references（这是仓库中parameter.mdx内链接的目标路径，已按仓库根目录转换）。

从源码看capturing[_]如何被落地

capturing[_]中的“来源集合”并不是修辞，而是在编译器解析闭包时被真实计算并记录下来的。在 DeclResolution.cpp 中可以看到完整逻辑：

// Collect the captured values and parameter references from the resolved // body. BodyCaptures bodyCaptures = collectBodyCaptures(shared, decl, funcOp); SmallVector<Capture> &captures = bodyCaptures.values; SmallVector<ParamDeclRefAttr> &paramCaptures = bodyCaptures.paramRefs; // If this is a `@__parameter` closure, attach the capture origins. if (signature.isCapturing()) { SmallVector<Type> captureTypes; for (const Capture &cap : captures) captureTypes.push_back(cap.getValue().getType()); for (ParamDeclRefAttr param : paramCaptures) captureTypes.push_back(param.getType()); SmallVector<TypedAttr> origins = shared.cachedOriginFinder.findOriginsIn(captureTypes); signature = signature.getWithBody(signature.getBody().getWithMetadata( signature.getFnMetaOriginData().addCaptureOrigins( OriginSetAttr::get(getContext(), origins)), signature.getBody().getArgListAttrs())); funcOp.setFuncTypeGenerator(signature); ... }

这段代码揭示的底层事实：

1. 解析器先通过collectBodyCaptures收集闭包体捕获的值（captures）和参数引用（paramCaptures）；
2. 当该函数签名被标记为isCapturing()（这正是@__parameter装饰器所设置的，见下文第四节）时，编译器将这些捕获值/参数的类型交给cachedOriginFinder.findOriginsIn求出对应的origin 集合；
3. 求得的 origins 被包装成OriginSetAttr并通过addCaptureOrigins附着到函数类型生成器（FuncTypeGenerator）的元数据上；
4. 最终函数被转换为带有参数声明属性的实体（ParamDeclAttr），从而能够在编译期作为参数绑定使用。

这就是capturing[_]与编译器内部 origin 分析之间的对应关系：[_]是源码层面的来源集合通配写法，而解析器实际会算出具体来源集合并嵌入类型元数据，供生命周期检查（如 CheckLifetimes.cpp）使用。

---

四、源码实现：装饰器如何被解析

@__parameter的语义是在 Mojo 编译器前端（MojoParser）中实现的。搜索仓库可以发现它的关键解析位置：

• MojoParser/DLValues.cpp（含 TODO 注释 “Need @__parameter fn's for methods”，表明对方法的支持尚未完成，这解释了为什么目前@__parameter仅适用于嵌套函数场景）
• MojoParser/DeclResolution.cpp
• LITDialect/LITOps.cpp
• LowerLIT/CheckLifetimes.cpp（生命周期检查环节）

装饰器分派与弃用警告

在 DeclResolution.cpp 中，装饰器按拼写分派：

} else if (spelling == "__parameter" || spelling == "parameter") { // Temporarily accept the legacy `@parameter` spelling with a deprecation // warning so the rename to `@__parameter` can land without breaking // out-of-tree and late-landing code in the same change. if (spelling == "parameter") { emitWarning(declRef->getLoc(), "'@parameter' is deprecated; use '@__parameter'") << FixIt::replaceToken(declRef->getLoc(), "__parameter"); } applyArgumentless(spelling, callNode, [&]() { tcSignature.argList.effects.setCapturing(); }); }

由此可以得到几个明确的实现事实：

1. 两种拼写都被识别：__parameter与历史拼写parameter走同一分支；
2. 旧拼写触发编译警告：当写@parameter时，编译器会发出'@parameter' is deprecated; use '@__parameter'警告，并给出自动修复（FixIt），将源码中的parameter令牌替换为__parameter；
3. 核心语义是一条setCapturing()：applyArgumentless是“无参数装饰器”的应用入口，其 lambda 将函数签名的效果（effects）标记为capturing。这意味着@__parameter的本质作用就是把这个嵌套函数的类型签名标记为“捕获性”（capturing）——第四节中signature.isCapturing()的判断即来源于此；
4. 注释也解释了为什么旧拼写仍被接受：为了让@parameter更名为@__parameter的过程不会破坏既有（out-of-tree 及同期晚提交）代码，先以警告形式过渡。

与函数字面量的区别

在 LITOps.cpp 中可以看到，带参数声明属性的遗留@__parameter闭包不会被当作函数字面量（function literal）处理：

// legacy @__parameter closure is not a function literal. if (getParamDeclAttr()) return getBoundReference(evalContext, bindings);

也就是说，当在编译期求值一个@__parameter闭包时，它直接返回其有界引用（bound reference），而不是构造一个函数字面量生成器。这从实现层面印证了：遗留捕获闭包是“作为参数使用的实体”，与普通闭包（函数字面量）在 IR 层面有本质差异。

生命周期检查环节

@__parameter闭包还需要与生命周期检查协作。在 LowerLIT/CheckLifetimes.cpp 附近（// @__parameter注释处）存在与闭包来源处理相关的检查逻辑，这对应了官方文档中“编译器据此延长捕获值生命周期”的描述：捕获来源信息被用于确保闭包内引用的外层值在调用点仍然存活。

---

五、可运行的示例工程：BUILD.bazel 与测试

@__parameter的官方示例以“独立 Mojo 应用 + Bazel 构建/测试”的形式组织在 Mojo/docs/site/code/reference/decorators/parameter/ 目录中，其 README（README.md）说明了目录约定：

• 每个.mojo文件是一个独立的 Mojo 应用；
• BUILD.bazel 定义了每个.mojo文件对应的构建目标与测试目标。

BUILD.bazel 解读

load("//bazel:api.bzl", "modular_run_binary_test", "mojo_binary") package(default_visibility = ["//oss/modular/docs:__subpackages__"]) MOJO_SRCS = glob(["*.mojo"]) [ mojo_binary( name = src.split(".")[0], srcs = [src], deps = [ "@mojo//:std", ], ) for src in MOJO_SRCS ] [ modular_run_binary_test( name = src.split(".")[0] + "_test", size = "small", binary = src.split(".")[0], ) for src in MOJO_SRCS ]

其要点：

1. 目标命名约定：每个.mojo文件会被自动生成一个同名（去扩展名）的mojo_binary目标和一个带_test后缀的modular_run_binary_test测试目标。例如当前目录唯一的示例文件legacy_capturing_closure.mojo对应目标legacy_capturing_closure与legacy_capturing_closure_test。
2. 标准库依赖：所有示例二进制均依赖@mojo//:std（Mojo 标准库）。
3. 测试规模：size = "small"，说明这些示例都是轻量级的小型运行测试——直接执行二进制并校验其输出（本示例预期输出3）。
4. visibility 限制：包仅对//oss/modular/docs:__subpackages__可见，即这些示例专供文档体系内部使用。

如果你在本地使用 Bazel 构建/运行该示例（示例目录即仓库内Mojo/docs/site/code/reference/decorators/parameter），典型命令形如：

bazel build //Mojo/docs/site/code/reference/decorators/parameter:legacy_capturing_closure bazel test //Mojo/docs/site/code/reference/decorators/parameter:legacy_capturing_closure_test

实际命令请以仓库根目录的 BUILD.bazel 与 bazelw 入口所定义的目标路径为准；本目录的BUILD.bazel采用glob自动生成目标，因此任何新增.mojo文件都会自动获得对应目标。

---

六、弃用状态与迁移建议

状态声明

官方参考文档在parameter.mdx开头以醒目警示（caution）明确：

The@__parameterdecorator is deprecated and will be removed in a future release. Use the current closure syntax instead. The previous spelling@parameteris still accepted with a deprecation warning.

翻译并整理要点：

1. @__parameter已弃用，将在未来版本中移除；
2. 迁移目标：使用当前的闭包语法（见仓库文档 closures.mdx）；
3. 历史拼写@parameter仍被接受，但会给出弃用警告（这条在源码 DeclResolution.cpp 中得到印证）。

为什么会存在“双重弃用”

仓库源码揭示了原因：@parameter是更早的拼写，Mojo 团队在将其更名为@__parameter时，为了让既有代码不在一夜之间全部报错，采取了“先接受旧拼写 + 发出弃用警告 + 提供 FixIt 自动替换”的过渡策略（DeclResolution.cpp 中注释 “Temporarily accept the legacy@parameterspelling with a deprecation warning so the rename to@__parametercan land without breaking out-of-tree and late-landing code in the same change.”）。而如今@__parameter本身也已进入弃用状态，最终方向是全面迁移到新的闭包语法。

迁移建议（基于仓库证据）

• 如果你正在维护使用@parameter的旧代码：立即将其改拼写为@__parameter以消除警告（编译器 FixIt 会自动完成替换）。
• 如果你正在使用@__parameter编写新代码：应规划迁移到官方推荐的当前闭包语法。新的闭包语法允许创建可捕获外部值的闭包值，且生命周期模型更完善；遗留的capturing[_]来源标记与手动延长生命周期的心智负担在新语法下由编译器以更统一的方式处理。
• 相关的手册章节与提案可参考仓库中的 闭包手册 以及 lifetimes-and-provenance.md 提案、lifetimes 手册，它们解释了 Mojo 对捕获与来源的完整设计思路。

---

七、常见问题速查

问题	答案
@__parameter可以用在顶层函数上吗？	官方文档明确指出它作用于嵌套函数；源码层面也存在 “Need @__parameter fn's for methods” 的 TODO（DLValues.cpp），即对方法（methods）的支持尚未实现，因此目前请只用于嵌套函数。
capturing[_]里的_是什么？	捕获来源集合的通配写法，表示该函数类型会捕获外部值；真实来源集合由编译器在解析时计算并嵌入类型元数据（DeclResolution.cpp）。
旧拼写@parameter还能用吗？	能，但会产生弃用警告，编译器会建议替换为@__parameter（DeclResolution.cpp）。
遗留闭包与普通闭包在编译期有什么区别？	遗留@__parameter闭包作为参数实体（ParamDeclAttr）存在，不是函数字面量（LITOps.cpp）；普通非参数化闭包会立即物化为运行时值，无法作为参数（DeclResolution.cpp）。
这个装饰器会保留多久？	官方文档声明“将在未来版本中移除”，因此新代码不应依赖它。

---

八、总结

@__parameter是 Mojo 语言演进过程中的一个过渡性功能：它让开发者能够在旧语法下编写“捕获外层值的参数化闭包”，并通过函数类型中的capturing[_]标记把捕获来源暴露给生命周期系统，从而安全地延长捕获值的生命周期。仓库源码（DeclResolution.cpp、LITOps.cpp）完整地展示了它的解析、来源收集与 IR 表示方式，官方示例工程（legacy_capturing_closure.mojo 与配套 BUILD.bazel）则给出了可直接构建验证的用例。

对于今天的 Mojo 开发者，正确的姿态是：理解遗留代码中的@__parameter与capturing[_]，但新代码一律使用当前的闭包语法。如果必须在旧代码库中工作，请优先执行编译器提示的@parameter→@__parameter自动修复，并尽快评估迁移路径。

【免费下载链接】mojoThe Modular Platform (includes MAX & Mojo)项目地址: https://gitcode.com/GitHub_Trending/mo/mojo