缓存文件句柄的关键信息,例如:
- 调用 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
别名
别名目标 std.debug.assert
std.Io.File.Reader.atEnd
函数
返回流是否到达逻辑末尾。
pub fn atEnd(r: *Reader) bool
参数
r: *Reader
std.Io.File.Reader.discard
函数
fn discard(io_reader: *Io.Reader, limit: Io.Limit) Io.Reader.Error!usize
参数
错误
- EndOfStream
- ReadFailed
详细诊断参见
Reader的实现。
std.Io.File.Reader.Error
错误集合
错误
- 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
别名
别名目标 std.Io.File
std.Io.File.Reader.getSize
函数
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
函数
pub fn init(file: File, io: Io, buffer: []u8) Reader
参数
std.Io.File.Reader.initInterface
函数
pub fn initInterface(buffer: []u8) Io.Reader
参数
buffer: []u8
std.Io.File.Reader.initSize
函数
pub fn initSize(file: File, io: Io, buffer: []u8, size: ?u64) Reader
参数
std.Io.File.Reader.initStreaming
函数
定位式 I/O 不影响全局寻址位置,因此线程安全性更好; 但若没有此类系统调用,预先初始化为流式模式 可省去一次注定失败的系统调用。
pub fn initStreaming(file: File, io: Io, buffer: []u8) Reader
参数
std.Io.File.Reader.Io
别名
别名目标 std.Io
std.Io.File.Reader.logicalPos
函数
pub fn logicalPos(r: *const Reader) u64
参数
r: *const Reader
std.Io.File.Reader.max_buffers_len
常量
尝试通过底层读取调用发送尽可能多的字节 向量时,要在栈上存储的切片数量。
std.Io.File.Reader.Mode
容器
字段
streaming
positional
streaming_simple避免调用 read 和 readv 以外的系统调用。
positional_simple避免执行 pread 和 preadv 之外的系统调用。
failure表示因定位失败而无法继续读取。
std.Io.File.Reader.Mode.toSimple
函数
pub fn toSimple(m: @This()) @This()
参数
m: @This()
std.Io.File.Reader.Mode.toStreaming
函数
pub fn toStreaming(m: @This()) @This()
参数
m: @This()
std.Io.File.Reader.Reader
别名
别名目标 std.Io.File.Reader
std.Io.File.Reader.readVec
函数
fn readVec(io_reader: *Io.Reader, data: [][]u8) Io.Reader.Error!usize
参数
错误
- EndOfStream
- ReadFailed
详细诊断参见
Reader的实现。
std.Io.File.Reader.readVecPositional
函数
fn readVecPositional(r: *Reader, data: [][]u8) Io.Reader.Error!usize
参数
r: *Reader
data: [][]u8
错误
- EndOfStream
- ReadFailed
详细诊断参见
Reader的实现。
std.Io.File.Reader.readVecStreaming
函数
fn readVecStreaming(r: *Reader, data: [][]u8) Io.Reader.Error!usize
参数
r: *Reader
data: [][]u8
错误
- EndOfStream
- ReadFailed
详细诊断参见
Reader的实现。
std.Io.File.Reader.seekBy
函数
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
错误集合
错误
- AccessDenied SeekError
文件描述符不具备执行定位所需的权限。
- Canceled Cancelable
调用方请求停止异步操作。
- EndOfStream
定位操作回退为读取,但在到达请求的位置前遇到末尾。
pos保持在文件末尾。- ReadFailed
定位操作回退为读取操作,但读取失败。
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- Unseekable SeekError
std.Io.File.Reader.seekTo
函数
相对于文件开头重新定位逻辑读取偏移量。
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
函数
fn setLogicalPos(r: *Reader, offset: u64) void
参数
r: *Reader
offset: u64
std.Io.File.Reader.SizeError
错误集合
错误
- AccessDenied StatError
在 WASI 中,当文件描述符不具备获取自身 filestat 信息所需的权限时,可能发生此错误。
- Canceled Cancelable
调用方请求停止异步操作。
- PermissionDenied StatError
- Streaming StatError
尝试对非文件流调用 stat。
- SystemResources StatError
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.File.Reader.std
别名
别名目标 std
std.Io.File.Reader.stream
函数
fn stream(io_reader: *Io.Reader, w: *Io.Writer, limit: Io.Limit) Io.Reader.StreamError!usize
参数
错误
std.Io.File.Reader.streamMode
函数
pub fn streamMode(r: *Reader, w: *Io.Writer, limit: Io.Limit, mode: Mode) Io.Reader.StreamError!usize
参数
错误
源码
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;
}