跳转到内容

std.Io.Semaphore

标准库Zig 0.17.1官方原文
源码std/Io/Semaphore.zig

第 1 行

无符号整数;若操作将使数值 变为负数,则阻塞内核线程。

此接口支持静态初始化,不需要反初始化。

字段

mutex: Io.Mutex = .init
cond: Io.Condition = .init
permits: usize = 0

此字段可以安全地初始化为任意值。

std.Io.Semaphore.Io

别名

第 8 行

别名目标 std.Io

std.Io.Semaphore.post

函数

第 61 行

使额外一个 permit 可用。

pub fn post(s: *Semaphore, io: Io) void

参数

s: *Semaphore
io: Io

std.Io.Semaphore.Semaphore

别名

第 5 行

别名目标 std.Io.Semaphore

std.Io.Semaphore.std

别名

第 7 行

别名目标 std

std.Io.Semaphore.testing

别名

第 9 行

别名目标 std.testing

std.Io.Semaphore.wait

函数

第 22 行

阻塞直到 permit 可用,并消耗一个许可。 取消时解除阻塞,但不消耗 permit。

另见:

pub fn wait(s: *Semaphore, io: Io) Io.Cancelable!void

参数

s: *Semaphore
io: Io

错误

Canceled

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

用法示例

test wait {
    const io = testing.io;

    const Context = struct {
        sem: Semaphore = .{ .permits = 1 },
        n: u32 = 0,

        fn worker(ctx: *@This()) !void {
            try ctx.sem.wait(io);
            ctx.n += 1;
            ctx.sem.post(io);
        }
    };

    var ctx: Context = .{};

    var group: Io.Group = .init;
    defer group.cancel(io);

    const num_workers = 3;
    for (0..num_workers) |_| group.async(io, Context.worker, .{&ctx});

    try group.await(io);
    try testing.expectEqual(num_workers, ctx.n);
}

std.Io.Semaphore.waitTimeout

函数

第 38 行

阻塞直到 permit 可用,并消费一个。 若被取消,或所给超时在 permit 可用前 到期,则解除阻塞,但不消费 permit。

另请参见:

pub fn waitTimeout(s: *Semaphore, io: Io, timeout: Io.Timeout) WaitTimeoutError!void

参数

s: *Semaphore
io: Io
timeout: Io.Timeout

错误

Canceled Cancelable

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

Timeout Error

用法示例

test waitTimeout {
    const io = testing.io;

    const Context = struct {
        ready: Io.Event = .unset,
        sem: Semaphore = .{ .permits = 0 },
        value: u32 = 0,

        fn worker(ctx: *@This()) !void {
            defer ctx.ready.set(io);

            try testing.expectError(error.Timeout, ctx.sem.waitTimeout(io, .{ .duration = .{
                .raw = .fromMilliseconds(1),
                .clock = .awake,
            } }));
            try testing.expectEqual(0, ctx.value);

            ctx.ready.set(io);

            while (ctx.value == 0) try ctx.sem.wait(io);
            try testing.expectEqual(1, ctx.value);
        }
    };

    var ctx: Context = .{};

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

    try ctx.ready.wait(io);

    ctx.value = 1;
    ctx.sem.post(io);

    try future.await(io);
}

std.Io.Semaphore.WaitTimeoutError

错误集合

第 29 行

错误

Canceled Cancelable

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

Timeout Error

std.Io.Semaphore.waitUncancelable

函数

第 52 行

阻塞直到有可用的 permit,然后消耗一个。

另见:

pub fn waitUncancelable(s: *Semaphore, io: Io) void

参数

s: *Semaphore
io: Io

用法示例

test waitUncancelable {
    const io = testing.io;

    const Context = struct {
        sem: Semaphore = .{ .permits = 1 },
        n: u32 = 0,

        fn worker(ctx: *@This()) !void {
            ctx.sem.waitUncancelable(io);
            ctx.n += 1;
            ctx.sem.post(io);
        }
    };

    var ctx: Context = .{};

    var group: Io.Group = .init;
    defer group.cancel(io);

    const num_workers = 3;
    for (0..num_workers) |_| group.async(io, Context.worker, .{&ctx});

    try group.await(io);
    try testing.expectEqual(num_workers, ctx.n);
}

std.Io.Semaphore.worker

函数

第 76 行

fn worker(ctx: *@This()) !void

参数

ctx: *@This()

std.Io.Semaphore.worker

函数

第 103 行

fn worker(ctx: *@This()) !void

参数

ctx: *@This()

std.Io.Semaphore.worker

函数

第 141 行

fn worker(ctx: *@This()) !void

参数

ctx: *@This()
源码

std/Io/Semaphore.zig

//! 无符号整数;若操作将使数值
//! 变为负数,则阻塞内核线程。
//!
//! 此接口支持静态初始化,不需要反初始化。
const Semaphore = @This();

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

mutex: Io.Mutex = .init,
cond: Io.Condition = .init,
/// 此字段可以安全地初始化为任意值。
permits: usize = 0,

/// 阻塞直到 `permit` 可用,并消耗一个许可。
/// 取消时解除阻塞,但不消耗 `permit`。
///
/// 另见:
/// * `waitTimeout`
/// * `waitUncancelable`
pub fn wait(s: *Semaphore, io: Io) Io.Cancelable!void {
    s.waitTimeout(io, .none) catch |err| switch (err) {
        error.Timeout => unreachable,
        error.Canceled => |e| return e,
    };
}

pub const WaitTimeoutError = Io.Cancelable || Io.Timeout.Error;

/// 阻塞直到 `permit` 可用,并消费一个。
/// 若被取消,或所给超时在 `permit` 可用前
/// 到期,则解除阻塞,但不消费 `permit`。
///
/// 另请参见:
/// * `wait`
/// * `waitUncancelable`
pub fn waitTimeout(s: *Semaphore, io: Io, timeout: Io.Timeout) WaitTimeoutError!void {
    const deadline = timeout.toDeadline(io);
    try s.mutex.lock(io);
    defer s.mutex.unlock(io);
    while (s.permits == 0) try s.cond.waitTimeout(io, &s.mutex, deadline);
    s.permits -= 1;
    if (s.permits > 0) s.cond.signal(io);
}

/// 阻塞直到有可用的 `permit`,然后消耗一个。
///
/// 另见:
/// * `wait`
/// * `waitTimeout`
pub fn waitUncancelable(s: *Semaphore, io: Io) void {
    s.mutex.lockUncancelable(io);
    defer s.mutex.unlock(io);
    while (s.permits == 0) s.cond.waitUncancelable(io, &s.mutex);
    s.permits -= 1;
    if (s.permits > 0) s.cond.signal(io);
}

/// 使额外一个 `permit` 可用。
pub fn post(s: *Semaphore, io: Io) void {
    s.mutex.lockUncancelable(io);
    defer s.mutex.unlock(io);

    s.permits += 1;
    s.cond.signal(io);
}

test wait {
    const io = testing.io;

    const Context = struct {
        sem: Semaphore = .{ .permits = 1 },
        n: u32 = 0,

        fn worker(ctx: *@This()) !void {
            try ctx.sem.wait(io);
            ctx.n += 1;
            ctx.sem.post(io);
        }
    };

    var ctx: Context = .{};

    var group: Io.Group = .init;
    defer group.cancel(io);

    const num_workers = 3;
    for (0..num_workers) |_| group.async(io, Context.worker, .{&ctx});

    try group.await(io);
    try testing.expectEqual(num_workers, ctx.n);
}

test waitTimeout {
    const io = testing.io;

    const Context = struct {
        ready: Io.Event = .unset,
        sem: Semaphore = .{ .permits = 0 },
        value: u32 = 0,

        fn worker(ctx: *@This()) !void {
            defer ctx.ready.set(io);

            try testing.expectError(error.Timeout, ctx.sem.waitTimeout(io, .{ .duration = .{
                .raw = .fromMilliseconds(1),
                .clock = .awake,
            } }));
            try testing.expectEqual(0, ctx.value);

            ctx.ready.set(io);

            while (ctx.value == 0) try ctx.sem.wait(io);
            try testing.expectEqual(1, ctx.value);
        }
    };

    var ctx: Context = .{};

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

    try ctx.ready.wait(io);

    ctx.value = 1;
    ctx.sem.post(io);

    try future.await(io);
}

test waitUncancelable {
    const io = testing.io;

    const Context = struct {
        sem: Semaphore = .{ .permits = 1 },
        n: u32 = 0,

        fn worker(ctx: *@This()) !void {
            ctx.sem.waitUncancelable(io);
            ctx.n += 1;
            ctx.sem.post(io);
        }
    };

    var ctx: Context = .{};

    var group: Io.Group = .init;
    defer group.cancel(io);

    const num_workers = 3;
    for (0..num_workers) |_| group.async(io, Context.worker, .{&ctx});

    try group.await(io);
    try testing.expectEqual(num_workers, ctx.n);
}