跳转到内容
标准库Zig 0.17.0官方原文
源码std/Io/RwLock.zig

第 1 行

支持一个写入者或多个读取者的锁。

字段

state: usize
mutex: Io.Mutex
semaphore: Io.Semaphore

std.Io.RwLock.assert

别名

第 8 行

别名目标 std.debug.assert

std.Io.RwLock.builtin

常量

第 4 行

std.Io.RwLock.Count

常量

第 26 行

std.Io.RwLock.init

常量

第 15 行

RwLock

std.Io.RwLock.Io

别名

第 7 行

别名目标 std.Io

std.Io.RwLock.is_writing

常量

第 21 行

usize

std.Io.RwLock.lock

函数

第 60 行

pub fn lock(rl: *RwLock, io: Io) Io.Cancelable!void

参数

rl: *RwLock
io: Io

错误

Canceled

调用方请求停止异步操作。

std.Io.RwLock.lockShared

函数

第 129 行

pub fn lockShared(rl: *RwLock, io: Io) Io.Cancelable!void

参数

rl: *RwLock
io: Io

错误

Canceled

调用方请求停止异步操作。

std.Io.RwLock.lockSharedUncancelable

函数

第 111 行

pub fn lockSharedUncancelable(rl: *RwLock, io: Io) void

参数

rl: *RwLock
io: Io

std.Io.RwLock.lockUncancelable

函数

第 51 行

pub fn lockUncancelable(rl: *RwLock, io: Io) void

参数

rl: *RwLock
io: Io

std.Io.RwLock.lockUnlock

函数

第 358 行

fn lockUnlock(rl: *Io.RwLock, io: Io) Io.Cancelable!void

参数

rl: *Io.RwLock
io: Io

错误

Canceled

调用方请求停止异步操作。

std.Io.RwLock.mutexLockCancel

函数

第 398 行

fn mutexLockCancel(rl: *Io.RwLock, io: Io) !void

参数

rl: *Io.RwLock
io: Io

std.Io.RwLock.reader

常量

第 23 行

usize

std.Io.RwLock.reader

函数

第 228 行

fn reader(run: *Runner, thread_idx: usize) !void

参数

run: *Runner
thread_idx: usize

std.Io.RwLock.reader

函数

第 328 行

fn reader(ctx: *@This(), io: Io) !void

参数

ctx: *@This()
io: Io

std.Io.RwLock.reader_mask

常量

第 25 行

usize

std.Io.RwLock.Runner

别名

第 217 行

别名目标 std.Io.RwLock

std.Io.RwLock.RwLock

别名

第 2 行

别名目标 std.Io.RwLock

std.Io.RwLock.semaphoreLockCancel

函数

第 394 行

fn semaphoreLockCancel(rl: *Io.RwLock, io: Io) !void

参数

rl: *Io.RwLock
io: Io

std.Io.RwLock.std

别名

第 6 行

别名目标 std

std.Io.RwLock.testing

别名

第 9 行

别名目标 std.testing

std.Io.RwLock.tryLock

函数

第 28 行

pub fn tryLock(rl: *RwLock, io: Io) bool

参数

rl: *RwLock
io: Io

std.Io.RwLock.tryLockShared

函数

第 89 行

pub fn tryLockShared(rl: *RwLock, io: Io) bool

参数

rl: *RwLock
io: Io

std.Io.RwLock.unlock

函数

第 84 行

pub fn unlock(rl: *RwLock, io: Io) void

参数

rl: *RwLock
io: Io

std.Io.RwLock.unlockShared

函数

第 147 行

pub fn unlockShared(rl: *RwLock, io: Io) void

参数

rl: *RwLock
io: Io

std.Io.RwLock.writer

常量

第 22 行

usize

std.Io.RwLock.writer

函数

第 250 行

fn writer(run: *Runner, thread_idx: usize) !void

参数

run: *Runner
thread_idx: usize

std.Io.RwLock.writer_mask

常量

第 24 行

usize
源码

std/Io/RwLock.zig

//! 支持一个写入者或多个读取者的锁。
const RwLock = @This();

const builtin = @import("builtin");

const std = @import("../std.zig");
const Io = std.Io;
const assert = std.debug.assert;
const testing = std.testing;

state: usize,
mutex: Io.Mutex,
semaphore: Io.Semaphore,

pub const init: RwLock = .{
    .state = 0,
    .mutex = .init,
    .semaphore = .{},
};

const is_writing: usize = 1;
const writer: usize = 1 << 1;
const reader: usize = 1 << (1 + @bitSizeOf(Count));
const writer_mask: usize = std.math.maxInt(Count) << @ctz(writer);
const reader_mask: usize = std.math.maxInt(Count) << @ctz(reader);
const Count = @Int(.unsigned, @divFloor(@bitSizeOf(usize) - 1, 2));

pub fn tryLock(rl: *RwLock, io: Io) bool {
    if (rl.mutex.tryLock()) {
        // 与 `lock` 不同,此操作从不在 `writer_mask` 中登记,故持有互斥锁
        // 不会阻止读者采用快速路径;CAS 会捕获在加载 `state`
        // 之后通过竞态进入的读者。
        const state = @atomicLoad(usize, &rl.state, .seq_cst);
        if (state & reader_mask == 0) {
            _ = @cmpxchgStrong(
                usize,
                &rl.state,
                state,
                state | is_writing,
                .seq_cst,
                .seq_cst,
            ) orelse return true;
        }

        rl.mutex.unlock(io);
    }

    return false;
}

pub fn lockUncancelable(rl: *RwLock, io: Io) void {
    _ = @atomicRmw(usize, &rl.state, .Add, writer, .seq_cst);
    rl.mutex.lockUncancelable(io);

    const state = @atomicRmw(usize, &rl.state, .Add, is_writing -% writer, .seq_cst);
    if (state & reader_mask != 0)
        rl.semaphore.waitUncancelable(io);
}

pub fn lock(rl: *RwLock, io: Io) Io.Cancelable!void {
    _ = @atomicRmw(usize, &rl.state, .Add, writer, .seq_cst);
    rl.mutex.lock(io) catch |err| switch (err) {
        error.Canceled => {
            _ = @atomicRmw(usize, &rl.state, .Sub, writer, .seq_cst);
            return error.Canceled;
        },
    };

    const state = @atomicRmw(usize, &rl.state, .Add, is_writing -% writer, .seq_cst);
    if (state & reader_mask != 0)
        rl.semaphore.wait(io) catch |err| switch (err) {
            error.Canceled => {
                // 仍持有互斥锁时清除 `is_writing`,意味着最后一个读者
                // 要么看到它已设置,并发布一个只有当前线程能消费的许可;要么没看到,
                // 因此永远不会发布许可。过期许可会让下一个写者越过读者直接进入。
                const prev_state = @atomicRmw(usize, &rl.state, .And, ~is_writing, .seq_cst);
                if (prev_state & reader_mask == 0) rl.semaphore.waitUncancelable(io);
                rl.mutex.unlock(io);
                return error.Canceled;
            },
        };
}

pub fn unlock(rl: *RwLock, io: Io) void {
    _ = @atomicRmw(usize, &rl.state, .And, ~is_writing, .seq_cst);
    rl.mutex.unlock(io);
}

pub fn tryLockShared(rl: *RwLock, io: Io) bool {
    const state = @atomicLoad(usize, &rl.state, .seq_cst);
    if (state & (is_writing | writer_mask) == 0) {
        _ = @cmpxchgStrong(
            usize,
            &rl.state,
            state,
            state + reader,
            .seq_cst,
            .seq_cst,
        ) orelse return true;
    }

    if (rl.mutex.tryLock()) {
        _ = @atomicRmw(usize, &rl.state, .Add, reader, .seq_cst);
        rl.mutex.unlock(io);
        return true;
    }

    return false;
}

pub fn lockSharedUncancelable(rl: *RwLock, io: Io) void {
    var state = @atomicLoad(usize, &rl.state, .seq_cst);
    while (state & (is_writing | writer_mask) == 0) {
        state = @cmpxchgWeak(
            usize,
            &rl.state,
            state,
            state + reader,
            .seq_cst,
            .seq_cst,
        ) orelse return;
    }

    rl.mutex.lockUncancelable(io);
    _ = @atomicRmw(usize, &rl.state, .Add, reader, .seq_cst);
    rl.mutex.unlock(io);
}

pub fn lockShared(rl: *RwLock, io: Io) Io.Cancelable!void {
    var state = @atomicLoad(usize, &rl.state, .seq_cst);
    while (state & (is_writing | writer_mask) == 0) {
        state = @cmpxchgWeak(
            usize,
            &rl.state,
            state,
            state + reader,
            .seq_cst,
            .seq_cst,
        ) orelse return;
    }

    try rl.mutex.lock(io);
    _ = @atomicRmw(usize, &rl.state, .Add, reader, .seq_cst);
    rl.mutex.unlock(io);
}

pub fn unlockShared(rl: *RwLock, io: Io) void {
    const state = @atomicRmw(usize, &rl.state, .Sub, reader, .seq_cst);

    if ((state & reader_mask == reader) and (state & is_writing != 0))
        rl.semaphore.post(io);
}

test "internal state" {
    const io = testing.io;

    var rl: Io.RwLock = .init;

    // 在修复议题 #13163 之前,以下测试会失败,
    // 原因是 lock 方法减去了 WRITER 标志。

    rl.lockUncancelable(io);
    rl.unlock(io);
    try testing.expectEqual(rl, Io.RwLock.init);

    try rl.lock(io);
    rl.unlock(io);
    try testing.expectEqual(rl, Io.RwLock.init);
}

test "smoke test" {
    const io = testing.io;

    var rl: Io.RwLock = .init;

    rl.lockUncancelable(io);
    try testing.expect(!rl.tryLock(io));
    try testing.expect(!rl.tryLockShared(io));
    rl.unlock(io);

    try rl.lock(io);
    try testing.expect(!rl.tryLock(io));
    try testing.expect(!rl.tryLockShared(io));
    rl.unlock(io);

    try testing.expect(rl.tryLock(io));
    try testing.expect(!rl.tryLock(io));
    try testing.expect(!rl.tryLockShared(io));
    rl.unlock(io);

    rl.lockSharedUncancelable(io);
    try testing.expect(!rl.tryLock(io));
    try testing.expect(rl.tryLockShared(io));
    rl.unlockShared(io);
    rl.unlockShared(io);

    try testing.expect(rl.tryLockShared(io));
    try testing.expect(!rl.tryLock(io));
    try testing.expect(rl.tryLockShared(io));
    rl.unlockShared(io);
    rl.unlockShared(io);

    rl.lockUncancelable(io);
    rl.unlock(io);
}

test "concurrent access" {
    if (builtin.single_threaded) return;

    const io = testing.io;
    const num_writers: usize = 2;
    const num_readers: usize = 4;
    const num_writes: usize = 1000;
    const num_reads: usize = 2000;

    const Runner = struct {
        const Runner = @This();

        io: Io,

        rl: Io.RwLock,
        writes: usize,
        reads: std.atomic.Value(usize),

        val_a: usize,
        val_b: usize,

        fn reader(run: *Runner, thread_idx: usize) !void {
            var prng = std.Random.DefaultPrng.init(thread_idx);
            const rnd = prng.random();
            while (true) {
                run.rl.lockSharedUncancelable(run.io);
                defer run.rl.unlockShared(run.io);

                try testing.expect(run.writes <= num_writes);
                if (run.reads.fetchAdd(1, .monotonic) >= num_reads) break;

                // 使用 `volatile` 访问,确保在 yield 的前后两侧都访问内存,
                // 从而最大化发生竞态条件的概率。
                const a_ptr: *const volatile usize = &run.val_a;
                const b_ptr: *const volatile usize = &run.val_b;

                const old_a = a_ptr.*;
                if (rnd.boolean()) try std.Thread.yield();
                const old_b = b_ptr.*;
                try testing.expect(old_a == old_b);
            }
        }

        fn writer(run: *Runner, thread_idx: usize) !void {
            var prng = std.Random.DefaultPrng.init(thread_idx);
            const rnd = prng.random();
            while (true) {
                run.rl.lockUncancelable(run.io);
                defer run.rl.unlock(run.io);

                try testing.expect(run.writes <= num_writes);
                if (run.writes == num_writes) break;

                // 使用 `volatile` 访问,确保在 yield 的前后两侧都访问内存,
                // 从而最大化发生竞态条件的概率。
                const a_ptr: *volatile usize = &run.val_a;
                const b_ptr: *volatile usize = &run.val_b;

                const new_val = rnd.int(usize);

                const old_a = a_ptr.*;
                a_ptr.* = new_val;
                if (rnd.boolean()) try std.Thread.yield();
                const old_b = b_ptr.*;
                b_ptr.* = new_val;
                try testing.expect(old_a == old_b);

                run.writes += 1;
            }
        }
    };

    var run: Runner = .{
        .io = io,
        .rl = .init,
        .writes = 0,
        .reads = .init(0),
        .val_a = 0,
        .val_b = 0,
    };
    var write_threads: [num_writers]std.Thread = undefined;
    var read_threads: [num_readers]std.Thread = undefined;

    for (&write_threads, 0..) |*t, i| t.* = try .spawn(.{}, Runner.writer, .{ &run, i });
    for (&read_threads, num_writers..) |*t, i| t.* = try .spawn(.{}, Runner.reader, .{ &run, i });

    for (write_threads) |t| t.join();
    for (read_threads) |t| t.join();

    try testing.expect(run.writes == num_writes);
    try testing.expect(run.reads.raw >= num_reads);
}

test "lock canceling" {
    const io = testing.io;

    var rl: Io.RwLock = .init;

    rl.lockSharedUncancelable(io);
    var sfuture = io.concurrent(semaphoreLockCancel, .{ &rl, io }) catch |err| switch (err) {
        error.ConcurrencyUnavailable => return error.SkipZigTest,
    };
    try std.testing.expectEqual(error.Canceled, sfuture.cancel(io));
    rl.unlockShared(io);
    try testing.expectEqual(rl, Io.RwLock.init);

    rl.lockUncancelable(io);
    var mfuture = io.concurrent(mutexLockCancel, .{ &rl, io }) catch |err| switch (err) {
        error.ConcurrencyUnavailable => return error.SkipZigTest,
    };
    try std.testing.expectEqual(error.Canceled, mfuture.cancel(io));
    rl.unlock(io);
    try testing.expectEqual(rl, Io.RwLock.init);
}

test "tryLock does not race with readers" {
    if (builtin.single_threaded) return error.SkipZigTest;

    const Context = struct {
        rl: Io.RwLock,

        fn reader(ctx: *@This(), io: Io) !void {
            while (true) {
                if (ctx.rl.tryLockShared(io)) ctx.rl.unlockShared(io);
                try io.checkCancel();
            }
        }
    };

    var ctx: Context = .{ .rl = .init };
    const io = testing.io;

    var future = io.concurrent(Context.reader, .{ &ctx, io }) catch |err| switch (err) {
        error.ConcurrencyUnavailable => return error.SkipZigTest,
    };
    defer future.cancel(io) catch {};

    for (0..1000) |_| {
        if (!ctx.rl.tryLock(io)) continue;
        defer ctx.rl.unlock(io);
        const state = @atomicLoad(usize, &ctx.rl.state, .seq_cst);
        try testing.expectEqual(0, state & reader_mask);
    }

    try testing.expectEqual(0, ctx.rl.semaphore.permits);
}

test "canceled writer does not leak a semaphore permit" {
    if (builtin.single_threaded) return error.SkipZigTest;

    const Writer = struct {
        fn lockUnlock(rl: *Io.RwLock, io: Io) Io.Cancelable!void {
            try rl.lock(io);
            rl.unlock(io);
        }
    };

    const io = testing.io;

    var rl: Io.RwLock = .init;

    for (0..1000) |_| {
        rl.lockSharedUncancelable(io);

        var wfuture = io.concurrent(Writer.lockUnlock, .{ &rl, io }) catch |err| switch (err) {
            error.ConcurrencyUnavailable => {
                rl.unlockShared(io);
                return error.SkipZigTest;
            },
        };
        var rfuture = io.concurrent(Io.RwLock.unlockShared, .{ &rl, io }) catch |err| switch (err) {
            error.ConcurrencyUnavailable => {
                rl.unlockShared(io);
                wfuture.await(io) catch {};
                return error.SkipZigTest;
            },
        };

        // 令最后一个读取者的 `post` 与写入者的取消发生竞争。
        wfuture.cancel(io) catch {};
        rfuture.await(io);

        try testing.expectEqual(0, rl.state);
        try testing.expectEqual(0, rl.semaphore.permits);
    }
}

fn semaphoreLockCancel(rl: *Io.RwLock, io: Io) !void {
    try rl.lock(io); // 测试信号量取消操作
}

fn mutexLockCancel(rl: *Io.RwLock, io: Io) !void {
    // 测试互斥锁取消
    try std.testing.expectEqual(error.Canceled, rl.lockShared(io));
    io.recancel();
    try std.testing.expectEqual(error.Canceled, rl.lock(io));
    return error.Canceled;
}