Ruby 3.2引入的IO::Buffer类为低层I/O操作提供了一块可显式控制的连续内存区域。它不像字符串那样自动扩容，也不像数组那样管理对象引用，而是一个包装了底层字节数组的简单封装。每个IO::Buffer实例内部维护着两个关键的长度概念：一个是从分配开始就固定下来的capacity，另一个是随着读写而动态变化的size。对这两个属性的误解，是多发数据、丢失尾部字节，甚至读取到垃圾数据的直接原因。下面我们从内存模型出发，完整拆解这对属性的工作机制。
IO::Buffer的内存基础与创建方式
IO::Buffer可以看作一个固定大小的字节容器，底层通常使用C语言中的malloc或操作系统提供的虚拟内存分配函数。创建时最常见的做法是调用IO::Buffer.new(size)或IO::Buffer.new(string)。当传入一个整数时，Ruby会分配一块指定字节数的内存，此时capacity和size都等于该值——内存被清零，缓冲区处于“已初始化”状态。但如果使用IO::Buffer.for(string)或从字符串转换，情形会稍有不同。
来看几个创建操作的对比：
# 创建指定容量的空缓冲区，自动清零 buf = IO::Buffer.new(1024) buf.size # => 1024 buf.capacity # => 1024 # 从字符串创建，capacity与string.bytesize一致 str = "hello" buf2 = IO::Buffer.for(str) buf2.size # => 5 buf2.capacity # => 5
IO::Buffer.new不接收字符串参数，它只接受整数（字节数）或别的IO::Buffer实例。上面提到size等于capacity的原因是，new会把整个缓冲区看作有效数据，即默认内容已填充。但随后我们可能会用set_string、set_value等方法改变部分区域，这时size就可能小于capacity了。这种设计的微妙之处在于：Ruby并不会替你追踪“实际使用长度”，开发者必须手动通过resize或set_string等方法调整size。
size与capacity的行为详解
capacity是只读属性，返回缓冲区分配的总字节数。一经创建，capacity就无法改变；如果想让容量变大，必须创建新的IO::Buffer再把数据复制过去。这一点类似于C语言中的malloc分配后无法原地扩展，除非使用realloc——而Ruby的IO::Buffer并没有暴露这样的接口。
size则不同，它既可以读取，也可以通过resize(new_size)显式设置，还会受到部分写入操作的影响。size的含义是“当前缓冲区中有效数据的长度”，在执行读取或网络发送时，默认只会操作前size个字节。例如，buf.send(io)只发送size字节，而不是capacity字节。同样，buf.get_string也返回长度为size的字符串。如果size小于capacity，那么超出size的部分就是未定义内存——它可能全是零，也可能是上次使用后残留的数据。
下面通过一个实验来观察size和capacity的联动：
buf = IO::Buffer.new(64) # capacity=64, size=64
buf.resize(16) # size变为16，capacity不变
buf.size # => 16
buf.capacity # => 64
# 此时调用 get_string 只会拿到前16字节
str = buf.get_string
str.bytesize # => 16
# 也可以用 set_string 重新设置内容并自动调整size
buf.set_string("Hi!", 0) # 从偏移量0写入 "Hi!"
buf.size # => 3 (set_string 会自动把size调整为写入后的末尾位置)
注意set_string的行为：它写入字符串后，会将size更新为写入起始偏移量 + 字符串字节数，但不会改变capacity。这就实现了“缓冲区容量很大，但有效数据很短”的典型场景。反过来，如果尝试resize一个大于capacity的新尺寸，Ruby会抛出RangeError；同样地，set_string写入时超出capacity边界也会引发异常。因此，size这一属性就像一把游标尺，标定着缓冲区中“有用部分”的终点。
为什么需要区分size和capacity：实际应用场景
在网络编程中，区分容量和有效长度至关重要。假设你使用IO::Buffer来接收socket数据。通常会先创建一个较大容量的缓冲区，然后调用buf.read(io, length)从IO对象中填充数据。这个read方法返回实际读取的字节数，并自动调整buf.size为读取后的有效长度。如果每次发送响应时直接使用send，它只会发送size指示的部分，从而避免把上次请求残留的脏数据发出去。
再看一个文件读取的例子。Ruby标准库支持将IO::Buffer当作底层缓存：
File.open("data.bin", "rb") do |file|
buf = IO::Buffer.new(4096) # 分配4KB缓冲区
# file.read 会向buf填充数据，并返回读取的字节数
nbytes = file.read(0, buf) # 偏移0作为起始写入点
# nbytes 可能小于 capacity
if nbytes > 0
buf.resize(nbytes) # 确保size与实际读取量一致
# 现在处理前 size 字节...
end
end
在上面的代码里，file.read传入IO::Buffer后，并不自动更新size——它只负责往内存里拷贝数据。所以我们需要显式用resize(nbytes)把size修正为实际读取量。如果不做这一步，接下来的操作可能会错误地假定缓冲区里4096字节全是有效数据，导致文件末尾混入多余的零字节。
还有一个重要场景是实现环形缓冲区或协议解析器。当我们从一块大缓冲区中切出若干数据包时，可以用buf.slice获取共享底层内存的视图。每个切片有独立的size和offset，capacity依然是原来大缓冲区的总容量。这样既能保证零拷贝，又能通过各自切片的size准确描述消息边界。如果混淆了size和capacity，就可能跨过消息边界读写下一条消息的内存区域，引发难以追踪的数据损坏。
与String等其他类的大小概念对比
熟悉Ruby字符串的开发者容易把IO::Buffer的size与String的bytesize直接等效，但二者在内存模型上差异明显。字符串是自动扩容的，它的bytesize就是当前内容的长度，不存在capacity概念（虽然底层有容量预留，但Ruby并不向用户暴露）。而IO::Buffer强制要求开发者显式管理size，这让它更接近C语言中的数组，但也需要使用者保持警戒。
另外，IO::Buffer的size与length是同义词，返回的都是有效数据长度。但切记不要把buf.length当作容量来用。曾经有开源项目因为误用length作为循环上限写入数据，结果造成缓冲区溢出，这就是混淆的代价。在每次调用set_string、set_value或者通过IO对象读取之后，都应当检查size的值，确认它是否符合预期。同时，可以用buf.inspect快速调试，输出内容会同时显示size和capacity，例如：#<IO::Buffer 0x00007f... 16/64 bytes>，其中前者为size，后者为capacity。
总结来看，IO::Buffer为Ruby打开了一扇高效二进制操作的大门，但它把内存管理的部分职责交给了开发者。size描述实际数据边界，capacity描述物理分配边界——二者的分离是性能与安全之间权衡的结果。在编写涉及网络协议、文件映射或自定义编解码的代码时，始终问自己“我现在操作的有效范围是多大”，并动手检查size与capacity的值，这将成为避免数据错误最直接有效的习惯。
RubyIO_Buffersize_capacity修改时间：2026-08-12 21:00:58