跳转到内容

std.Io.File.MultiReader

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

第 1 行

字段

gpa: Allocator
streams: *Streams
batch: Io.Batch

std.Io.File.MultiReader.Allocator

别名

第 6 行

别名目标 std.mem.Allocator

std.Io.File.MultiReader.assert

别名

第 7 行

别名目标 std.debug.assert

std.Io.File.MultiReader.Buffer

类型函数

第 43 行

pub fn Buffer(comptime n: usize) type

参数

n: usize

字段

len: u32
contexts: [n][@sizeOf(Context)]u8 align(@alignOf(Context))
storage: [n][@sizeOf(Io.Operation.Storage)]u8 align(@alignOf(Io.Operation.Storage))

std.Io.File.MultiReader.Buffer.toStreams

函数

第 49 行

pub fn toStreams(b: *@This()) *Streams

参数

b: *@This()

std.Io.File.MultiReader.checkAnyError

函数

第 119 行

检查所有流的错误;只要任意位置出现 error.Canceled,就优先返回该错误,并忽略 error.EndOfStream。

pub fn checkAnyError(mr: *const MultiReader) UnendingError!void

参数

mr: *const MultiReader

错误

AccessDenied UnendingError

在 WASI 中,当文件描述符不具有读取 所需的权限时发生此错误。

Canceled Cancelable

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

ConcurrencyUnavailable ConcurrentError

可能由资源耗尽等临时情况引起,也可能因为 Io 实现不支持并发。

ConnectionResetByPeer UnendingError
InputOutput UnendingError
IsDir UnendingError

尝试将目录文件描述符当作普通文件读取。

LockViolation UnendingError

由于锁定而无法读取文件。根据 Io 实现的不同,读取已锁定文件可能返回此错误,也可能忽略锁。

NotOpenForReading UnendingError

打开文件时未授予读取能力。

OutOfMemory Error
SocketUnconnected UnendingError
SystemResources UnendingError
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

WouldBlock UnendingError

已启用非阻塞模式,且从该文件描述符读取会阻塞。

std.Io.File.MultiReader.Context

容器

第 13 行

字段

mr: *MultiReader
fr: File.Reader
vec: [1][]u8
err: ?Error

std.Io.File.MultiReader.deinit

函数

第 99 行

pub fn deinit(mr: *MultiReader) void

参数

std.Io.File.MultiReader.discard

函数

第 158 行

fn discard(r: *Io.Reader, limit: Io.Limit) Io.Reader.Error!usize

参数

r: *Io.Reader
limit: Io.Limit

错误

EndOfStream
ReadFailed

详细诊断参见 Reader 的实现。

std.Io.File.MultiReader.Error

错误集合

第 20 行

错误

AccessDenied UnendingError

在 WASI 中,当文件描述符不具有读取 所需的权限时发生此错误。

Canceled Cancelable

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

ConcurrencyUnavailable ConcurrentError

可能由资源耗尽等临时情况引起,也可能因为 Io 实现不支持并发。

ConnectionResetByPeer UnendingError
EndOfStream
InputOutput UnendingError
IsDir UnendingError

尝试将目录文件描述符当作普通文件读取。

LockViolation UnendingError

由于锁定而无法读取文件。根据 Io 实现的不同,读取已锁定文件可能返回此错误,也可能忽略锁。

NotOpenForReading UnendingError

打开文件时未授予读取能力。

OutOfMemory Error
SocketUnconnected UnendingError
SystemResources UnendingError
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

WouldBlock UnendingError

已启用非阻塞模式,且从该文件描述符读取会阻塞。

std.Io.File.MultiReader.File

别名

第 5 行

别名目标 std.Io.File

std.Io.File.MultiReader.fileReader

函数

第 109 行

pub fn fileReader(mr: *MultiReader, index: usize) *File.Reader

参数

mr: *MultiReader
index: usize

std.Io.File.MultiReader.fill

函数

第 202 行

等待至少一个流收到更多数据。

pub fn fill(mr: *MultiReader, unused_capacity: usize, timeout: Io.Timeout) FillError!void

参数

mr: *MultiReader
unused_capacity: usize
timeout: Io.Timeout

错误

Canceled Cancelable

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

ConcurrencyUnavailable ConcurrentError

可能由资源耗尽等临时情况引起,也可能因为 Io 实现不支持并发。

EndOfStream

调用 fill 时,所有流均已失败或到达 末尾。

Timeout Error

std.Io.File.MultiReader.FillError

错误集合

第 195 行

错误

Canceled Cancelable

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

ConcurrencyUnavailable ConcurrentError

可能由资源耗尽等临时情况引起,也可能因为 Io 实现不支持并发。

EndOfStream

调用 fill 时,所有流均已失败或到达 末尾。

Timeout Error

std.Io.File.MultiReader.fillRemaining

函数

第 236 行

等待所有流失败或到达末尾。

pub fn fillRemaining(mr: *MultiReader, timeout: Io.Timeout) Io.Batch.AwaitConcurrentError!void

参数

mr: *MultiReader
timeout: Io.Timeout

错误

Canceled Cancelable

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

ConcurrencyUnavailable ConcurrentError

可能由资源耗尽等临时情况引起,也可能因为 Io 实现不支持并发。

Timeout Error

std.Io.File.MultiReader.fillUntimed

函数

第 180 行

fn fillUntimed(context: *Context, capacity: usize) Io.Reader.Error!void

参数

context: *Context
capacity: usize

错误

EndOfStream
ReadFailed

详细诊断参见 Reader 的实现。

std.Io.File.MultiReader.init

函数

第 57 行

用于获取 streams 参数的便捷 API,参见 Streams.Buffer。

pub fn init(mr: *MultiReader, gpa: Allocator, io: Io, streams: *Streams, files: []const File) void

参数

mr: *MultiReader
gpa: Allocator
io: Io
streams: *Streams
files: []const File

std.Io.File.MultiReader.Io

别名

第 4 行

别名目标 std.Io

std.Io.File.MultiReader.MultiReader

别名

第 1 行

别名目标 std.Io.File.MultiReader

std.Io.File.MultiReader.reader

函数

第 113 行

pub fn reader(mr: *MultiReader, index: usize) *Io.Reader

参数

mr: *MultiReader
index: usize

std.Io.File.MultiReader.readVec

函数

第 166 行

fn readVec(r: *Io.Reader, data: [][]u8) Io.Reader.Error!usize

参数

r: *Io.Reader
data: [][]u8

错误

EndOfStream
ReadFailed

详细诊断参见 Reader 的实现。

std.Io.File.MultiReader.rebase

函数

第 174 行

fn rebase(r: *Io.Reader, capacity: usize) Io.Reader.RebaseError!void

参数

r: *Io.Reader
capacity: usize

错误

EndOfStream Error
ReadFailed Error

详细诊断参见 Reader 的实现。

std.Io.File.MultiReader.rebaseGrowing

函数

第 243 行

fn rebaseGrowing(mr: *MultiReader, context: *Context, capacity: usize) Allocator.Error!void

参数

mr: *MultiReader
context: *Context
capacity: usize

错误

OutOfMemory

std.Io.File.MultiReader.std

别名

第 3 行

别名目标 std

std.Io.File.MultiReader.stream

函数

第 149 行

fn stream(r: *Io.Reader, w: *Io.Writer, limit: Io.Limit) Io.Reader.StreamError!usize

参数

r: *Io.Reader
w: *Io.Writer
limit: Io.Limit

错误

EndOfStream

Reader 指示流结束。此错误不会从 Writer 产生。

ReadFailed

详细诊断参见 Reader 的实现。

WriteFailed

详细诊断信息见 Writer 实现。

std.Io.File.MultiReader.Streams

容器

第 26 行

尾随数据:

  • contexts: [len]Context
  • storage: [len]Io.Operation.Storage

字段

len: u32

std.Io.File.MultiReader.Streams.contexts

函数

第 29 行

pub fn contexts(s: *Streams) []Context

参数

s: *Streams

std.Io.File.MultiReader.Streams.storage

函数

第 35 行

pub fn storage(s: *Streams) []Io.Operation.Storage

参数

s: *Streams

std.Io.File.MultiReader.toOwnedSlice

函数

第 132 行

pub fn toOwnedSlice(mr: *MultiReader, index: usize) Allocator.Error![]u8

参数

mr: *MultiReader
index: usize

错误

OutOfMemory

std.Io.File.MultiReader.UnendingError

错误集合

第 21 行

错误

AccessDenied UnendingError

在 WASI 中,当文件描述符不具有读取 所需的权限时发生此错误。

Canceled Cancelable

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

ConcurrencyUnavailable ConcurrentError

可能由资源耗尽等临时情况引起,也可能因为 Io 实现不支持并发。

ConnectionResetByPeer UnendingError
InputOutput UnendingError
IsDir UnendingError

尝试将目录文件描述符当作普通文件读取。

LockViolation UnendingError

由于锁定而无法读取文件。根据 Io 实现的不同,读取已锁定文件可能返回此错误,也可能忽略锁。

NotOpenForReading UnendingError

打开文件时未授予读取能力。

OutOfMemory Error
SocketUnconnected UnendingError
SystemResources UnendingError
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

WouldBlock UnendingError

已启用非阻塞模式,且从该文件描述符读取会阻塞。

源码

std/Io/File/MultiReader.zig

const MultiReader = @This();

const std = @import("../../std.zig");
const Io = std.Io;
const File = Io.File;
const Allocator = std.mem.Allocator;
const assert = std.debug.assert;

gpa: Allocator,
streams: *Streams,
batch: Io.Batch,

pub const Context = struct {
    mr: *MultiReader,
    fr: File.Reader,
    vec: [1][]u8,
    err: ?Error,
};

pub const Error = UnendingError || error{EndOfStream};
pub const UnendingError = Allocator.Error || File.Reader.Error || Io.ConcurrentError;

/// 尾随数据:
/// * `contexts: [len]Context`
/// * `storage: [len]Io.Operation.Storage`
pub const Streams = extern struct {
    len: u32,

    pub fn contexts(s: *Streams) []Context {
        const base: usize = @intFromPtr(s);
        const ptr: [*]Context = @ptrFromInt(std.mem.alignForward(usize, base + @sizeOf(Streams), @alignOf(Context)));
        return ptr[0..s.len];
    }

    pub fn storage(s: *Streams) []Io.Operation.Storage {
        const prev = contexts(s);
        const end = prev.ptr + prev.len;
        const ptr: [*]Io.Operation.Storage = @ptrFromInt(std.mem.alignForward(usize, @intFromPtr(end), @alignOf(Io.Operation.Storage)));
        return ptr[0..s.len];
    }
};

pub fn Buffer(comptime n: usize) type {
    return extern struct {
        len: u32,
        contexts: [n][@sizeOf(Context)]u8 align(@alignOf(Context)),
        storage: [n][@sizeOf(Io.Operation.Storage)]u8 align(@alignOf(Io.Operation.Storage)),

        pub fn toStreams(b: *@This()) *Streams {
            b.len = n;
            return @ptrCast(b);
        }
    };
}

/// 用于获取 `streams` 参数的便捷 API,参见 `Streams.Buffer`。
pub fn init(mr: *MultiReader, gpa: Allocator, io: Io, streams: *Streams, files: []const File) void {
    const contexts = streams.contexts();
    for (contexts, files) |*context, file| context.* = .{
        .mr = mr,
        .fr = .{
            .io = io,
            .file = file,
            .mode = .streaming,
            .interface = .{
                .vtable = &.{
                    .stream = stream,
                    .discard = discard,
                    .readVec = readVec,
                    .rebase = rebase,
                },
                .buffer = &.{},
                .seek = 0,
                .end = 0,
            },
        },
        .vec = .{&.{}},
        .err = null,
    };
    mr.* = .{
        .gpa = gpa,
        .streams = streams,
        .batch = .init(streams.storage()),
    };
    for (contexts, 0..) |*context, i| {
        const r = &context.fr.interface;
        rebaseGrowing(mr, context, 1) catch |err| {
            context.err = err;
            continue;
        };
        context.vec[0] = r.buffer;
        mr.batch.addAt(@intCast(i), .{ .file_read_streaming = .{
            .file = context.fr.file,
            .data = &context.vec,
        } });
    }
}

pub fn deinit(mr: *MultiReader) void {
    const gpa = mr.gpa;
    const contexts = mr.streams.contexts();
    const io = contexts[0].fr.io;
    mr.batch.cancel(io);
    for (contexts) |*context| {
        gpa.free(context.fr.interface.buffer);
    }
}

pub fn fileReader(mr: *MultiReader, index: usize) *File.Reader {
    return &mr.streams.contexts()[index].fr;
}

pub fn reader(mr: *MultiReader, index: usize) *Io.Reader {
    return &mr.streams.contexts()[index].fr.interface;
}

/// 检查所有流的错误;只要任意位置出现 `error.Canceled`,就优先返回该错误,并忽略 `error.EndOfStream`。
///
pub fn checkAnyError(mr: *const MultiReader) UnendingError!void {
    const contexts = mr.streams.contexts();
    var other: UnendingError!void = {};
    for (contexts) |*context| {
        if (context.err) |err| switch (err) {
            error.Canceled => |e| return e,
            error.EndOfStream => continue,
            else => |e| other = e,
        };
    }
    return other;
}

pub fn toOwnedSlice(mr: *MultiReader, index: usize) Allocator.Error![]u8 {
    const gpa = mr.gpa;
    const r: *Io.Reader = reader(mr, index);
    if (r.seek == 0) {
        const new = try gpa.realloc(r.buffer, r.end);
        r.buffer = &.{};
        r.end = 0;
        return new;
    }
    const new = try gpa.dupe(u8, r.buffered());
    gpa.free(r.buffer);
    r.buffer = &.{};
    r.seek = 0;
    r.end = 0;
    return new;
}

fn stream(r: *Io.Reader, w: *Io.Writer, limit: Io.Limit) Io.Reader.StreamError!usize {
    _ = limit;
    _ = w;
    const fr: *File.Reader = @alignCast(@fieldParentPtr("interface", r));
    const context: *Context = @fieldParentPtr("fr", fr);
    try fillUntimed(context, 1);
    return 0;
}

fn discard(r: *Io.Reader, limit: Io.Limit) Io.Reader.Error!usize {
    _ = limit;
    const fr: *File.Reader = @alignCast(@fieldParentPtr("interface", r));
    const context: *Context = @fieldParentPtr("fr", fr);
    try fillUntimed(context, 1);
    return 0;
}

fn readVec(r: *Io.Reader, data: [][]u8) Io.Reader.Error!usize {
    _ = data;
    const fr: *File.Reader = @alignCast(@fieldParentPtr("interface", r));
    const context: *Context = @fieldParentPtr("fr", fr);
    try fillUntimed(context, 1);
    return 0;
}

fn rebase(r: *Io.Reader, capacity: usize) Io.Reader.RebaseError!void {
    const fr: *File.Reader = @alignCast(@fieldParentPtr("interface", r));
    const context: *Context = @fieldParentPtr("fr", fr);
    try fillUntimed(context, capacity);
}

fn fillUntimed(context: *Context, capacity: usize) Io.Reader.Error!void {
    fill(context.mr, capacity, .none) catch |err| switch (err) {
        error.Timeout => unreachable,
        error.Canceled, error.ConcurrencyUnavailable => |e| {
            context.err = e;
            return error.ReadFailed;
        },
        error.EndOfStream => |e| return e,
    };
    if (context.err) |err| switch (err) {
        error.EndOfStream => |e| return e,
        else => return error.ReadFailed,
    };
}

pub const FillError = Io.Batch.AwaitConcurrentError || error{
    /// 调用 `fill` 时,所有流均已失败或到达
    /// 末尾。
    EndOfStream,
};

/// 等待至少一个流收到更多数据。
pub fn fill(mr: *MultiReader, unused_capacity: usize, timeout: Io.Timeout) FillError!void {
    const contexts = mr.streams.contexts();
    const io = contexts[0].fr.io;
    var any_completed = false;

    try mr.batch.awaitConcurrent(io, timeout);

    while (mr.batch.next()) |operation| {
        any_completed = true;
        const context = &contexts[operation.index];
        const n = operation.result.file_read_streaming catch |err| {
            context.err = err;
            continue;
        };
        const r = &context.fr.interface;
        r.end += n;
        if (r.buffer.len - r.end < unused_capacity) {
            rebaseGrowing(mr, context, r.bufferedLen() + unused_capacity) catch |err| {
                context.err = err;
                continue;
            };
            assert(r.seek == 0);
        }
        context.vec[0] = r.buffer[r.end..];
        mr.batch.addAt(operation.index, .{ .file_read_streaming = .{
            .file = context.fr.file,
            .data = &context.vec,
        } });
    }

    if (!any_completed) return error.EndOfStream;
}

/// 等待所有流失败或到达末尾。
pub fn fillRemaining(mr: *MultiReader, timeout: Io.Timeout) Io.Batch.AwaitConcurrentError!void {
    while (fill(mr, 1, timeout)) |_| {} else |err| switch (err) {
        error.EndOfStream => return,
        else => |e| return e,
    }
}

fn rebaseGrowing(mr: *MultiReader, context: *Context, capacity: usize) Allocator.Error!void {
    const gpa = mr.gpa;
    const r = &context.fr.interface;
    if (r.buffer.len >= capacity) {
        const data = r.buffer[r.seek..r.end];
        @memmove(r.buffer[0..data.len], data);
        r.seek = 0;
        r.end = data.len;
    } else {
        const adjusted_capacity = std.ArrayList(u8).growCapacity(capacity);

        if (r.seek == 0) {
            if (gpa.remap(r.buffer, adjusted_capacity)) |new_memory| {
                r.buffer = new_memory;
                return;
            }
        }

        const data = r.buffer[r.seek..r.end];
        const new = try gpa.alloc(u8, adjusted_capacity);
        @memcpy(new[0..data.len], data);
        gpa.free(r.buffer);
        r.buffer = new;
        r.seek = 0;
        r.end = data.len;
    }
}