无符号整数;若操作将使数值 变为负数,则阻塞内核线程。
此接口支持静态初始化,不需要反初始化。
字段
std.Io.Semaphore.Io
别名
别名目标 std.Io
std.Io.Semaphore.post
函数
使额外一个 permit 可用。
pub fn post(s: *Semaphore, io: Io) void
参数
std.Io.Semaphore.Semaphore
别名
别名目标 std.Io.Semaphore
std.Io.Semaphore.std
别名
别名目标 std
std.Io.Semaphore.testing
别名
别名目标 std.testing
std.Io.Semaphore.wait
函数
pub fn wait(s: *Semaphore, io: Io) Io.Cancelable!void
参数
错误
- 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
函数
pub fn waitTimeout(s: *Semaphore, io: Io, timeout: Io.Timeout) WaitTimeoutError!void
参数
错误
- 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
错误集合
错误
- Canceled Cancelable
调用方请求停止异步操作。
- Timeout Error
std.Io.Semaphore.waitUncancelable
函数
pub fn waitUncancelable(s: *Semaphore, io: Io) void
参数
用法示例
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
函数
fn worker(ctx: *@This()) !void
参数
ctx: *@This()
std.Io.Semaphore.worker
函数
fn worker(ctx: *@This()) !void
参数
ctx: *@This()
std.Io.Semaphore.worker
函数
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);
}