仓颉并发编程:std.sync 包 AtomicUInt16 原子操作类型实战指南

原创2026-10-14 10:43:271,330 阅读
文章标签:人工智能AI 技能文档开发工具

仓颉并发编程:std.sync 包 AtomicUInt16 原子操作类型实战指南

本文基于 DocAgent 仓库中的 std.sync 官方 API 文档 编写,围绕仓颉(Cangjie)标准库 std.sync 包中的 AtomicUInt16 类展开,系统讲解其构造函数、全部成员函数的原型与语义、默认内存排序机制、已废弃 API 的迁移建议,并给出可直接运行的多线程计数实战示例,帮助开发者在并发场景下安全、高效地操作 UInt16 类型共享变量。

一、为什么需要 AtomicUInt16

在多核处理器日益普及的今天,并发编程已成为提升程序性能的关键手段。仓颉语言采用 M:N 线程模型,提供用户态的轻量级仓颉线程,开发者通过 spawn 关键字即可并发执行代码块,具体说明见 std.sync 包总览。

当多个线程同时读写同一个变量时,如果只是简单的 value++ 或 value = value + 1,会因"读—改—写"三步操作不具备原子性而产生数据竞争:两个线程可能同时读到旧值,各自加一后再写回,导致计数丢失。AtomicUInt16 正是为了解决这类问题而设计——它把 UInt16 类型的值封装起来,提供一套不可中断、线程安全的原子读写与运算接口,让并发计数、标志位维护、状态切换等操作无需加锁即可安全完成。

在 std.sync 原子操作类列表 中,AtomicUInt16 与 AtomicBool、AtomicInt8/16/32/64、AtomicUInt8/32/64、AtomicReference<T> 等共同组成了覆盖 Bool、整数与引用类型的完整原子操作家族。

二、类声明与构造函数

2.1 类声明

AtomicUInt16 封装了无符号 16 位整数类型 UInt16(取值范围 0 ~ 65535,相关类型扩展见 UInt16 类型说明),其完整定义如下(出自 sync_package_classes.md 的 AtomicUInt16 章节):

public class AtomicUInt16 {
    public init(val: UInt16)
}

从源码结构看,AtomicUInt16 是标准库 std.sync 包直接提供的公开类,不需要额外继承或实现接口即可使用。

2.2 构造函数 init(UInt16)

public init(val: UInt16)
  • 功能:构造一个封装 UInt16 数据类型的原子类型 AtomicUInt16 实例,其内部数据的初始值即入参 val 的值。
  • 参数:val: UInt16 —— 原子类型的初始值。

使用示例:

import std.sync.*

let counter = AtomicUInt16(0)      // 初始值为 0
let status  = AtomicUInt16(65535)  // 初始值为 UInt16 最大值

三、成员函数全解析

AtomicUInt16 提供三类原子操作:读写操作(load/store)、交换操作(swap/compareAndSwap)与算术/位运算操作(fetchAdd/fetchSub/fetchAnd/fetchOr/fetchXor)。所有成员函数均有"默认内存排序"版本,以及一个已标记 deprecated 的 MemoryOrder 参数版本(见下节说明)。

3.1 读写操作:load 与 store

load():读取原子值

public func load(): UInt16

采用默认内存排序方式读取原子类型的当前值,返回值为 UInt16。这是最常用的读取接口,等效于 Java 中 AtomicInteger.get()。

store(val):写入原子值

public func store(val: UInt16): Unit

采用默认内存排序方式,将参数 val 指定的值写入原子类型,返回 Unit。

注意:store 与 load 组合可以安全地实现"发布—订阅"模式:一个线程写入,另一个线程读取,读取方必然能看到写入方在 store 之前完成的所有操作(这是默认顺序一致语义的保证)。

3.2 交换操作:swap 与 compareAndSwap

swap(val):无条件的原子交换

public func swap(val: UInt16): UInt16

将参数 val 指定的值写入原子类型,并返回写入前的值。无论当前值是多少都会写入,因此它是"无条件交换"。

compareAndSwap(old, new):条件交换(CAS)

public func compareAndSwap(old: UInt16, new: UInt16): Bool

CAS(Compare and Swap)是并发编程中最核心的原子原语:

  1. 比较当前原子类型的值与参数 old 是否相等;
  2. 若相等,则写入参数 new 指定的值,返回 true;
  3. 若不相等,则不写入任何值,返回 false。

整个"比较—交换"过程不可分割,这正是实现无锁数据结构(如自旋锁、无锁栈、无锁队列)的基础。例如,可以用它实现"仅在值为期望值时更新"的乐观并发控制:

let counter = AtomicUInt16(10)
let ok = counter.compareAndSwap(10, 11)  // ok == true,当前值变为 11
let fail = counter.compareAndSwap(10, 20) // fail == false,当前值仍为 11

3.3 算术与位运算:fetch 系列

fetch 系列操作遵循同一语义:执行运算、将结果写回原子类型、返回运算前的旧值。这一点与 swap 的"返回写入前值"保持一致,便于开发者基于旧值做后续判断。

fetchAdd(val):原子加

public func fetchAdd(val: UInt16): UInt16

将当前值加上 val,结果写回,返回加操作前的值。多线程计数器的核心接口。

fetchSub(val):原子减

public func fetchSub(val: UInt16): UInt16

以原子类型的当前值为被减数、val 为减数做减法,结果写回,返回减操作前的值。注意 UInt16 为无符号类型,应避免结果下溢为负值。

fetchAnd(val):原子按位与

public func fetchAnd(val: UInt16): UInt16

将当前值与 val 做按位与(AND)运算,结果写回,返回运算前的值。常用于清除标志位。

fetchOr(val):原子按位或

public func fetchOr(val: UInt16): UInt16

将当前值与 val 做按位或(OR)运算,结果写回,返回运算前的值。常用于置位标志。

fetchXor(val):原子按位异或

public func fetchXor(val: UInt16): UInt16

将当前值与 val 做按位异或(XOR)运算,结果写回,返回运算前的值。常用于标志位翻转(toggle)。

提示:利用 fetchAnd/fetchOr/fetchXor,可以用一个 AtomicUInt16 的 16 个 bit 位分别承载 16 个布尔标志,多线程各自原子地置位/清除/翻转自己的标志位而互不干扰。

3.4 成员函数速查表

下表汇总 AtomicUInt16 的全部成员函数(默认内存排序版本):

函数 原型 语义要点
init (val: UInt16) 构造实例,初始值为 val
load (): UInt16 读取当前值
store (val: UInt16): Unit 写入新值
swap (val: UInt16): UInt16 无条件写入,返回旧值
compareAndSwap (old: UInt16, new: UInt16): Bool 值等于 old 时写入 new,返回是否成功
fetchAdd (val: UInt16): UInt16 原子加,返回旧值
fetchSub (val: UInt16): UInt16 原子减,返回旧值
fetchAnd (val: UInt16): UInt16 原子按位与,返回旧值
fetchOr (val: UInt16): UInt16 原子按位或,返回旧值
fetchXor (val: UInt16): UInt16 原子按位异或,返回旧值

四、内存排序与 deprecated 重载

4.1 为什么需要内存排序

出于性能优化,编译器或 CPU 可能对指令进行重排,破坏多线程下的可见性顺序。内存顺序(Memory Order)用于显式声明读写操作的排序策略。MemoryOrder 枚举 目前仅包含一个取值:

  • SeqCst(Sequentially Consistent,顺序一致):禁止指令重排,确保该原子操作之前的所有原子操作都先于该操作之后的原子操作完成。这是最严格、最直观的排序策略。

AtomicUInt16 的"默认内存排序"实际上就是顺序一致,对应的常量为 DefaultMemoryOrder:

public let DefaultMemoryOrder: MemoryOrder = MemoryOrder.SeqCst

4.2 deprecated 重载与迁移建议

AtomicUInt16 的每个成员函数还提供了一组带 memoryOrder!: MemoryOrder 参数的重载(compareAndSwap 则接受 successOrder! 与 failureOrder! 两个参数),但全部标记为 deprecated,未来版本即将废弃。以 compareAndSwap 为例:

public func compareAndSwap(
    old: UInt16,
    new: UInt16,
    successOrder!: MemoryOrder,
    failureOrder!: MemoryOrder
): Bool
  • successOrder!:CAS 成功时,执行"读 > 修改 > 写"操作需要的内存排序方式;
  • failureOrder!:CAS 失败时,仅执行"读"操作需要的内存排序方式。

由于当前 MemoryOrder 只有 SeqCst 一个取值,显式传入与使用默认值在语义上等价,因此官方建议一律使用无参数版本。迁移对照表如下:

废弃版本 推荐替代
compareAndSwap(old, new, successOrder!, failureOrder!) compareAndSwap(old, new)
fetchAdd(val, memoryOrder!) fetchAdd(val)
fetchSub(val, memoryOrder!) fetchSub(val)
fetchAnd(val, memoryOrder!) fetchAnd(val)
fetchOr(val, memoryOrder!) fetchOr(val)
fetchXor(val, memoryOrder!) fetchXor(val)
load(memoryOrder!) load()
store(val, memoryOrder!) store(val)
swap(val, memoryOrder!) swap(val)

五、实战示例:多线程原子计数

下面是一个完整可运行的示例,展示 AtomicUInt16 在多线程场景下的典型用法——但要注意:UInt16 取值范围有限(0~65535),当并发线程数较多、累加次数较大时可能溢出,因此该示例刻意控制累加总量。对于大范围计数,请选择 AtomicInt64 或 AtomicUInt64。

import std.sync.*
import std.time.*
import std.collection.*

let counter = AtomicUInt16(0)

main(): Int64 {
    let list = ArrayList<Future<Int64>>()

    /* 创建 10 个线程,每个线程执行 100 次原子加 */
    for (_ in 0..10) {
        let fut = spawn {
            for (_ in 0..100) {
                counter.fetchAdd(1)   // 原子自增
            }
        }
        list.add(fut)
    }

    /* 等待所有线程完成 */
    for (f in list) {
        f.get()
    }

    println("counter = ${counter.load()}")
    return 0
}

运行结果:

counter = 1000

如果去掉 fetchAdd 的原子性(例如改用普通 UInt16 变量的非原子累加),多线程竞争下结果往往小于 1000,这正是原子操作的价值所在。类似的"多线程原子计数"模式在 sync 包官方示例 中也有验证(示例使用 AtomicInt64 创建 1000 个线程并得到 count = 1000 的稳定结果)。

5.1 用 CAS 实现仅更新一次的标志

借助 compareAndSwap 的"比较—交换"语义,可以优雅地实现"只允许一个线程成功执行"的互斥效果:

import std.sync.*

let flag = AtomicUInt16(0)

main(): Int64 {
    let list = ArrayList<Future<Int64>>()

    for (_ in 0..100) {
        let fut = spawn {
            // 仅当当前值为 0 时写入 1,多个线程中只有一个能成功
            if (flag.compareAndSwap(0, 1)) {
                println("only one thread enters here")
            }
        }
        list.add(fut)
    }

    for (f in list) {
        f.get()
    }
    return 0
}

该模式是自旋锁、任务去重、懒初始化等无锁算法的通用构建块。

5.2 位标志操作示例

import std.sync.*

let flags = AtomicUInt16(0b0000_0000_0000_0000)

main(): Int64 {
    // 多线程各自置位自己的标志位
    flags.fetchOr(0b0000_0000_0000_0001)   // 置位 bit0
    flags.fetchOr(0b0000_0000_1000_0000)   // 置位 bit7
    flags.fetchAnd(0b1111_1111_1111_1110)  // 清除 bit0
    flags.fetchXor(0b0000_0000_1000_0000)  // 翻转 bit7

    println("flags = ${flags.load()}")
    return 0
}

六、使用注意与选型建议

  1. 注意返回值语义:fetch* 与 swap 返回的是操作前的旧值,而非操作后的新值。需要新值时,请用 load() 再读取,或根据旧值自行推导。
  2. 注意溢出与下溢:UInt16 的取值范围为 0 ~ 65535。fetchAdd 可能上溢、fetchSub 可能下溢,请结合业务量级选择合适的原子类型(原子类型完整列表)。
  3. 优先使用无参数版本:所有带 MemoryOrder 参数的重载均已标记 deprecated,新代码应直接使用默认内存排序版本,避免未来升级时的大规模迁移。
  4. 原子性 ≠ 复合操作原子性:compareAndSwap 单个调用是原子的,但"读—判断—CAS"组成的复合逻辑(如自旋循环)需要开发者自己保证正确性,典型的自旋写法为:读取旧值 → 计算新值 → CAS,若失败则重试。
  5. 与锁的关系:原子操作适合轻量级共享状态(计数器、标志位、指针交换);当临界区逻辑复杂、需要保护多变量一致性时,应改用 Mutex 配合 synchronized 关键字,二者互补而非互斥。

七、延伸阅读

登录后查看全文
DocAgent