跳转到内容

std.Io.File.Reader

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

第 1 行

缓存文件句柄的关键信息,例如:

  • 调用 stat 得到的大小,或调用中发生的错误。
  • 当前寻址位置。
  • 尝试寻址时发生的错误。
  • 应采用按位置读取还是流式读取。
  • 应通过文件描述符间的系统调用读取,例如 sendfile, 还是通过普通形式读取,例如 read。

实现 Io.Reader 接口。

字段

io: Io
file: File
err: ?Error = null
mode: Mode = .positional
pos: u64 = 0

跟踪文件中的实际定位位置。 要获取逻辑位置,请使用 logicalPos。

size: ?u64 = null
size_err: ?SizeError = null
seek_err: ?SeekError = null
interface: Io.Reader

std.Io.File.Reader.assert

别名

第 15 行

别名目标 std.debug.assert

std.Io.File.Reader.atEnd

函数

第 374 行

返回流是否到达逻辑末尾。

pub fn atEnd(r: *Reader) bool

参数

r: *Reader

std.Io.File.Reader.discard

函数

第 300 行

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

参数

io_reader: *Io.Reader
limit: Io.Limit

错误

EndOfStream
ReadFailed

详细诊断参见 Reader 的实现。

std.Io.File.Reader.Error

错误集合

第 29 行

错误

AccessDenied UnendingError

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

Canceled Cancelable

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

ConnectionResetByPeer UnendingError
InputOutput UnendingError
IsDir UnendingError

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

LockViolation UnendingError

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

NotOpenForReading UnendingError

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

SocketUnconnected UnendingError
SystemResources UnendingError
Unexpected UnexpectedError

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

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

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

WouldBlock UnendingError

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

std.Io.File.Reader.File

别名

第 14 行

别名目标 std.Io.File

std.Io.File.Reader.getSize

函数

第 115 行

pub fn getSize(r: *Reader) SizeError!u64

参数

r: *Reader

错误

AccessDenied StatError

在 WASI 中,当文件描述符不具备获取自身 filestat 信息所需的权限时,可能发生此错误。

Canceled Cancelable

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

PermissionDenied StatError
Streaming StatError

尝试对非文件流调用 stat。

SystemResources StatError
Unexpected UnexpectedError

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

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

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

std.Io.File.Reader.init

函数

第 84 行

pub fn init(file: File, io: Io, buffer: []u8) Reader

参数

file: File
io: Io
buffer: []u8

std.Io.File.Reader.initInterface

函数

第 71 行

pub fn initInterface(buffer: []u8) Io.Reader

参数

buffer: []u8

std.Io.File.Reader.initSize

函数

第 92 行

pub fn initSize(file: File, io: Io, buffer: []u8, size: ?u64) Reader

参数

file: File
io: Io
buffer: []u8
size: ?u64

std.Io.File.Reader.initStreaming

函数

第 104 行

定位式 I/O 不影响全局寻址位置,因此线程安全性更好; 但若没有此类系统调用,预先初始化为流式模式 可省去一次注定失败的系统调用。

pub fn initStreaming(file: File, io: Io, buffer: []u8) Reader

参数

file: File
io: Io
buffer: []u8

std.Io.File.Reader.Io

别名

第 13 行

别名目标 std.Io

std.Io.File.Reader.logicalPos

函数

第 183 行

pub fn logicalPos(r: *const Reader) u64

参数

r: *const Reader

std.Io.File.Reader.max_buffers_len

常量

第 197 行

尝试通过底层读取调用发送尽可能多的字节 向量时,要在栈上存储的切片数量。

std.Io.File.Reader.Mode

容器

第 44 行

字段

streaming
positional
streaming_simple

避免调用 read 和 readv 以外的系统调用。

positional_simple

避免执行 pread 和 preadv 之外的系统调用。

failure

表示因定位失败而无法继续读取。

std.Io.File.Reader.Mode.toSimple

函数

第 62 行

pub fn toSimple(m: @This()) @This()

参数

m: @This()

std.Io.File.Reader.Mode.toStreaming

函数

第 54 行

pub fn toStreaming(m: @This()) @This()

参数

m: @This()

std.Io.File.Reader.Reader

别名

第 10 行

别名目标 std.Io.File.Reader

std.Io.File.Reader.readVec

函数

第 231 行

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

参数

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

错误

EndOfStream
ReadFailed

详细诊断参见 Reader 的实现。

std.Io.File.Reader.readVecPositional

函数

第 240 行

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

参数

r: *Reader
data: [][]u8

错误

EndOfStream
ReadFailed

详细诊断参见 Reader 的实现。

std.Io.File.Reader.readVecStreaming

函数

第 276 行

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

参数

r: *Reader
data: [][]u8

错误

EndOfStream
ReadFailed

详细诊断参见 Reader 的实现。

std.Io.File.Reader.seekBy

函数

第 134 行

pub fn seekBy(r: *Reader, offset: i64) SeekError!void

参数

r: *Reader
offset: i64

错误

AccessDenied SeekError

文件描述符不具备执行定位所需的权限。

Canceled Cancelable

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

EndOfStream

定位操作回退为读取,但在到达请求的位置前遇到末尾。 pos 保持在文件末尾。

ReadFailed

定位操作回退为读取操作,但读取失败。

Unexpected UnexpectedError

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

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

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

Unseekable SeekError

std.Io.File.Reader.SeekError

错误集合

第 36 行

错误

AccessDenied SeekError

文件描述符不具备执行定位所需的权限。

Canceled Cancelable

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

EndOfStream

定位操作回退为读取,但在到达请求的位置前遇到末尾。 pos 保持在文件末尾。

ReadFailed

定位操作回退为读取操作,但读取失败。

Unexpected UnexpectedError

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

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

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

Unseekable SeekError

std.Io.File.Reader.seekTo

函数

第 163 行

相对于文件开头重新定位逻辑读取偏移量。

pub fn seekTo(r: *Reader, offset: u64) SeekError!void

参数

r: *Reader
offset: u64

错误

AccessDenied SeekError

文件描述符不具备执行定位所需的权限。

Canceled Cancelable

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

EndOfStream

定位操作回退为读取,但在到达请求的位置前遇到末尾。 pos 保持在文件末尾。

ReadFailed

定位操作回退为读取操作,但读取失败。

Unexpected UnexpectedError

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

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

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

Unseekable SeekError

std.Io.File.Reader.setLogicalPos

函数

第 187 行

fn setLogicalPos(r: *Reader, offset: u64) void

参数

r: *Reader
offset: u64

std.Io.File.Reader.SizeError

错误集合

第 31 行

错误

AccessDenied StatError

在 WASI 中,当文件描述符不具备获取自身 filestat 信息所需的权限时,可能发生此错误。

Canceled Cancelable

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

PermissionDenied StatError
Streaming StatError

尝试对非文件流调用 stat。

SystemResources StatError
Unexpected UnexpectedError

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

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

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

std.Io.File.Reader.std

别名

第 12 行

别名目标 std

std.Io.File.Reader.stream

函数

第 199 行

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

参数

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

错误

EndOfStream

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

ReadFailed

详细诊断参见 Reader 的实现。

WriteFailed

详细诊断信息见 Writer 实现。

std.Io.File.Reader.streamMode

函数

第 204 行

pub fn streamMode(r: *Reader, w: *Io.Writer, limit: Io.Limit, mode: Mode) Io.Reader.StreamError!usize

参数

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

错误

EndOfStream

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

ReadFailed

详细诊断参见 Reader 的实现。

WriteFailed

详细诊断信息见 Writer 实现。

源码

std/Io/File/Reader.zig

//! 缓存文件句柄的关键信息,例如:
//! * 调用 stat 得到的大小,或调用中发生的错误。
//! * 当前寻址位置。
//! * 尝试寻址时发生的错误。
//! * 应采用按位置读取还是流式读取。
//! * 应通过文件描述符间的系统调用读取,例如 `sendfile`,
//!   还是通过普通形式读取,例如 `read`。
//!
//! 实现 `Io.Reader` 接口。
const Reader = @This();

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

io: Io,
file: File,
err: ?Error = null,
mode: Mode = .positional,
/// 跟踪文件中的实际定位位置。
/// 要获取逻辑位置,请使用 `logicalPos`。
pos: u64 = 0,
size: ?u64 = null,
size_err: ?SizeError = null,
seek_err: ?SeekError = null,
interface: Io.Reader,

pub const Error = Io.Operation.FileReadStreaming.UnendingError || Io.Cancelable;

pub const SizeError = File.StatError || error{
    /// 例如,文件句柄是网络套接字,因而没有大小时会发生。
    Streaming,
};

pub const SeekError = File.SeekError || error{
    /// 定位操作回退为读取,但在到达请求的位置前遇到末尾。
    /// `pos` 保持在文件末尾。
    EndOfStream,
    /// 定位操作回退为读取操作,但读取失败。
    ReadFailed,
};

pub const Mode = enum {
    streaming,
    positional,
    /// 避免调用 `read` 和 `readv` 以外的系统调用。
    streaming_simple,
    /// 避免执行 `pread` 和 `preadv` 之外的系统调用。
    positional_simple,
    /// 表示因定位失败而无法继续读取。
    failure,

    pub fn toStreaming(m: @This()) @This() {
        return switch (m) {
            .positional, .streaming => .streaming,
            .positional_simple, .streaming_simple => .streaming_simple,
            .failure => .failure,
        };
    }

    pub fn toSimple(m: @This()) @This() {
        return switch (m) {
            .positional, .positional_simple => .positional_simple,
            .streaming, .streaming_simple => .streaming_simple,
            .failure => .failure,
        };
    }
};

pub fn initInterface(buffer: []u8) Io.Reader {
    return .{
        .vtable = &.{
            .stream = stream,
            .discard = discard,
            .readVec = readVec,
        },
        .buffer = buffer,
        .seek = 0,
        .end = 0,
    };
}

pub fn init(file: File, io: Io, buffer: []u8) Reader {
    return .{
        .io = io,
        .file = file,
        .interface = initInterface(buffer),
    };
}

pub fn initSize(file: File, io: Io, buffer: []u8, size: ?u64) Reader {
    return .{
        .io = io,
        .file = file,
        .interface = initInterface(buffer),
        .size = size,
    };
}

/// 定位式 I/O 不影响全局寻址位置,因此线程安全性更好;
/// 但若没有此类系统调用,预先初始化为流式模式
/// 可省去一次注定失败的系统调用。
pub fn initStreaming(file: File, io: Io, buffer: []u8) Reader {
    return .{
        .io = io,
        .file = file,
        .interface = Reader.initInterface(buffer),
        .mode = .streaming,
        .seek_err = error.Unseekable,
        .size_err = error.Streaming,
    };
}

pub fn getSize(r: *Reader) SizeError!u64 {
    return r.size orelse {
        if (r.size_err) |err| return err;
        if (r.file.stat(r.io)) |st| {
            if (st.kind == .file) {
                r.size = st.size;
                return st.size;
            } else {
                r.mode = r.mode.toStreaming();
                r.size_err = error.Streaming;
                return error.Streaming;
            }
        } else |err| {
            r.size_err = err;
            return err;
        }
    };
}

pub fn seekBy(r: *Reader, offset: i64) SeekError!void {
    const io = r.io;
    switch (r.mode) {
        .positional, .positional_simple => {
            setLogicalPos(r, @intCast(@as(i64, @intCast(logicalPos(r))) + offset));
        },
        .streaming, .streaming_simple => {
            const seek_err = r.seek_err orelse e: {
                if (io.vtable.fileSeekBy(io.userdata, r.file, offset)) |_| {
                    setLogicalPos(r, @intCast(@as(i64, @intCast(logicalPos(r))) + offset));
                    return;
                } else |err| {
                    r.seek_err = err;
                    break :e err;
                }
            };
            var remaining = std.math.cast(u64, offset) orelse return seek_err;
            while (remaining > 0) {
                remaining -= discard(&r.interface, .limited64(remaining)) catch |err| {
                    r.seek_err = err;
                    return err;
                };
            }
        },
        .failure => return r.seek_err.?,
    }
}

/// 相对于文件开头重新定位逻辑读取偏移量。
pub fn seekTo(r: *Reader, offset: u64) SeekError!void {
    const io = r.io;
    switch (r.mode) {
        .positional, .positional_simple => {
            setLogicalPos(r, offset);
        },
        .streaming, .streaming_simple => {
            const logical_pos = logicalPos(r);
            if (offset >= logical_pos) return seekBy(r, @intCast(offset - logical_pos));
            if (r.seek_err) |err| return err;
            io.vtable.fileSeekTo(io.userdata, r.file, offset) catch |err| {
                r.seek_err = err;
                return err;
            };
            setLogicalPos(r, offset);
        },
        .failure => return r.seek_err.?,
    }
}

pub fn logicalPos(r: *const Reader) u64 {
    return r.pos - r.interface.bufferedLen();
}

fn setLogicalPos(r: *Reader, offset: u64) void {
    const logical_pos = r.logicalPos();
    if (offset < logical_pos or offset >= r.pos) {
        r.interface.tossBuffered();
        r.pos = offset;
    } else r.interface.toss(@intCast(offset - logical_pos));
}

/// 尝试通过底层读取调用发送尽可能多的字节
/// 向量时,要在栈上存储的切片数量。
const max_buffers_len = 16;

fn stream(io_reader: *Io.Reader, w: *Io.Writer, limit: Io.Limit) Io.Reader.StreamError!usize {
    const r: *Reader = @alignCast(@fieldParentPtr("interface", io_reader));
    return streamMode(r, w, limit, r.mode);
}

pub fn streamMode(r: *Reader, w: *Io.Writer, limit: Io.Limit, mode: Mode) Io.Reader.StreamError!usize {
    switch (mode) {
        .positional, .streaming => return w.sendFile(r, limit) catch |write_err| switch (write_err) {
            error.Unimplemented => {
                r.mode = r.mode.toSimple();
                return 0;
            },
            else => |e| return e,
        },
        .positional_simple => {
            const dest = limit.slice(try w.writableSliceGreedy(1));
            var data: [1][]u8 = .{dest};
            const n = try readVecPositional(r, &data);
            w.advance(n);
            return n;
        },
        .streaming_simple => {
            const dest = limit.slice(try w.writableSliceGreedy(1));
            var data: [1][]u8 = .{dest};
            const n = try readVecStreaming(r, &data);
            w.advance(n);
            return n;
        },
        .failure => return error.ReadFailed,
    }
}

fn readVec(io_reader: *Io.Reader, data: [][]u8) Io.Reader.Error!usize {
    const r: *Reader = @alignCast(@fieldParentPtr("interface", io_reader));
    switch (r.mode) {
        .positional, .positional_simple => return readVecPositional(r, data),
        .streaming, .streaming_simple => return readVecStreaming(r, data),
        .failure => return error.ReadFailed,
    }
}

fn readVecPositional(r: *Reader, data: [][]u8) Io.Reader.Error!usize {
    const io = r.io;
    var iovecs_buffer: [max_buffers_len][]u8 = undefined;
    const dest_n, const data_size = try r.interface.writableVector(&iovecs_buffer, data);
    const dest = iovecs_buffer[0..dest_n];
    assert(dest[0].len > 0);
    const n = io.vtable.fileReadPositional(io.userdata, r.file, dest, r.pos) catch |err| switch (err) {
        error.Unseekable => {
            r.mode = r.mode.toStreaming();
            const pos = r.pos;
            if (pos != 0) {
                r.pos = 0;
                r.seekBy(@intCast(pos)) catch {
                    r.mode = .failure;
                    return error.ReadFailed;
                };
            }
            return 0;
        },
        else => |e| {
            r.err = e;
            return error.ReadFailed;
        },
    };
    if (n == 0) {
        r.size = r.pos;
        return error.EndOfStream;
    }
    r.pos += n;
    if (n > data_size) {
        r.interface.end += n - data_size;
        return data_size;
    }
    return n;
}

fn readVecStreaming(r: *Reader, data: [][]u8) Io.Reader.Error!usize {
    const io = r.io;
    var iovecs_buffer: [max_buffers_len][]u8 = undefined;
    const dest_n, const data_size = try r.interface.writableVector(&iovecs_buffer, data);
    const dest = iovecs_buffer[0..dest_n];
    assert(dest[0].len > 0);
    const n = r.file.readStreaming(io, dest) catch |err| switch (err) {
        error.EndOfStream => {
            r.size = r.pos;
            return error.EndOfStream;
        },
        else => |e| {
            r.err = e;
            return error.ReadFailed;
        },
    };
    r.pos += n;
    if (n > data_size) {
        r.interface.end += n - data_size;
        return data_size;
    }
    return n;
}

fn discard(io_reader: *Io.Reader, limit: Io.Limit) Io.Reader.Error!usize {
    const r: *Reader = @alignCast(@fieldParentPtr("interface", io_reader));
    const io = r.io;
    const file = r.file;
    switch (r.mode) {
        .positional, .positional_simple => {
            const size = r.getSize() catch {
                r.mode = r.mode.toStreaming();
                return 0;
            };
            const logical_pos = logicalPos(r);
            const bytes_remaining = size - logical_pos;
            if (bytes_remaining == 0) return error.EndOfStream;
            const delta = @min(@backingInt(limit), bytes_remaining);
            setLogicalPos(r, logical_pos + delta);
            return delta;
        },
        .streaming, .streaming_simple => {
            // 遗憾的是,在不知道大小的情况下无法向前查找,
            // 因为所提供的查找系统调用在查找位置
            // 超出末尾时,不会返回真正的
            // 末尾位置。
            fallback: {
                if (r.size_err == null and r.seek_err == null) break :fallback;

                const buffered_len = r.interface.bufferedLen();
                var remaining = @backingInt(limit);
                if (remaining <= buffered_len) {
                    r.interface.seek += remaining;
                    return remaining;
                }
                remaining -= buffered_len;
                r.interface.seek = 0;
                r.interface.end = 0;

                var trash_buffer: [128]u8 = undefined;
                var data: [1][]u8 = .{trash_buffer[0..@min(trash_buffer.len, remaining)]};
                var iovecs_buffer: [max_buffers_len][]u8 = undefined;
                const dest_n, const data_size = try r.interface.writableVector(&iovecs_buffer, &data);
                const dest = iovecs_buffer[0..dest_n];
                assert(dest[0].len > 0);
                const n = file.readStreaming(io, dest) catch |err| switch (err) {
                    error.EndOfStream => {
                        r.size = r.pos;
                        return error.EndOfStream;
                    },
                    else => |e| {
                        r.err = e;
                        return error.ReadFailed;
                    },
                };
                r.pos += n;
                if (n > data_size) {
                    r.interface.end += n - data_size;
                    remaining -= data_size;
                } else {
                    remaining -= n;
                }
                return @backingInt(limit) - remaining;
            }
            const size = r.getSize() catch return 0;
            const n = @min(size - r.pos, std.math.maxInt(i64), @backingInt(limit));
            io.vtable.fileSeekBy(io.userdata, file, n) catch |err| {
                r.seek_err = err;
                return 0;
            };
            r.pos += n;
            return n;
        },
        .failure => return error.ReadFailed,
    }
}

/// 返回流是否到达逻辑末尾。
pub fn atEnd(r: *Reader) bool {
    // 即使 stat 失败,遇到末尾时仍会设置 size。
    const size = r.size orelse return false;
    return size - logicalPos(r) == 0;
}