Java Vector API 怎么用 Mask 处理尾部元素

用 Java Vector API 处理数组时，最容易漏掉的是最后一组不足一个向量宽度的元素。安全做法不是把数组补零，也不是让 fromArray 读到边界外，而是在每轮用 VectorSpecies.indexInRange(i, length) 生成有效 lane 的 VectorMask，并把这个 Mask 同时用于加载和写回。这样长度为 10、向量宽度为 4 时，最后一轮只启用前 2 个 lane。

官方文档：https://docs.oracle.com/en/java/javase/25/docs/api/jdk.incubator.vector/jdk/incubator/vector/package-summary.html

先把尾部问题换算成 lane 范围

Vector API 的 VectorSpecies 代表元素类型和向量形状，SPECIES.length() 是一次并行处理的 lane 数。循环下标 i 表示本轮数组起点；第 N 个 lane 实际访问 i + N。因此有效条件就是 0 ≤ i + N 。indexInRange 正是把这个条件批量转换成 Mask。

用同一个 Mask 贯通加载、计算和写回

下面的例子把两个 float[] 相乘。Mask 循环最直观：每轮都计算一次边界，但实现简单，尤其适合需要统一处理任意长度输入的代码。

import jdk.incubator.vector.FloatVector;
import jdk.incubator.vector.VectorMask;
import jdk.incubator.vector.VectorSpecies;

static float[] multiply(float[] left, float[] right) {
    // 先确认输入长度一致，避免尾部 Mask 只保护了其中一个数组
    if (left.length != right.length) {
        throw new IllegalArgumentException("数组长度必须一致");
    }
    float[] result = new float[left.length];
    VectorSpecies species = FloatVector.SPECIES_PREFERRED;

    for (int i = 0; i  mask = species.indexInRange(i, left.length);
        FloatVector a = FloatVector.fromArray(species, left, i, mask);
        FloatVector b = FloatVector.fromArray(species, right, i, mask);
        // 未启用 lane 不参与乘法，结果也不会写到数组范围外
        a.mul(b, mask).intoArray(result, i, mask);
    }
    return result;
}

这里的三个位置要保持一致：两个 fromArray 都使用同一个 Mask，乘法使用它，intoArray 也使用它。未启用的 lane 不参与底层标量操作；不要只给写回加 Mask，却让加载仍使用无 Mask 重载。

大数组可以把完整块和尾循环拆开

Oracle 的 Vector API 包文档还给出另一种组织方式：先用 species.loopBound(length) 得到不超过数组长度的最大完整块，只在这部分调用无 Mask 的加载与运算，剩余元素交给标量循环。Mask 方案更统一；分裂方案通常更容易让主循环保持无分支，但两者都必须以 species.length() 驱动，不能写死 4、8 这类硬件假设。

static void add(float[] target, float[] delta) {
    // 主循环只走完整向量块，尾部由标量循环接管
    if (target.length != delta.length) {
        throw new IllegalArgumentException("数组长度必须一致");
    }
    VectorSpecies species = FloatVector.SPECIES_PREFERRED;
    int bound = species.loopBound(target.length);
    int i = 0;
    for (; i 

Mask 与标量尾循环怎么选

如果代码还要处理切片起点、多个数组或条件运算，Mask 版本更不容易把边界逻辑分散到多个循环里；如果数组通常很长且尾部很短，loopBound 版本可以让绝大多数迭代避开 Mask。选择时关注的是可读性、数据分布和基准测试，不要把“尾部少”直接等同于“Mask 一定慢”。

• Mask 版本：一个循环覆盖任意长度，适合通用库和边界复杂的流水线。
• 完整块加尾循环：主循环更简洁，适合稳定的大批量数组。
• 两者共同边界：Mask 的 limit 是长度上界；species 由运行平台选择；未启用 lane 的结果不要当成有效业务数据读取。

常见问题

为什么不能直接调用无 Mask 的 fromArray？

无 Mask 重载要求整个向量对应的数组区间都合法。最后一轮不足一个完整向量时，直接调用会把越界访问交给 API 处理，不能靠“多出来的 lane 不使用”来规避。

indexInRange 的 limit 包含最后一个下标吗？

不包含。它使用半开区间 [0, limit)，所以数组长度应直接传 array.length，不要传 array.length - 1。

Mask 能否只用于写回？

不建议。尾部安全需要从加载开始贯通；加载、运算和写回使用同一有效范围，逻辑最清楚。