Cppfront 契约(Contracts)完全指南:pre/post 条件、断言与可定制违规处理机制

原创2026-10-05 21:31:591,927 阅读
文章标签:编译器编程语言开发工具

Cppfront 契约(Contracts)完全指南:pre/post 条件、断言与可定制违规处理机制

本文基于 docs/cpp2/contracts.md 编写,并结合 cppfront 仓库源码(include/cpp2util.h、source/to_cpp1.h、source/reflect.h2、回归测试)进行源码级印证与扩充。Cpp2 的契约机制是 Cppfront(一个 C++ Syntax 2 → Syntax 1 的实验性编译器)中实现设计期检查(Design by Contract)与类型/边界/空值安全的核心设施,读完本文你将掌握三种契约的写法、<group, predicates> 的评估顺序、如何自定义契约组与违规处理器,以及如何借助回归测试验证契约行为。

概述:Cpp2 支持哪三类契约

Cppfront 目前支持三种契约(contracts):

  • 前置条件与后置条件(preconditions and postconditions)。函数声明可以在 = /* 函数体 */ 之前书写 pre(condition) 与 post(condition)。进入函数体之前,前置条件会被完整求值;后置条件则作为"函数表达式"被捕获(capture),留待之后求值——如果需要,后置条件会在进入函数时先完成对值的捕获。当函数体通过正常 return 退出时,后置条件被求值;如果函数经由异常退出,则后置条件不会被求值。

  • 断言(Assertions)。函数体内可以书写 assert(condition) 断言语句。断言在控制流经过它时被求值。

// 契约声明位于 = 函数体之前
f: (x: int) -> int
    pre (x > 0)
    post (result == x$ + 1)
= {
    // 函数体内可以使用 assert
    assert( x < 1000, "x 过大" );
    return x + 1;
}

要点说明:

  • condition 是一个求值为 true 或 false 的表达式。除非该契约组处于启用状态(group.is_active() 为 true),否则 condition 根本不会被求值——这是契约零开销(可关闭)的关键设计。
  • 可选地,condition 后面可以跟 , "message",在违规发生时附带一条消息,例如 pre(condition, "message")。
  • 可选地,可以在 ( 之前用尖括号写入 <group, pred1, pred2>,表示该测试属于名为 group 的契约组,并可附带契约谓词 pred1、pred2。一旦违规发生,会调用 Group.report_violation()。例如 pre<group>(condition)。若未指定契约组,契约默认属于 default 组(在 Cpp1 代码中写作 cpp2_default)。

契约的求值顺序:从"忽略"到"报告违规"

一个契约的完整求值顺序如下(这也是 Cppfront 降低到 Cpp1 后实际生成的代码所遵循的逻辑):

  1. 先检查是否为 unevaluated 组:如果契约组是 unevaluated,则契约被直接忽略,condition 永不求值。这个特殊组专供静态分析器使用,唯一要求是 condition 在语法上合法即可;
  2. 再按顺序求值谓词(predicates):任一谓词求值为 false 即停止;
  3. 求值 group.is_active():为 false 则停止;
  4. 求值 condition:为 true 则停止(通过检查);
  5. 报告违规:若所有谓词为真、组处于激活状态、而 condition 为 false,则调用 group.report_violation()。

这一顺序可以在 source/to_cpp1.h 的契约降级代码中得到印证(见 L4980-L5031):

// 摘自 source/to_cpp1.h(Cpp2 契约被翻译为 Cpp1 后的形态)
if (n.group && n.group->to_string() == "unevaluated") {
    return;                       // unevaluated 组:直接不发任何检查代码
}
...
// 谓词与 is_active() 依次以 && 串联,condition 最后求值
printer.print_cpp2(
    separator + name + ".is_active()",
    ...
);
printer.print_cpp2(
    " && !(" + print_to_string(*n.condition) + ") ) " +
        "{ " + name + ".report_violation(" + message + "); }",
    ...
);

从这段生成逻辑可以推断:编译器把每个契约编译成形如 if (pred1 && pred2 && group.is_active() && !(condition)) { group.report_violation(message); } 的 Cpp1 语句。由于 C++ 的 && 短路求值,谓词、is_active()、condition 严格按声明顺序依次求值,任何一环失败都不会执行后面的 condition 与 report_violation()——这正是"未启用即零开销"的实现基础。

实战示例:带 $ 捕获的 pre/post

原文档给出了一个综合示例,同时演示了前置条件、后置条件、契约组与 $ 值捕获:

insert_at: (container, where: int, val: int)
    pre<bounds_safety>( 0 <= where <= container.ssize(), "position (where)$ is outside 'container'" )
    post              ( container.ssize() == container.ssize()$ + 1 )
= {
    _ = container.insert( container.begin()+where, val );
}

示例要点:

  • $ 捕获在进入函数之前完成。"position (where)$ ..." 消息中的 $ 会在进入函数时被替换为 where 的实际值(Cpp2 的 $ 插值/捕获机制,详见 docs/cpp2/expressions.md);后置条件里的 container.ssize()$ 捕获的是"进入函数前"的容器大小。
  • 前置条件属于 bounds_safety 契约组,在进入函数前检查。如果检查失败——例如 where 为 -1——则调用 cpp2::bounds_safety.report_violation("position -1 is outside 'container'")。
  • 后置条件属于 default 安全契约组。若检查失败,则调用 cpp2::default.report_violation()。

注意前置条件的写法 0 <= where <= container.ssize():Cpp2 支持链式比较,它等价于"where 不小于 0 且不大于容器当前大小"。后置条件 container.ssize() == container.ssize()$ + 1 利用 $ 记住插入前的长度,断言插入后长度恰好加 1——这是把 $ 捕获用于后置条件校验的典型模式(相关内容还可参考 docs/cpp2/objects.md 中关于对象生命周期的讨论)。

契约组(Contract groups)

契约组的价值在于:可以为不同的契约集合独立地启用/禁用,或安装自定义违规处理器。一个契约组 grp 实际上就是一个对象的名字,该对象必须可被这样调用:

  • grp.report_violation() 与 grp.report_violation(message),其中 message 是 * const char 形式的 C 风格文本字符串;
  • grp.is_active(),当且仅当组处于启用状态时返回 true。

创建新契约组非常简单:只要创建任何带有 .report_violation 函数的对象即可,对象名就是契约组名。对象可以位于任意作用域:局部、全局或堆上。原文档示例:

group_a: cpp2::contract_group = ();          // 一个全局组

func: () = {
    group_b: cpp2::contract_group = ();      // 一个局部组

    group_c := new<cpp2::contract_group>();  // 一个动态分配的组

    // ...

    assert<group_a >( some    && condition );
    assert<group_g >( another || condition );
    assert<group_c*>( another && condition );
}

这里 assert<group_a>、assert<group_g>、assert<group_c*> 把各断言分别归入对应的契约组(注意动态分配的组通过 group_c* 指针来引用)。

把类层次中的所有对象变成契约组:<this>

你可以让某个类层次中的所有对象都成为一个契约组:在基类中提供一个 .report_violation 函数,然后在层次内的契约中使用 <this> 作为组名。Cppfront 自身的反射 API 就使用了这项技术,见 source/reflect.h2 的 add_initializer(L420-L422):

function_declaration: @copyable type =
{
    // 继承自一个提供了 '.report_violation' 的基类

    // ...

    add_initializer: (inout this, source: std::string_view)
        pre<this> (!has_initializer(), "cannot add an initializer to a function that already has one")
        pre<this> (parent_is_type(),   "cannot add an initializer to a function that isn't in a type scope")
    = { /*...*/ }

    // ...

}

在这段代码中,pre<this> 将前置条件关联到"当前对象"这个契约组:任何 function_declaration 对象(及其层次内的派生对象)若违反这两条前置条件,违规消息会通过该对象自身的 report_violation() 上报。这样契约检查点天然携带了对象上下文,非常适合在框架/API 层做自描述式校验。

契约谓词(Contract predicates)

契约谓词用于把特定的契约检查按静态或动态属性进行条件化。关键特性是:只要任一谓词为 false,该检查的条件表达式就不会被求值。原文档示例:

is_checked_build: bool == SEE_BUILD_FLAG;   // 一个静态(编译期)谓词

checking_enabled: bool =  /*...*/ ;         // 一个动态(运行期)谓词,
                                            // 可在程序运行期间变化

func: () = {
    assert<audit, is_checked_build, checking_enabled>( condition );
}

该示例的求值顺序:

  • 先求值 is_checked_build。由于它是编译期值,评估可发生在编译期;若为 false 则停止,整个契约甚至可能被编译器优化掉;
  • 否则在运行期求值 checking_enabled;若为 false 则停止;
  • 否则求值 audit.is_active();若为 false 则停止;
  • 否则求值 condition;若为 true 则停止;
  • 否则调用 audit.report_violation()。

这一"编译期谓词优先、运行期开关其次、组激活再次、条件最后"的分层设计,允许你在同一套契约代码中混合表达"仅在特定构建配置下检查"与"运行时动态开关检查"两种需求,且短路求值保证无谓的开销。

cpp2::contract_group 与可定制的违规处理

契约组对象还可以提供更多功能。Cpp2 自带 cpp2::contract_group 类型,允许为每个对象安装一个可定制的处理器。每个对象同一时刻只能有一个处理器,但处理器可以在程序运行过程中更换。contract_group 支持:

  • .set_handler(pfunc):接受一个签名形如 * (* const char) 的处理器函数指针;
  • .get_handler():返回当前处理器函数指针,未安装时返回 null;
  • .is_active():返回当前是否安装了处理器;
  • .enforce(condition, message):求值 condition,若为 false 则调用 .report_violation(message)。

contract_group 的完整实现位于 include/cpp2util.h 的 L542-L556:

class contract_group {
public:
    using handler = void (*)(CPP2_MESSAGE_PARAM msg CPP2_SOURCE_LOCATION_PARAM);

    constexpr contract_group  (handler h = {}) : reporter{h} { }
    constexpr auto set_handler(handler h = {}) { reporter = h; }
    constexpr auto is_active  () const -> bool    { return reporter != handler{}; }

    constexpr auto enforce(bool b, CPP2_MESSAGE_PARAM msg = "" CPP2_SOURCE_LOCATION_PARAM_WITH_DEFAULT)
                                          -> void { if (!b) report_violation(msg CPP2_SOURCE_LOCATION_ARG); }
    constexpr auto report_violation(CPP2_MESSAGE_PARAM msg = "" CPP2_SOURCE_LOCATION_PARAM_WITH_DEFAULT)
                                          -> void { if (reporter) reporter(msg CPP2_SOURCE_LOCATION_ARG); }
private:
    handler reporter;
};

可以看到:is_active() 的本质就是"当前是否安装有处理器"(reporter != handler{}),report_violation() 则是把消息转发给处理器。因此"激活契约组"与"安装违规处理器"在实现上是同一件事——这也解释了为什么 set_handler() 可以用 {} 清空处理器并使组变为非激活状态(回归测试 pure2-contracts.cpp2 中 cpp2::type_safety.set_handler() 一行正是利用这一点关闭了该组的检查)。

五个预定义契约组

Cpp2 在命名空间 cpp2 中预定义了五个全局契约组对象(见 include/cpp2util.h 的 L573-L597):

预定义组 用途 违规时默认输出的前缀
default 未指定组时使用的默认契约组 Contract
type_safety 类型安全检查 Type safety
bounds_safety 边界安全检查 Bounds safety
null_safety 空值安全检查 Null safety
testing 一般性测试检查 Testing

这些组的默认处理器是 cpp2::report_and_terminate(include/cpp2util.h):把违规信息打印到 std::cerr 后终止程序。原文档表述为"调用 std::terminate()";查看当前仓库源码,实际实现是打印违规信息(包含文件、行号、函数名与消息,前提是启用了 CPP2_USE_SOURCE_LOCATION)后调用 std::exit(EXIT_FAILURE),最终效果同样是"打印后立即终止"。

[[noreturn]] inline auto report_and_terminate(std::string_view group, CPP2_MESSAGE_PARAM msg = "" CPP2_SOURCE_LOCATION_PARAM_WITH_DEFAULT) noexcept -> void {
    std::cerr
#ifdef CPP2_USE_SOURCE_LOCATION
        << where.file_name() << "("
        << where.line() << ") "
        << where.function_name() << ": "
#endif
        << group << " violation";
    if (msg && msg[0] != '\0') {
        std::cerr << ": " << msg;
    }
    std::cerr << "\n";
    std::exit(EXIT_FAILURE);
}

预定义组在 cppfront 运行时库中也被大量用于安全校验,例如 null_safety.report_violation("dynamic null dereference attempt detected" ...)(include/cpp2util.h)、type_safety.report_violation("integer division by zero attempt detected" ...)(L1184)、bounds_safety 的越界上报(L1235)等,可对照 docs/cpp2/safety.md 理解它们在安全模型中的作用。

接入自有错误上报框架:自定义处理器

默认行为可以替换为任何你想要的行为,包括接入项目正在使用的第三方或自研错误上报系统。原文档示例:

main: () -> int = {
    cpp2::default.set_handler(call_my_framework&);
    assert<default>(false, "this is a test, this is only a test");
    std::cout << "done\n";
}

call_my_framework: (msg: * const char) = {
    //  这里可以做任何事,包括任意工作,
    //  以及集成你当前的错误上报库、
    //  记录日志后继续运行、抛出异常,等等...
    std::cout
        << "sending error to my framework... ["
        << msg << "]\n";
    exit(0);
}
//  输出:
//      sending error to my framework... [this is a test, this is only a test]

要点:cpp2::default.set_handler(call_my_framework&) 用 & 取函数地址安装自定义处理器;处理器签名是 (msg: * const char)。之后对 default 组的任何违规(此处用 assert<default>(false, ...) 故意触发)都会走 call_my_framework,而不是打印到 std::cerr 后终止。你可以在这里实现:上报到日志系统后继续运行、抛出异常、触发调试器断点、计入监控指标等任意逻辑。由于每个 contract_group 对象独立持有自己的处理器,五个预定义组以及你自定义的任意组都可以拥有互不干扰的处理策略。

回归测试实证:契约求值的短路行为

仓库的回归测试 regression-tests/pure2-contracts.cpp2 直接验证了契约的短路求值与 unevaluated 组行为:

test_condition_evaluation: (tag) -> bool = { std::cout << tag << "\n"; return true; }

audit: bool = true;

main: () = {
    //  几个基础测试
    assert( 1 != 2, "ack, arithmetic is buggy" );
    assert<type_safety>( typeid(int) != typeid(double), "ack, C types are broken" );
    assert<unevaluated>( any-grammatical.kind(of, nonsense * here) is "all ignored" );

    //  验证:只有存在活跃处理器(以及其他控制开关)时条件才会被求值
    assert( test_condition_evaluation(1), "default" );              // 求值:打印 "1"

    //  type_safety 组有处理器
    assert<type_safety>( test_condition_evaluation(2), "type" );           // 求值:打印 "2"
    cpp2::type_safety.set_handler();
    //  type_safety 组现在没有处理器
    assert<type_safety>( test_condition_evaluation(3), "1 == (1)$" );      // 不求值

    //  bounds_safety 有处理器,且 audit 为 true
    assert<bounds_safety, audit>( test_condition_evaluation(4), "type" );  // 求值:打印 "4"
    audit = false;
    //  bounds_safety 有处理器,但 audit 为 false
    assert<bounds_safety, audit>( test_condition_evaluation(5), "type" );  // 不求值

    assert<unevaluated>( test_condition_evaluation(6) );            // 不求值
}

注意其中 assert<unevaluated>( any-grammatical.kind(of, nonsense * here) ... ) 故意写了一段语法上合法、语义上无意义的表达式——这正是文档所说"unevaluated 组唯一要求是条件在语法上合法"。各平台回归测试的实测输出(例如 test-results/apple-clang-15-c++2b/pure2-contracts.cpp.execution)依次只打印 1、2、4,证明:

  • default 组激活时条件 1 被求值;
  • type_safety 组有处理器时条件 2 被求值,set_handler() 清空处理器后条件 3 不被求值;
  • bounds_safety 组激活且谓词 audit 为 true 时条件 4 被求值,audit = false 后条件 5 不被求值(谓词短路阻止了条件求值);
  • unevaluated 组中的条件 6 永不求值。

这些结果与本文前述的求值顺序一一对应,可作为契约机制的"可运行规范"参考(测试集由 regression-tests/run-tests.sh 驱动,输出对照文件位于 regression-tests/test-results/ 下各编译器目录)。

小结与延伸阅读

Cppfront 的契约系统把前置/后置条件、断言、契约组、契约谓词与可替换违规处理器组合成一个统一而灵活的机制:默认的五个安全契约组(default、type_safety、bounds_safety、null_safety、testing)覆盖常规安全校验;<group, pred1, pred2> 语法让你对每个契约精细控制归属与启用条件;cpp2::contract_group 的 set_handler/get_handler/is_active/enforce 则让违规处理完全可定制、可对接任意错误上报体系。结合短路求值的实现(source/to_cpp1.h)与回归测试,你可以放心地把这套机制用于生产级的安全断言与框架自校验。

继续深入可参阅:docs/cpp2/safety.md(安全模型与各类 _safety 组的使用场景)、docs/cpp2/functions.md(函数声明与契约的语法位置)、docs/cpp2/expressions.md($ 捕获与插值),以及运行时库实现 include/cpp2util.h。

登录后查看全文
cppfront