21.6 可回退的编译器内建功能

在 21.4 中，我们利用 Brian Kernighan 算法（x &= x - 1）实现了无符号整数的置 1 位统计。从算法正确性与标准兼容性来看，这一实现无懈可击。然而在现代硬件微架构层面，这种纯软件循环存在显著的性能代沟：针对包含大量置 1 位的 32 位整数，该算法需要经历数十次条件跳转与位运算；而在现代 x86-64 或 ARM 处理器上，硬件通常直接配备了单周期的专用指令（如 x86 上的 POPCNT 指令或 ARM 上的 VCNT）。

在严谨的基础库工程中，我们面临一个核心权衡：能否在支持硬件加速的编译器与目标架构上无缝接入专用指令，而在缺乏扩展支持或跨平台受限的环境中平滑回退至纯 C 算法，同时保证双轨在所有输入全集上的行为严格自洽？

本节我们将位操作加速、字节序翻转、算术溢出探测、分支偏好提示以及编译器特有属性封装为统一的跨平台抽象层：在预处理与编译阶段精准探测当前工具链的能力边界，自适应选取最佳执行路径；一旦环境缺失硬件扩展支持，则无感降级至标准 C 实现。最后，我们将搭建双轨回归体系，确保两条路径在任何边界输入下都能输出完全等价的结果。

1. 内建函数与内部函数

现代主流编译器向开发者暴露底层硬件特权通常遵循三套迥异的技术路线：

• GCC 与 Clang 的内建函数（Built-in Functions）：以 __builtin_ 为命名标识（如 __builtin_popcount、__builtin_clz）。这类符号由编译器前端直接接管，既无需包含特定系统头文件，在底层也往往不会产生常规的 ABI 函数调用开销。编译器会根据目标微架构选项，直接将其内嵌扩展为特定的机器指令，或在指令集不支持时回退为对运行时辅助库（如 libgcc）的调用。
• MSVC 的内部函数（Intrinsics）：微软工具链通过 <intrin.h> 暴露硬件原语（如 _BitScanReverse、__popcnt、_byteswap_ulong）。它们的命名与参数契约具有强烈的平台私有色彩。例如 _BitScanReverse 并非直接返回前导零或位宽，而是通过输出指针写入搜索到的最高有效位下标，并通过整型返回值指示是否存在非零位。
• C23 标准库 <stdbit.h>：作为 ISO C 标准演进的成果，C23 将这批常用位运算接口正式归入标准库命名空间（例如 stdc_count_ones_ui、stdc_leading_zeros_ui 等）。标准统一消除了历史方言的命名割裂，并明确规定了针对输入 0 的返回值契约。

除了显式调用内建函数或内部函数外，还有一条常被忽视的演进路径：现代优化编译器本身具备强大的语法模式识别能力（Pattern Matching）。在 21.4 中手写的纯 C 循环，只要在编译时开启 -O2 -mpopcnt，优化器即可在中间表示阶段将其识别为标准的位统计模式，并自动整段替换为单条 popcntl 指令：

unsigned pop_loop(uint32_t x) {
    unsigned n = 0;

    while (x != 0) {
        x &= x - 1u;
        n++;
    }
    return n;
}

zsh - gcc -S

$ gcc -std=c17 -Wall -Wextra -O2 -mpopcnt -S pop_demo.c -o pop_mp.s
$ sed -n '/^pop_loop:/,/ret/p' pop_mp.s
pop_loop:
	xorl	%eax, %eax
	xorl	%edx, %edx
	popcntl	%ecx, %eax
	testl	%ecx, %ecx
	cmove	%edx, %eax
	ret

这是在 MinGW-w64 GCC 13.2 下得到的优化汇编。指令 cmove 负责兜底处理 x 为 0 的边界情况：由于纯 C 循环在 x == 0 时会直接跳过循环体返回 0，优化器在生成代码时引入了一条条件传送指令以确保逻辑完备。若未在命令行开启 -mpopcnt 架构开关，同一段纯 C 代码则保持逐位计算的常规控制流。这一现象表明：编写规范的标准 C 逻辑并赋予编译器恰当的架构标志，现代优化器往往能自行桥接到底层硬件指令。

内建加速与回退实现必须满足严格的行为同构

内建扩展、编译器内部函数以及标准 C 纯软件实现，是通往同一份功能规格的三种不同执行路径。无论底层走向哪条分支，对于输入定义域内的每一个数值（特别是 0 以及溢出临界点等极端输入），所产生的结果都必须保持完全一致。若某个硬件内建接口在特定输入下属于未定义行为（例如 __builtin_clz(0)），抽象封装层必须在内部予以拦截并完成规格收敛，决不能将底层未定义状态泄露至对外接口。

2. 编译期能力探测

要在预处理阶段无缝挑选最优执行分支，关键在于借助编译器提供的元宏对环境特征进行细粒度探测。

其中最核心的探测工具是 __has_builtin(name)，它用于判断当前编译器是否内置了指定的内建函数。Clang 很早便支持该机制，GCC 则从 10.1 版本开始正式引入。需要注意的是，在较老的编译器上 __has_builtin 这一元宏本身可能尚未定义；若直接使用它作为条件表达式会引发预处理报错。工程中常用的防御性策略是在头文件最前端设定安全回退：

#ifndef __has_builtin
#define __has_builtin(x) 0
#endif

#define MDR_HAS_BUILTIN(x) __has_builtin(x)

针对标准库与系统头文件的可用性，__has_include(...) 提供了直接的探测手段。该操作符最早作为扩展存在于 GCC 与 Clang 中，随后在 C23 规范中被正式收录为标准语法。在 MinGW-w64 GCC 13.2 环境下的实际探测输出如下：

zsh - detect

$ gcc -std=c17 -Wall -Wextra detect.c -o detect && ./detect
has_builtin defined
__builtin_popcount yes
__builtin_clzg no
__builtin_stdc_leading_zeros no
stdbit.h no
__GNUC__ 13
__STDC_VERSION__ 201710
$ gcc -std=c2x -Wall -Wextra detect.c -o detect2 && ./detect2
has_builtin defined
__builtin_popcount yes
__builtin_clzg no
__builtin_stdc_leading_zeros no
stdbit.h no
__GNUC__ 13
__STDC_VERSION__ 202000

当把相同的探测代码迁移至配备 GCC 14.2 的 Linux 环境并启用 -std=c23 时，探测结果发生了关键变化：__builtin_clzg、__builtin_stdc_leading_zeros 以及 <stdbit.h> 均成功点亮，__GNUC__ 上升为 14。但需要高度警惕的是：此时预定义宏 __STDC_VERSION__ 的输出值依然停留在 202000L。

这一细节揭示了跨平台工程中一条极为深刻的经验：根据 ISO C23 正式标准，__STDC_VERSION__ 的官方终值被定为 202311L。然而在许多现实发行的编译器中（例如 GCC 14），即便开启 -std=c23 且各类 C23 头文件与新特性均已完备就绪，编译器给出的版本标识依然保持着过渡期的数值（202000L）：

zsh - ver

$ gcc -std=c23 -Wall -Wextra ver.c -o ver && ./ver
__STDC_VERSION__ = 202000L
does not reach 202311L

如果代码中死板地书写 #if __STDC_VERSION__ >= 202311L 来推断环境是否支持 C23 库，就会直接将大量已经具备 <stdbit.h> 支持的现代编译器（如 GCC 14 全系）拒之门外。

因此，工业级实践应当秉承“探查特性本身，而非臆测版本号”的原则：对于头文件依赖直接使用 __has_include，针对特定内建符号使用 __has_builtin，对于语法属性使用 __has_c_attribute（详细规则可参阅属性）。粗粒度的语言版本宏仅适合在完全掌握各工具链历史怪癖的前提下作为次要参考。

面向具体功能探测，避开版本号猜测

评估语言与库特性是否就绪时，应当直接针对特性本身设立探针：头文件包含依赖 __has_include，内建指令加速依赖 __has_builtin，语法属性依赖 __has_c_attribute。各编译器发行的 __STDC_VERSION__ 真实落地节奏往往滞后于特性本身的交付速度。单凭版本号设卡，极易错失本已就绪的现代特性支持。

编译器身份识别宏（如 __GNUC__、__clang__、_MSC_VER）依然在特定场景下不可或缺，但它们的主要职责是区分不同的编译器家族体系。需要留意的是，Clang 为了保持与 GNU 生态的兼容性，默认也会定义 __GNUC__，因此在分支判断时若需对 Clang 做特殊处理，必须将其前置判断；MSVC 则通过四位整型的 _MSC_VER 表征主次版本（例如 Visual Studio 2022 17.14 所配套的 cl 19.51 对应 _MSC_VER == 1951）。

单选

要判断当前环境能不能包含并使用 C23 的 <stdbit.h>，下面哪种写法最可靠？

#if __STDC_VERSION__ >= 202311L

#if __has_include(<stdbit.h>)

#if __GNUC__ >= 14

#if defined(_MSC_VER) && _MSC_VER >= 1951

3. 分层回退设计：以 popcount 为例

将前文的能力探测机制融汇落地，我们构建专用头文件 include/mdr_compiler.h。首先确立编译期特性总开关：允许项目通过外部预定义宏主动切断一切平台内建扩展，以便于纯净环境验证与缺陷复现：

#if defined(MDR_NO_BUILTINS)
#define MDR_USE_BUILTINS 0
#else
#define MDR_USE_BUILTINS 1
#endif

紧接着开展标准 C23 头文件的探测工作。此项检查仅在允许启用内建加速的环境下执行，且严格使用 __has_include 进行原子探测：

#if MDR_USE_BUILTINS && defined(__has_include)
#if __has_include(<stdbit.h>)
#include <stdbit.h>
#define MDR_HAVE_STDBIT 1
#endif
#if __has_include(<stdckdint.h>)
#include <stdckdint.h>
#define MDR_HAVE_STDCKDINT 1
#endif
#endif
#ifndef MDR_HAVE_STDBIT
#define MDR_HAVE_STDBIT 0
#endif
#ifndef MDR_HAVE_STDCKDINT
#define MDR_HAVE_STDCKDINT 0
#endif

在 src/mdr_bits.c 中，mdr_popcount_u32 依循一套严密的层级次序自上而下选路：

unsigned mdr_popcount_u32(uint32_t value) {
#if MDR_HAVE_STDBIT
    return (unsigned)stdc_count_ones_ui(value);
#elif MDR_USE_BUILTINS && MDR_HAS_BUILTIN(__builtin_popcount)
    return (unsigned)__builtin_popcount(value);
#elif MDR_USE_BUILTINS && defined(_MSC_VER)
    return (unsigned)__popcnt(value);
#else
    unsigned count = 0;

    while (value != 0) {
        value &= value - 1u;
        count++;
    }
    return count;
#endif
}

这套级联优先级的排布体现了清晰的工程考量：

1. 标准优先：ISO C23 标准接口（<stdbit.h>）位居最高优先级；
2. 编译器通用内建次之：GCC 与 Clang 广泛支持的 __builtin_ 接口次之；
3. 专有方言再次：MSVC 内部函数紧随其后；
4. 标准 C 算法兜底：纯 C 循环作为绝对稳健的基石垫底。

需要注意不同编译器在面对缺少硬件指令时的应对策略分歧：MSVC 的 __popcnt 假定运行目标机必然支持 POPCNT 机器指令，在老旧 32 位 x86 处理器上若未经指令集检测直接调用可能触发非法指令异常；而 GCC/Clang 的 __builtin_popcount 在未指定 -mpopcnt 开关时，会自动将调用降级为链接期对 libgcc 库函数 __popcountdi2 的调用，从而在任意 CPU 架构上均能平稳运行。

当外部定义了 MDR_NO_BUILTINS 时，预处理器会强行将所有路径引流至最后一条标准 C 分支。这就为工程在同一套代码仓库内构建“内建加速版”与“纯 C 回退版”两套测试靶标创造了基础。

生成的汇编代码能够清晰还原各选路分支的底层形态。我们针对 21.4 的源码在四种典型配置下分别导出汇编：

zsh - gcc -S

$ gcc -std=c17 -Wall -Wextra -Iinclude -O2 -S src/mdr_bits.c -o lib_builtin.s
$ gcc -std=c17 -Wall -Wextra -Iinclude -O2 -mpopcnt -S src/mdr_bits.c -o lib_builtin+mpopcnt.s
$ gcc -std=c17 -Wall -Wextra -Iinclude -O2 -DMDR_NO_BUILTINS -S src/mdr_bits.c -o lib_fallback.s
$ sed -n '/^mdr_popcount_u32:/,/ret/p' lib_builtin.s
mdr_popcount_u32:
	subq	$40, %rsp
	movl	%ecx, %ecx
	call	__popcountdi2
	addq	$40, %rsp
	ret
$ sed -n '/^mdr_popcount_u32:/,/ret/p' lib_builtin+mpopcnt.s
mdr_popcount_u32:
	xorl	%eax, %eax
	popcntl	%ecx, %eax
	ret

四种组合在编译器眼中的转换结果如下：

配置	生成代码	原因
默认（-O2）	call __popcountdi2	内建函数在无专用指令时委托至底层运行库
默认 + -mpopcnt	popcntl 单条指令	目标指令集显式开启，内建直接折叠为机器指令
回退（-O2）	andl/addl/jne 循环体	未开架构开关，编译器未对该循环做硬件化折叠
回退 + -mpopcnt	popcntl、test、cmove	优化器识别出算法模式，并自动兜底边界条件

在配备 GCC 14.2 的 Linux 环境下，前两行的行为与上述结论高度一致（仅在 ABI 传参寄存器与 @PLT 符号解析记法上存在平台差异）。

比对第三行与第四行可以发现，优化器的汇编生成细节会伴随编译器版本迭代而演变：在 MinGW-w64 GCC 13.2 环境下，“纯 C 回退 + -mpopcnt”在识别出循环后，额外生成了 testl 与 cmove 来保证输入为 0 时的逻辑闭环；而迁移到 GCC 14.2 后，优化器进一步化简了分支，直接落成单条 popcntl 指令。这直观印证了一条性能优化铁律：切忌凭静态阅读汇编或对指令条数的经验推测来预判系统吞吐，唯有真实基准测量才能给出客观答案。

内建函数不必然带来性能飞跃

前述对照表第一行表明：在未开启目标架构扩展（缺少专用硬件指令）时，__builtin_popcount 并不能施展硬件魔法，仅仅是将手写循环转变成对底层运行时库函数 __popcountdi2 的外部调用。这反而引入了栈帧开销与函数调用跳转。内建接口的实际性能红利高度依附于目标处理器的微架构配置；在性能敏感路径上，审视最终落地的汇编输出至关重要。

4. 抹平未定义行为与语义分歧

在 C23 <stdbit.h> 规范中，四个前导与尾随计数函数均确立了清晰的数学边界契约：当输入为 0 时，返回对象的全位宽（32 位无符号整数返回 32，64 位返回 64）。然而在编译器扩展层面，GCC 与 Clang 的 __builtin_clz(0) 和 __builtin_ctz(0) 在官方手册中被明确标记为未定义行为（Undefined Behavior）。

若未经拦截便将裸内建函数暴露给上层，一旦调用方传入 0，程序的运行结果将彻底失控：

zsh - clz0

$ gcc -std=c17 -Wall -Wextra -O0 clz0.c -o clz0 && ./clz0
__builtin_clz(0) = 31
__builtin_ctz(0) = 32
$ gcc -std=c17 -Wall -Wextra -O2 clz0.c -o clz0o2 && ./clz0o2
__builtin_clz(0) = -1290901457
__builtin_ctz(0) = 32
$ ./clz0o2
__builtin_clz(0) = 1839312102
__builtin_ctz(0) = 32

在未开启优化的 -O0 下，__builtin_clz(0) 恰好返回了 31（这是 x86 BSR 指令在目标寄存器未被覆写时的历史残留值），表象上极具迷惑性；而在开启 -O2 后，编译器基于未定义行为的自由优化空间，使得同一行表达式在两次独立运行时输出了完全不同的伪随机数值。为防止常量折叠掩盖这一缺陷，测试中特意通过 volatile 注入运行期数值。__builtin_ctz(0) 即使碰巧输出了 32，在语言标准层面同样没有任何保证。

解决这一语义裂痕的代码极其精炼，只需在抽象层主动截断 0 的非法传播：

❌ 直接暴露内建函数

unsigned mdr_clz_u32(uint32_t x) {
    return (unsigned)__builtin_clz(x);
}

✅ 先处理 0 再调用

unsigned mdr_clz_u32(uint32_t x) {
    return x == 0 ? 32u : (unsigned)__builtin_clz(x);
}

这一判断仅引入了一条条件跳转，且现代编译器往往能将其与后续指令紧密结合。审视两种实现方式在 -O2 下的汇编输出：

zsh - clzasm

$ gcc -std=c17 -Wall -Wextra -O2 -S clzasm.c -o clzasm.s
$ sed -n '/^clz_builtin:/,/ret/p' clzasm.s
clz_builtin:
	bsrl	%ecx, %eax
	xorl	$31, %eax
	ret
$ sed -n '/^clz_wrapped:/,/ret/p' clzasm.s
clz_wrapped:
	movl	$32, %eax
	testl	%ecx, %ecx
	je	.L3
	bsrl	%ecx, %eax
	xorl	$31, %eax
.L3:
	ret

BSR（Bit Scan Reverse）指令在底层只负责定位最高有效位所在的下标，随后优化器借助异或指令 xorl $31, %eax 将下标换算为前导零数量。包装版本中增加的 movl $32, %eax 与 je .L3 构成了严格的零值防线，这是为了抹平硬件盲区、换取全输入空间语义确定性而必须付出的代价。

相同的防护原则同样贯穿于其余位操作原语中：

• __builtin_ctz 对输入 0 未定义，包装层统一拦截并返回 32；
• 64 位版本 __builtin_clzll 与 __builtin_ctzll 对输入 0 未定义，统一包装为返回 64；
• MSVC 体系下的 _BitScanReverse 与 _BitScanForward 在入参为 0 时返回布尔假，抽象层依据该返回值将其归一化为 32。

在 MSVC 环境下的适配实现如下：

unsigned mdr_clz_u32(uint32_t x) {
    unsigned long index;

    return _BitScanReverse(&index, x) ? 31u - (unsigned)index : 32u;
}

当 _BitScanReverse 探测到至少一个置 1 位时，它将最高位下标写入输出对象 index 并返回非零；若入参全为 0，则返回 0。我们通过三元表达式将其换算为规格所需的前导零计数。经由 MSVC 14.51 编译验证，该实现与 21.4 的纯 C 回退版本在全部典型测试集上表现完全等价。

字节序翻转与安全算术溢出检测同样遵循这套适配思路。内建函数 __builtin_bswap32 与 __builtin_bswap64 在全定义域内均有合法定义，无需前置条件分支拦截；MSVC 体系下则直接对应 _byteswap_ulong 与 _byteswap_uint64。

而在带检查的加法运算中，我们通过宏统一了三代技术规范的差异：

#if MDR_HAVE_STDCKDINT
#define MDR_CKD_ADD_SIZE(a, b, res) (ckd_add((res), (a), (b)))
#elif MDR_USE_BUILTINS && MDR_HAS_BUILTIN(__builtin_add_overflow)
#define MDR_CKD_ADD_SIZE(a, b, res) __builtin_add_overflow((a), (b), (res))
#else
#define MDR_CKD_ADD_SIZE(a, b, res)                                            \
    ((a) > SIZE_MAX - (b) ? true : (*(res) = (a) + (b), false))
#endif

无论是 C23 的 ckd_add，还是 GCC/Clang 的 __builtin_add_overflow，均统一遵循“运算溢出时返回布尔真，并将截断或有效和存入输出指针对象”的语义，二者能够零成本无缝对齐。在纯 C 兜底分支中，宏直接展开了 21.4 的安全保护逻辑：保证操作数 a 与 b 仅被求值一次，且仅在无溢出风险时才执行解引用赋值。三条路径在返回值状态与写入契约上严密一致，在测试套件中全部通过。

5. 分支偏好与不可达优化提示

分支预测提示旨在向编译器的控制流分析器传递概率先验信息，促使优化器将大概率执行的热路径（Hot Path）排列成紧凑的直行汇编流水线，并将小概率异常分支移至主代码块之外以减少指令缓存命中惩罚：

#if MDR_USE_BUILTINS && (defined(__GNUC__) || defined(__clang__))
#define MDR_LIKELY(x) __builtin_expect(!!(x), 1)
#define MDR_UNLIKELY(x) __builtin_expect(!!(x), 0)
#define MDR_UNREACHABLE() __builtin_unreachable()
#elif MDR_USE_BUILTINS && defined(_MSC_VER)
#define MDR_LIKELY(x) (x)
#define MDR_UNLIKELY(x) (x)
#define MDR_UNREACHABLE() __assume(0)
#else
#define MDR_LIKELY(x) (x)
#define MDR_UNLIKELY(x) (x)
#define MDR_UNREACHABLE() abort()
#endif

在宏定义中使用双重逻辑非 !!(x)，目的是将任意非零标量值强制规整为标准的整数 1，因为 __builtin_expect 的第二个形参类型为 long，参与的是数值字面量比对而非真值评估。在不支持该内建特性的回退分支中，宏被安全降级为外层带括号的表达式 (x)，以防在复杂复合条件（如 if (MDR_LIKELY(a) && b)）中发生运算符优先级撕裂。

MDR_UNREACHABLE() 宣告控制流在逻辑上绝不会触及该位置，编译器据此可以在数据流分析中直接剪除后续的一切冗余判断。在现代规范中，C23 提供了标准宏 unreachable()；GCC 与 Clang 使用 __builtin_unreachable()；MSVC 体系则对应于 __assume(0)；在缺乏这组编译期暗示的标准回退路径下，则降级为直接调用 abort()。

这两种处理方式存在关键的工程差异：若程序由于逻辑漏洞意外触及了该断点，__builtin_unreachable() 会放任 CPU 带着错误的假设继续穿透执行，导致完全未定义的崩溃或内存破坏；而 abort() 则会当场触发异常退出中断。因此在工程调试配置下，将未达提示回退至 abort() 有利于尽早暴露潜在隐患，而在发布版本中则利用其换取激进的代码剪裁。

在工程实践中，分支提示应当保持高度克制。仅在性能剖析（可参阅第 15 章）证实存在明确流水线停顿时才值得针对性标记；现代处理器的动态分支预测器以及编译器基于采样数据的引导优化（PGO）往往比手工硬编码的分支暗示更为精准，滥用甚至可能导致热冷路径反转而降低指令缓存利用率。

多选

关于 mdr_compiler.h 里的优化提示与属性宏，下列说法正确的是哪些？

MDR_UNREACHABLE() 真的被执行到时，所有实现都是未定义行为

没有内建函数时，MDR_LIKELY(x) 展开成 (x)

MDR_LIKELY 的定义里可以省掉 x 外面的括号

定义 MDR_NO_ATTRIBUTES 后，MDR_PRINTF_LIKE 展开为空

6. 编译器属性与静态检查宏

语言属性（Attributes）用于向编译器前端提供元数据，以强化类型安全分析与死代码消除。在历史演进中，GCC/Clang 的 GNU 属性语法（__attribute__((...))）、MSVC 的 SAL 注解（_Check_return_）与 C23 的双中括号标准属性（[[...]]）各行其道。本库设计了一组具备无缝退化能力的统一包装宏：

#if (defined(__GNUC__) || defined(__clang__)) && !defined(MDR_NO_ATTRIBUTES)
#define MDR_NODISCARD __attribute__((warn_unused_result))
#define MDR_MAYBE_UNUSED __attribute__((unused))
#define MDR_FALLTHROUGH __attribute__((fallthrough))
#define MDR_PRINTF_LIKE(fmt, args) __attribute__((format(printf, fmt, args)))
#else
#define MDR_NODISCARD
#define MDR_MAYBE_UNUSED
#define MDR_FALLTHROUGH
#define MDR_PRINTF_LIKE(fmt, args)
#endif

在这组宏中，MDR_PRINTF_LIKE(fmt, args) 在工程协作中的价值尤为突出。它促使编译器前端将目标自定义函数的调用点纳入格式化字符串静态检查范围：只要入参的格式占位符与后随的实参类型发生偏差（例如用 %d 打印字符串），编译器便会立即给出精准的类型错位诊断。给一个日志函数加上它：

MDR_PRINTF_LIKE(1, 2)
static void mdr_log(const char *fmt, ...) {
    va_list ap;

    va_start(ap, fmt);
    vfprintf(stderr, fmt, ap);
    va_end(ap);
}

MDR_NODISCARD
static int mdr_write_all(const char *path, const char *data);

int main(void) {
    mdr_write_all("out.bin", "abc");
    mdr_log("value = %d\n", "text");
    return 0;
}

编译时两条警告一起出现：

zsh - attr_demo

$ gcc -std=c17 -Wall -Wextra -Iinclude attr_demo.c -o attr_demo
attr_demo.c: In function 'main':
attr_demo.c:23:23: warning: format '%d' expects argument of type 'int', but argument 2 has type 'char *' [-Wformat=]
   23 |     mdr_log("value = %d\n", "text");
      |                      ~^     ~~~~~~
      |                       |     |
      |                       int   char *
      |                      %s
attr_demo.c:22:5: warning: ignoring return value of 'mdr_write_all' declared with attribute 'warn_unused_result' [-Wunused-result]
   22 |     mdr_write_all("out.bin", "abc");
      |     ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
$ gcc -std=c17 -Wall -Wextra -DMDR_NO_ATTRIBUTES -Iinclude attr_demo.c -o attr_demo_noattr

第二条命令一行警告也没有，两个属性被定义成空之后代码照样编译。

在 format(printf, fmt, args) 的语法契约中，fmt 与 args 分别代表格式控制串在形参列表中的 1 索引位置，以及首个可变参数（...）的 1 索引位置。在上面的 mdr_log(fmt, ...) 示例中，两者分别对应 1 与 2。若参数索引标注错位，编译器将在错误的形参上执行类型比对，输出令人费解的虚假诊断。

MDR_NODISCARD 则针对必须校验处理返回状态的关键接口（例如资源分配、文件写入、系统调用等）设立保护。它虽然无法强制生成错误处理逻辑，却能在调用方无意忽略返回值时第一时间抛出编译警告，防范资源泄漏与隐蔽错误传播。

当外部定义了 MDR_NO_ATTRIBUTES 时，所有属性宏均被预处理器视为空文本展开。此时同一份业务代码依然能够以零阻碍成功编译。确保“剥除所有属性注解后系统仍能纯净编译通过”，是工程层可回退设计的另一块坚实拼图。

7. 双轨回归测试设计

mdr_compiler.h 的所有条件检测均固化在预处理期。在常规的单次编译构建中，生成的二进制产物要么完全走向内建加速分支，要么完全走向纯 C 回退分支。这带来了一个隐蔽的工程盲区：如果日常自动化测试仅覆盖默认的内建分支，回退分支很可能在某次代码重构后悄悄损坏，直至代码被部署到缺乏内建支持的小众架构时才暴露出致命缺陷。

为了建立严密的防线，构建系统必须采用“同一套测试用例，双向并行绑定”的工程策略：同时编译出常规库与强制回退库两个静态靶标，并将全部测试套件在两个版本上分别挂载一遍。

在 CMake 构建脚本中引入双轨目标：

if(NOT MDR_NO_BUILTINS)
    add_library(mdr_fallback STATIC ${MDR_SOURCES})
    target_include_directories(mdr_fallback PUBLIC "${CMAKE_CURRENT_SOURCE_DIR}/include")
    target_compile_definitions(mdr_fallback PUBLIC MDR_NO_BUILTINS=1)
endif()

测试用例的注册随之扩展为成对结构：每个测试源码同时编译为默认可执行目标与后缀为 _fallback 的对照目标，并作为独立的 ctest 用例参与回归：

foreach(test_src IN LISTS MDR_UNIT_TESTS)
    get_filename_component(test_name "${test_src}" NAME_WE)
    add_executable(${test_name} "${test_src}" tests/check.c)
    target_link_libraries(${test_name} PRIVATE mdr)
    add_test(NAME ${test_name} COMMAND ${test_name})

    if(TARGET mdr_fallback)
        add_executable(${test_name}_fallback "${test_src}" tests/check.c)
        target_link_libraries(${test_name}_fallback PRIVATE mdr_fallback)
        add_test(NAME ${test_name}_fallback COMMAND ${test_name}_fallback)
    endif()
endforeach()

在 Linux 环境下构建并运行测试套件：

zsh - ctest

$ cmake -S . -B build
$ cmake --build build -j2
$ ctest --test-dir build
Test project /home/minsecrus/tutorial/work/p069/mdr/build
    Start 1: test_bits
1/8 Test #1: test_bits ........................   Passed    0.00 sec
    Start 2: test_bits_fallback
2/8 Test #2: test_bits_fallback ...............   Passed    0.00 sec
    Start 3: test_ext
3/8 Test #3: test_ext .........................   Passed    0.00 sec
    Start 4: test_ext_fallback
4/8 Test #4: test_ext_fallback ................   Passed    0.00 sec
    Start 5: test_memory
5/8 Test #5: test_memory ......................   Passed    0.00 sec
    Start 6: test_memory_fallback
6/8 Test #6: test_memory_fallback .............   Passed    0.00 sec
    Start 7: test_string
7/8 Test #7: test_string ......................   Passed    0.00 sec
    Start 8: test_string_fallback
8/8 Test #8: test_string_fallback .............   Passed    0.00 sec

100% tests passed, 0 tests failed out of 8

Total Test time (real) =   0.02 sec
$ ./build/test_bits
test_bits: 99 checks, 0 failed
$ ./build/test_ext
test_ext: 66 checks, 0 failed

八项测试用例（四对镜像目标）全部平稳通过（在后续 21.7 中还将进一步加入针对海量随机数据的差分测试）。完全相同的断言集在两个库版本上均交出绿灯，有力证明了能力探测层与回退算法在功能上完全等价。随后开启 -DMDR_SANITIZE=ON 再次执行完整回归，确保两条路径均未触发任何未定义行为或内存越界：

zsh - ctest

$ cmake -S . -B build-asan -DMDR_SANITIZE=ON
$ cmake --build build-asan -j2
$ ctest --test-dir build-asan
Test project /home/minsecrus/tutorial/work/p069/mdr/build-asan
    Start 7: test_string
7/8 Test #7: test_string ......................   Passed    0.02 sec
    Start 8: test_string_fallback
8/8 Test #8: test_string_fallback .............   Passed    0.02 sec

100% tests passed, 0 tests failed out of 8

Total Test time (real) =   0.15 sec

在此之外，还有两个维度的跨平台行为值得单列核验：

第一，观测多编译器方言的指令翻译差异。在相同的源码下使用 Clang 22 开启 -O2 编译 mdr_bits.c：当未指定 -mpopcnt 时，Clang 并没有像 GCC 那样生成对运行时库 __popcountdi2 的外部调用，而是直接将其内联展开为一组基于位移与掩码的并行加法指令流（分治相加算法），消除了函数调用上下文切换；当开启 -mpopcnt 后，Clang 与 GCC 均一致折叠为单条 popcntl 指令。而在指定 MDR_NO_BUILTINS 时，各编译器均忠实生成标准的逐位循环。这说明不同编译器在“内建函数缺少直属硬件指令”时的策略各有侧重，但抽象层的行为契约始终稳固。

第二，针对 MSVC 内部函数执行原生验证。在 Windows 原生命令行中，可以直接调用 MSVC 的 cl 编译器构建测试：

cl /nologo /W4 /std:c17 /utf-8 /Iinclude src\mdr_string.c src\mdr_memory.c ^
   src\mdr_bits.c src\mdr_ext.c tests\check.c tests\test_bits.c /Fe:test_bits_msvc.exe
.\test_bits_msvc.exe
test_bits: 99 checks, 0 failed

其中编译选项 /utf-8 是必不可少的，用于防止 MSVC 在默认的系统代码页（如 GBK/CP936）下将 UTF-8 编码的源文件注释误判为非法字符。此项测试在 Visual Studio 2022（MSVC 14.51）下顺利通过，验证了基于 _BitScanReverse 与 _BitScanForward 的位宽换算逻辑与 GCC 回退实现完全一致。

在持续集成流水线中部署跨平台矩阵测试的具体流程已在第 18 章中深入探讨。这里沉淀出一条核心法则：两个变体库，共用同一套回归集。决不能仅凭默认环境的通过来揣测回退分支的健康度。

8. 习题

8.1 巩固

#22161

⚡2⏳2

正文第 3 节用四种配置编译 mdr_bits.c 看了 mdr_popcount_u32 的汇编。不用运行，先按正文那张表推断下面四种配置各自会落成什么，再动手核对：

(1) -O2、-O2 -mpopcnt、-O2 -DMDR_NO_BUILTINS、-O2 -DMDR_NO_BUILTINS -mpopcnt 四份汇编里，mdr_popcount_u32 分别是：调用运行库、一条 popcntl、一个 andl 循环、popcntl 加 test 加 cmove。把四段汇编贴出来，与推断对照。

(2) 第四种配置里多出的 test 和 cmove 针对的是哪个输入？先用 popcntl 对 0 的结果推断这两条指令对返回值有没有影响，再用 mdr_popcount_u32(0) 跑一遍核对。

(3) 把同一个实验对 mdr_clz_u32 做一遍。默认配置与 -DMDR_NO_BUILTINS 下各是哪几条指令，为什么回退版要多一个循环？再单独用 -DMDR_NO_BUILTINS -mpopcnt 编一次，循环还在不在？

#22162

⚡3⏳3

写一个探针程序 detect.c，用预处理把当前环境的下列信息打印出来：

printf("has_builtin defined\n");                    /* #if defined(__has_builtin) */
printf("__builtin_popcount %d\n", ...);             /* __has_builtin(...) */
printf("__builtin_clzg %d\n", ...);
printf("stdbit.h %d\n", ...);                       /* __has_include(<stdbit.h>) */
printf("stdckdint.h %d\n", ...);
printf("nodiscard %ld\n", ...);                     /* __has_c_attribute(nodiscard) */
printf("__GNUC__ %d\n", __GNUC__);
printf("__STDC_VERSION__ %ld\n", (long)__STDC_VERSION__);

(1) 用 -std=c17 和 -std=c2x 各编一次，记录两行的差别。__STDC_VERSION__ 在 -std=c2x 下是 202000L 而不是 202311L，说明为什么不能拿它当「有没有 C23 库」的门槛。

(2) 把 MDR_HAS_BUILTIN(x) 改成直接写 __has_builtin(x)，宏定义不要包 #ifndef，再用 gcc -U__has_builtin 编译。记录报错原文，说明本库为什么要给一个默认为 0 的定义。

(3) 在探针里加一行 #if defined(__has_c_attribute) && __has_c_attribute(nodiscard) >= 202003L，在 -std=c17 下能否通过？再把 defined(__has_c_attribute) && 去掉、用 -U__has_c_attribute 编译，记录报错，说明为什么属性检测也要先判断 __has_c_attribute 本身在不在。

#22163

⚡3⏳3

正文第 4 节说 __builtin_clz(0) 是未定义行为，包装层必须先处理 0。下面这个包装处理了一半：

static unsigned buggy_clz_u32(uint32_t x) {
    return x == 0 ? 32u : (unsigned)__builtin_clzll(x);
}

(1) 写一个「显然正确」的慢版本：从 0x80000000 起逐位左移数前导零，x 为 0 时返回 32。用它对 0 到 0xFFFF 的每个输入比较，记录不一致的个数和第一个不一致的输入。

(2) 对 0x80000000、1、0x00FF0000 三个输入各写出缺陷版与慢版本的结果，解释 clzll 与 clz 返回值为什么差 32。

(3) 给出修正写法（只改一处），再跑一遍差分，确认 0 个不一致。

(4) 为什么这里不用 __builtin_clz 当参照实现？用一句话说清。

#22164

⚡4⏳3

正文的 MDR_CKD_ADD_SIZE 有三条分支：<stdckdint.h> 的 ckd_add、__builtin_add_overflow、手写减法判断。照着它写一个 MDR_CKD_MUL_SIZE，再用计数器验证每个实参只求值一次。

(1) 宏的第三条分支写成 ((b) != 0 && (a) > SIZE_MAX / (b) ? true : (*(res) = (a) * (b), false))。用 static size_t next_a(void)、next_b(void) 各返回 3 和 4、每次调用把计数器加一，写成 MDR_CKD_MUL_SIZE(next_a(), next_b(), &r)，打印 calls_a、calls_b，记录实际次数。

(2) 同样的调用换成 mul_once((a), (b), (res)) 形式的辅助函数，次数是多少？

(3) 溢出路径上 *res 有没有被写？用 SIZE_MAX 与 2 验证，并说明条件表达式 ?: 的求值规则怎样保证这一点。

(4) 用 -O0 和 -O2 各跑一次，确认观察到的次数与优化级别无关。

8.2 编程

#22165

⚡4⏳3

MDR_UNREACHABLE() 在 GCC/Clang 上展开成 __builtin_unreachable()，回退时展开成 abort()。写一个对比程序：

static int half(int x) {
    if (x < 0) {
        MDR_UNREACHABLE();
    }
    if (x < 0) {
        return -1;
    }
    return x / 2;
}

(1) 用 -DUSE_BUILTIN 和不用它各编一遍，在 -O0、-O2 下用 volatile int v = -3; half(v) 调用。把四次运行的结果记下来。

(2) 用 gcc -O2 -S 看 half 的汇编：带 __builtin_unreachable() 的版本里，第二个 if 还在吗？编译器据什么把它删掉？

(3) 用退出状态区分两种构建（abort() 那一版应当以非零状态终止）。说明为什么调试构建要用 abort()，发布构建才考虑用未定义换优化。

(4) 把这段代码收进库里需要额外注意什么？为什么正文建议 MDR_UNREACHABLE() 只在确实不可能到达的地方用。

#22166

⚡4⏳3

日志函数常带一个级别参数：void mdr_logf(int level, const char *fmt, ...)。给它加 MDR_PRINTF_LIKE 时，位置参数写错会得到完全不同、且看不出所以然的诊断。

(1) 分别用 MDR_PRINTF_LIKE(2, 3)、MDR_PRINTF_LIKE(1, 2)、MDR_PRINTF_LIKE(2, 1) 标注同一个函数，用 gcc -std=c17 -Wall -Wextra -c 编译，记录警告或错误原文。哪一种能正确检查调用点？

(2) 写一行故意错的调用 mdr_logf(1, "value = %d\n", "text")，在正确的标注下记下诊断里的「期望类型」和「实际类型」，以及在零标注下的行为。

(3) 给一个「返回值必须检查」的写文件函数加 MDR_NODISCARD，忽略返回值时编译，记录警告。再定义 MDR_NO_ATTRIBUTES 编译同一份源文件，确认一行警告也没有。

(4) 一个 static 辅助函数只在一个构建配置里被调用，另一个配置里没人用。加上 MDR_MAYBE_UNUSED 前后各编一次，记录 -Wunused-function 的出现与消失。

#22167

⚡5⏳4

正文第 7 节用 -DMDR_NO_BUILTINS 编出第二套库，两套链接同一组测试。这一题的验收点就是「只测一套会漏」。

(1) 按正文的 CMake 片段，在 CMakeLists.txt 里加 mdr_fallback 目标和 test_<名字>_fallback 注册。构建后运行 ctest --test-dir build，记录测试总数与 test_bits、test_bits_fallback 各通过多少项。

(2) 往 src/mdr_bits.c 的回退分支里注入一个缺陷：把 mdr_popcount_u32 的循环条件从 while (value != 0) 改成 while (value > 1)。重新构建，分别运行 test_bits 与 test_bits_fallback，记录哪一个失败、失败信息里报的是哪个输入。

(3) 说明为什么这个缺陷在默认构建里完全不可见，而在另一台没有内建函数的平台上就是实打实的错误。

(4) 恢复代码，再加一个 -DMDR_SANITIZE=ON 的构建目录跑一遍。MinGW 上这一步会失败，记录错误信息并说明该去哪类机器上做。

#22168

⚡5⏳4

上一题是两套库各跑一次。还有一种做法：把同一份 mdr_bits.c 编两次、改掉回退版的符号名，链接进同一个程序，让两条路径在同一次运行里逐个输入对比。

(1) 用 objcopy --prefix-symbols=fb_ 给回退版 mdr_bits.c 的目标文件加前缀，写一个程序同时调用 mdr_popcount_u32 与 fb_mdr_popcount_u32，对 0 到 0xFFFF 逐个比较，输出不一致个数。

(2) 用 nm 查看加前缀前后的符号表，看出哪些符号被改了名。为什么这个办法能避开重复定义的链接错误？

(3) 把同样的 --prefix-symbols 用在 mdr_ext.c 的目标文件上，再链接一次。nm 里会看到什么，链接为什么失败？改用 objcopy --redefine-syms、只把 nm 里那些 T 开头的 mdr_* 名字列进改名表，能不能解决？说明两种做法分别改了什么。

(4) 与正文的两套库做法比较：各自的优点是什么（一个能测完整接口与 ctest 集成，一个能在一次运行里直接对照），代价是什么。

(5) 比较对象扩展到 mdr_clz_u32、mdr_ctz_u32，确认三条都一致。若某一条不一致，报告里要能直接指出是哪个函数、哪个输入。

8.3 综合与挑战

#22169

⚡6⏳4拓展

正文提到 __builtin_popcount 在没有 -mpopcnt 时退化成运行库调用，而 MSVC 的 __popcnt 要求目标机支持该指令。第三种做法是运行时选择：

__attribute__((target("popcnt")))
static unsigned pop_hw(uint32_t x) {
    return (unsigned)__builtin_popcount(x);
}

(1) 用 __builtin_cpu_supports("popcnt") 在运行时判断，支持时走 pop_hw，否则走普通 C 版本。对 0 到 0xFFFF 全部输入比较两条路径的结果，要求 0 个不一致。

(2) 用 -O2 -S 看 pop_hw 与普通 C 版本的汇编，贴出两者。target("popcnt") 起的作用是什么？不加它、只加 -mpopcnt 对整份文件有什么风险？

(3) 这个做法在什么情况下值得？从三个方面回答：目标机是否可能缺少该指令、函数调用的间接开销、以及是否需要为此维护两套编译产物。

(4) 把同样的结构套到 mdr_clz_u32 上（对应 lzcnt）。注意 __builtin_clz(0) 仍是未定义行为，包装层的 0 判断不能省。写完后说明：为什么这类「运行时派发」通常写在库的初始化阶段，而不是每个调用点都判断一次。

9. 参考资料

• GCC 手册，Bit Operation Builtins：https://gcc.gnu.org/onlinedocs/gcc/Bit-Operation-Builtins.html
• GCC 手册，Other Builtins：https://gcc.gnu.org/onlinedocs/gcc/Other-Builtins.html
• GCC 手册，Integer Overflow Builtins：https://gcc.gnu.org/onlinedocs/gcc/Integer-Overflow-Builtins.html
• GCC 手册，__has_builtin：https://gcc.gnu.org/onlinedocs/cpp/_005f_005fhas_005fbuiltin.html
• GCC 10 Changes（__has_builtin 的引入）：https://gcc.gnu.org/gcc-10/changes.html
• Clang 文档，Language Extensions：https://clang.llvm.org/docs/LanguageExtensions.html
• Microsoft Learn，_BitScanReverse、_BitScanReverse64：https://learn.microsoft.com/en-us/cpp/intrinsics/bitscanreverse-bitscanreverse64
• Microsoft Learn，__popcnt16、__popcnt、__popcnt64：https://learn.microsoft.com/en-us/cpp/intrinsics/popcnt16-popcnt-popcnt64
• Microsoft Learn，_byteswap_uint64、_byteswap_ulong、_byteswap_ushort：https://learn.microsoft.com/en-us/cpp/c-runtime-library/reference/byteswap-uint64-byteswap-ulong-byteswap-ushort
• cppreference，unreachable：https://en.cppreference.com/w/c/program/unreachable
• cppreference，<stdbit.h>：https://en.cppreference.com/w/c/header/stdbit
• cppreference，<stdckdint.h>：https://en.cppreference.com/w/c/header/stdckdint