仓颉标准库 std.io 实践:BufferedInputStream 缓冲输入流使用与原理深度解析

原创2026-10-14 19:35:061,902 阅读
文章标签:编程语言语言运行时标准库内存管理并发编程OpenHarmony

仓颉标准库 std.io 实践:BufferedInputStream 缓冲输入流使用与原理深度解析

本文以仓颉(Cangjie)标准库 std.io 中的 BufferedInputStream 为核心,从官方示例出发,结合标准库源码深入讲解缓冲输入流的构造方式、read/readByte 读取机制、缓冲失效与填充原理、reset 复用、Resource 资源释放以及 Seekable 游标操作,帮助读者在真实项目中正确、高效地使用缓冲输入流处理字节数据。

概述:为什么需要 BufferedInputStream

在仓颉标准库中,I/O 操作以"流"(Stream)为抽象载体,程序从输入流(如文件、网络、内存字节块)中读取有序的字节序列。InputStream 接口定义了最基础的读取契约:

public interface InputStream {
    func read(buffer: Array<Byte>): Int64
}

该接口定义见 stream.cj。底层流的每次 read 都可能涉及系统调用或数据搬运,若上层业务按字节、小批量地频繁读取,性能开销会很大。

BufferedInputStream<T> 正是为此设计的缓冲包装流:它在内部维护一个字节缓冲数组,先把底层流中的一段数据一次性"搬运"进缓冲区,上层读取时优先从缓冲区取数,从而显著减少对底层流的访问次数。其类声明与官方定位为:

public class BufferedInputStream<T> <: InputStream where T <: InputStream {
    var inputStream: T
    let inBuf: Array<Byte>
    var curPos: Int64 = 0
    var availLen: Int64 = 0
    ...
}

对应实现见 buffered_input_stream.cj。其中 inBuf 是内部缓冲数组,curPos 指向缓冲区内下一个待读字节的位置,availLen 表示缓冲区中当前可读的有效字节数。官方 API 文档对其功能的描述是:可以将其他 InputStream 类型的输入流(如 ByteBuffer)绑定到 BufferedInputStream 实例上,读取数据时先从被绑定的流读入缓冲区暂存,再按需从缓冲区读取,见 io_package_classes.md。

官方示例:从内存流中读取数据

本篇文章的核心示例来自官方文档 buffered_input_stream.md,它演示了 BufferedInputStream 最基础、最典型的用法:用 ByteBuffer 构造一个内存字节流,再用 BufferedInputStream 包装后读取:

import std.io.*

main(): Unit {
    let arr1 = "0123456789".toArray()
    let byteBuffer = ByteBuffer()
    byteBuffer.write(arr1)
    let bufferedInputStream = BufferedInputStream(byteBuffer)
    let arr2 = Array<Byte>(20, repeat: 0)

    /* Read data from the stream and return the length of data read */
    let readLen = bufferedInputStream.read(arr2)
    println(String.fromUtf8(arr2[..readLen]))
}

执行结果:

0123456789

示例中的关键步骤可以拆解为:

  1. "0123456789".toArray() 将字符串转换为 Array<Byte>,作为源数据;
  2. ByteBuffer() 创建内存字节流,byteBuffer.write(arr1) 将源数据写入流中。ByteBuffer 是基于 Array<Byte> 实现的读写字节流类,同时实现了 IOStream 与 Seekable 接口,实现见 byte_buffer.cj;
  3. BufferedInputStream(byteBuffer) 将内存流绑定到缓冲输入流,此后对 bufferedInputStream 的读取会先经过内部缓冲区;
  4. read(arr2) 从流中读取数据并返回实际读取的字节数,String.fromUtf8(arr2[..readLen]) 将读取到的有效字节切片还原为字符串输出。

值得注意:read 返回的是实际读取到的字节数而非缓冲区容量。官方示例中用 arr2[..readLen] 精确切片,避免把缓冲区中未写入的初始零字节也打印出来,这是一个值得养成的编码习惯。

三种构造方式:默认容量、指定容量与复用缓冲区

BufferedInputStream 提供三种构造方式,均可用于绑定任意满足 T <: InputStream 约束的输入流。

默认容量构造

public init(input: T)

该构造器使用默认缓冲区容量 4096 字节(DEFAULT_BUFFER_CAPACITY,定义于 stream.cj),内部实现为 this(input, DEFAULT_BUFFER_CAPACITY)。对应 API 文档见 io_package_classes.md。大多数场景下直接使用此构造器即可。

指定容量构造

public init(input: T, capacity: Int64)

capacity 指定内部缓冲区的容量。源码实现中,当 capacity <= 0 时会抛出 IllegalArgumentException:

public init(input: T, capacity: Int64) {
    if (capacity <= 0) {
        throw IllegalArgumentException("Invalid argument 'capacity': expected a positive value, got '${capacity}'.")
    }
    inputStream = input
    inBuf = Array<Byte>(capacity, repeat: 0)
}

见 buffered_input_stream.cj。API 文档明确:capacity 必须大于 0,否则抛出 IllegalArgumentException,见 io_package_classes.md。容量大小会影响底层流的访问频率:容量越大,单次填充可承载的数据越多,适合大块数据读取;容量较小则内存占用低,适合轻量场景。

复用外部缓冲区构造

public init(input: T, buffer: Array<Byte>)

该构造器直接将调用方传入的 Array<Byte> 作为内部缓冲区,不重新分配内存。官方文档指出:在性能敏感场景下,复用传入的 buffer 可以减少内存分配频率、提升性能,见 io_package_classes.md。源码中若 buffer.size == 0 会抛出 IllegalArgumentException:

public init(input: T, buffer: Array<Byte>) {
    if (buffer.size == 0) {
        throw IllegalArgumentException("Invalid argument 'buffer': buffer size is 0.")
    }
    inputStream = input
    inBuf = buffer
}

见 buffered_input_stream.cj。与指定容量构造不同,此构造器不做数组拷贝,外部对 buffer 的引用与内部缓冲指向同一数组,使用时应避免在流生命周期内意外改写该数组。

核心读取 API:read 与 readByte

read(buffer: Array): Int64

read 是 InputStream 接口的核心方法,签名与行为如下:

  • 参数 buffer:存放读取数据的字节数组,不能为空(为空时抛 IllegalArgumentException);
  • 返回值:实际读取到的字节数;
  • 当流已读尽时返回 0(源码中以 availLen == -1 作为"流结束"哨兵标记)。

源码实现的核心逻辑(见 buffered_input_stream.cj):

public func read(buffer: Array<Byte>): Int64 {
    if (availLen == -1) {
        return 0
    }

    var len = buffer.size
    if (len == 0) {
        throw IllegalArgumentException("Invalid argument 'buffer': buffer size is 0.")
    }

    var count = 0
    while (len > 0) {
        if (availLen == 0) {
            fillInBuf()
            if (availLen == -1) {
                break
            }
        }

        let copyLen = if (availLen <= len) {
            availLen
        } else {
            len
        }

        inBuf.copyTo(buffer, curPos, count, copyLen)
        curPos += copyLen
        availLen -= copyLen
        count += copyLen
        len -= copyLen
    }

    count
}

该实现呈现了几个值得注意的设计点:

  • 循环填充直至满足需求或流结束:只要目标缓冲区还没装满,就不断从内部缓冲取数;内部缓冲耗尽时调用 fillInBuf() 从底层流重新填充。
  • availLen == -1 表示流结束:fillInBuf() 在底层流返回 0(无更多数据)时把 availLen 置为 -1,此后 read 一律返回 0。
  • 拷贝长度取最小值:copyLen 取 availLen 与剩余需求 len 的较小者,确保既不越界读取也不溢出写入。

readByte(): ?Byte

readByte 用于单字节读取,返回 ?Byte 可选类型:读到字节时返回 Some,流结束时返回 None(见 buffered_input_stream.cj)。其逻辑与 read 一致:先检查 availLen 是否为 -1(流结束)或 0(需重新填充),然后从 inBuf[curPos] 取一个字节并移动游标。

典型用法是按字节遍历整个流,遇到 None 即停止:

import std.io.ByteBuffer
import std.io.BufferedInputStream

main(): Unit {
    /* Create input stream and write data */
    let inputStream = ByteBuffer()
    let sourceData = "abc".toArray()
    inputStream.write(sourceData)
    let bufferedStream = BufferedInputStream(inputStream)

    /* Read all bytes sequentially */
    while (true) {
        let byte = bufferedStream.readByte()
        if (byte == None) {
            break
        }
        println(String.fromUtf8(byte.getOrThrow()))
    }
}

执行结果为逐行输出 a、b、c,该示例同样收录于 io_package_classes.md。

缓冲填充机制 fillInBuf

fillInBuf() 是内部私有方法(见 buffered_input_stream.cj),负责将底层流数据读入内部缓冲:

func fillInBuf(): Unit {
    let readNum = inputStream.read(inBuf)
    if (readNum > 0) {
        curPos = 0
        availLen = readNum
    } else {
        availLen = -1
    }
}

它直接调用被包装流 inputStream 的 read(inBuf),以内部缓冲整体作为目标。底层流读取成功(readNum > 0)时重置 curPos = 0 并将 availLen 置为实际读入量;底层流返回 0 表示数据耗尽,则置 availLen = -1 标记流结束。这一"整段填充 + 游标消费"的设计,正是缓冲输入流减少底层访问次数的关键所在。

流切换复用:reset

reset(input: T) 可以将 BufferedInputStream 重新绑定到新的底层输入流,同时清空内部缓冲状态(curPos = 0、availLen = 0),但不改变缓冲区容量:

public func reset(input: T): Unit {
    inputStream = input
    curPos = 0
    availLen = 0
}

见 buffered_input_stream.cj。官方 API 文档强调"重置状态但不会重置 capacity",见 io_package_classes.md。典型应用是复用同一个缓冲对象依次读取多个流,避免反复构造对象的开销。官方示例先读取第一个流的内容,再 reset 切换到第二个流继续读取(完整示例见 io_package_classes.md):

First message: Hello
Second message: World

资源管理:close 与 try-with-resource

当被包装的底层流同时实现了 Resource 接口时(即 T <: Resource),BufferedInputStream<T> 会通过扩展自动实现 Resource:

extend<T> BufferedInputStream<T> <: Resource where T <: Resource {
    public func close(): Unit {
        inputStream.close()
    }

    public func isClosed(): Bool {
        inputStream.isClosed()
    }
}

见 buffered_input_stream.cj。close() 会委托给底层流的 close(),isClosed() 同样透传底层流的关闭状态。

有了 Resource 实现,BufferedInputStream 便可在 try-with-resource 语法中使用,由语法自动调用 close() 释放资源。官方示例中自定义了一个同时实现 InputStream 与 Resource 的类 A,演示了在 try (r = bufferedStream) { ... } 块内读取数据、块结束后自动关闭资源的过程(完整代码见 io_package_classes.md),其输出为:

Get the resource
false
Hello World
Resource is closed
true

使用注意:官方文档特别提醒,调用 close() 之后不应再调用 BufferedInputStream 的其他接口,否则可能产生未定义行为。

游标操作:Seekable 支持

当底层流实现了 Seekable 接口(T <: Seekable)时,BufferedInputStream<T> 自动获得 Seekable 能力(见 buffered_input_stream.cj),提供以下属性与方法:

成员 签名 说明
length prop length: Int64 当前流中数据总量(字节数)
position prop position: Int64 当前游标位置
remainLength prop remainLength: Int64 当前游标到流末尾的未读数据量(字节,不含缓冲区内数据)
seek func seek(sp: SeekPosition): Int64 移动游标到指定位置,返回新位置相对流起始的偏移

Seekable 接口定义见 stream.cj。seek 实现会先清空内部缓冲(curPos = 0、availLen = 0),再委托底层流移动游标,因此缓冲中的残留数据会被丢弃:

public func seek(sp: SeekPosition): Int64 {
    let pos = inputStream.seek(sp)
    curPos = 0
    availLen = 0
    pos
}

SeekPosition 是描述游标基准的枚举(见 io_package_enums.md):

  • Begin(Int64):从流起始位置移动指定长度;
  • Current(Int64):从当前游标位置移动指定长度;
  • End(Int64):从流末尾移动指定长度。

官方在 io_package_classes.md 中给出的综合示例展示了这些能力:读取 11 字节的 "Hello World" 后,length 为 11、position 为 11、remainLength 为 0;seek(Current(11)) 可将游标移动到 22(允许越过流末尾);而 seek(Begin(-1)) 因试图移动到数据起点之前而抛出 IOException。其执行结果为:

Length : 11
Position : 11
Remain Length : 0
Position after seek() : 22
Error: Can't move the position before the beginning of the stream.
World

与流工具函数的配合使用

std.io 包还提供若干配合 InputStream & Seekable 使用的便捷函数(API 见 io_package_funcs.md):

  • readToEnd<T>(from: T): Array<Byte>:读取参数中所有未读数据并以 Array<Byte> 返回;
  • readString<T>(from: T): String:读取全部剩余内容并转换为字符串,若剩余字节不符合 UTF-8 编码规则则抛出 ContentFormatException;
  • readStringUnchecked<T>(from: T): String:不校验编码地读取全部剩余内容并返回字符串(unsafe 函数,需在 unsafe 块中调用);
  • copy(from: InputStream, to!: OutputStream): Int64:将输入流未读数据拷贝到输出流,返回拷贝字节数。

由于 BufferedInputStream<T> 在 T <: Seekable 时同样实现 Seekable,因此它可以直接作为这些函数的参数使用,例如读取缓冲流剩余内容:readToEnd(bufferedStream)。

另外,标准库中的 StringReader<T> 在内部正是基于 BufferedInputStream<T> 实现的——其成员 inputBIS: BufferedInputStream<T> 在构造时被初始化为 BufferedInputStream(input)(见 string_reader.cj),可见缓冲输入流是字符串读取等高层 I/O 能力的基础组件。

小结

BufferedInputStream<T> 是仓颉标准库 std.io 中面向输入流的缓冲适配层,核心价值在于以"整段填充、游标消费"的方式减少底层流的访问次数:

  • 三种构造方式分别覆盖默认容量(4096)、显式容量和外部缓冲区复用三种场景;
  • read 返回实际读取字节数,readByte 以 None 表示流结束,二者共享 availLen/curPos/fillInBuf 缓冲机制;
  • reset 支持在不改变容量的前提下切换底层流;
  • 通过 Resource 扩展支持 try-with-resource 自动释放;
  • 通过 Seekable 扩展支持 length、position、remainLength 查询与 seek 游标移动。

建议在编写文件、网络等字节流读取逻辑时,优先考虑以 BufferedInputStream 包装底层流;同时留意 read 的返回值语义、readByte 的 None 终止约定,以及 seek 会清空缓冲区这一行为。相关源码可继续阅读 buffered_input_stream.cj、stream.cj 与 byte_buffer.cj,官方 API 文档见 io_package_classes.md。

登录后查看全文
cangjie_runtime