class IO::Buffer

IO::Buffer is a efficient zero-copy buffer for input/output. There are typical use cases:

Interaction with string and file memory is performed by efficient low-level C mechanisms like memcpy.

The class is meant to be an utility for implementing more high-level mechanisms like Fiber::Scheduler#io_read and Fiber::Scheduler#io_write and parsing binary protocols.

Examples of Usage

Empty buffer:

buffer = IO::Buffer.new(8)  # create empty 8-byte buffer
# =>
# #<IO::Buffer 0x0000555f5d1a5c50+8 INTERNAL>
# ...
buffer
# =>
# <IO::Buffer 0x0000555f5d156ab0+8 INTERNAL>
# 0x00000000  00 00 00 00 00 00 00 00
buffer.set_string('test', 2) # put there bytes of the "test" string, starting from offset 2
# => 4
buffer.get_string  # get the result
# => "\x00\x00test\x00\x00"

Buffer from string:

string = 'data'
IO::Buffer.for(string) do |buffer|
  buffer
  # =>
  # #<IO::Buffer 0x00007f3f02be9b18+4 SLICE>
  # 0x00000000  64 61 74 61                                     data

  buffer.get_string(2)  # read content starting from offset 2
  # => "ta"
  buffer.set_string('---', 1) # write content, starting from offset 1
  # => 3
  buffer
  # =>
  # #<IO::Buffer 0x00007f3f02be9b18+4 SLICE>
  # 0x00000000  64 2d 2d 2d                                     d---
  string  # original string changed, too
  # => "d---"
end

Buffer from file:

File.write('test.txt', 'test data')
# => 9
buffer = IO::Buffer.map(File.open('test.txt'), nil, 0, IO::Buffer::READONLY)
# =>
# #<IO::Buffer 0x00007f3f0768c000+9 EXTERNAL MAPPED FILE SHARED READONLY>
# ...
buffer.get_string(5, 2) # read 2 bytes, starting from offset 5
# => "da"
buffer.set_string('---', 1) # attempt to write
# in `set_string': Buffer is not writable! (IO::Buffer::AccessError)

# To create writable file-mapped buffer
# Open file for read-write, pass size, offset, and flags=0
buffer = IO::Buffer.map(File.open('test.txt', 'r+'), 9, 0, 0)
buffer.set_string('---', 1)
# => 3 -- bytes written
File.read('test.txt')
# => "t--- data"

<strong>The class is experimental and the interface is subject to change, this is especially true of file mappings which may be removed entirely in the future.</strong>

Constants

BIG_ENDIAN

Refers to big endian byte order, where the most significant byte is stored first. See get_value for more details.

DEFAULT_SIZE

The default buffer size, typically a (small) multiple of the PAGE_SIZE. Can be explicitly specified by setting the RUBY_IO_BUFFER_DEFAULT_SIZE environment variable.

EXTERNAL

Indicates that the memory in the buffer is owned by someone else. See

external? for more details.

HOST_ENDIAN

Refers to the byte order of the host machine. See get_value for more details.

INTERNAL

Indicates that the memory in the buffer is owned by the buffer. See internal? for more details.

LITTLE_ENDIAN

Refers to little endian byte order, where the least significant byte is stored first. See get_value for more details.

LOCKED

Indicates that the memory in the buffer is locked and cannot be resized or freed. See locked? and locked for more details.

MAPPED

Indicates that the memory in the buffer is mapped by the operating system. See

mapped? for more details.

NETWORK_ENDIAN

Refers to network byte order, which is the same as big endian. See get_value for more details.

PAGE_SIZE

The operating system page size. Used for efficient page-aligned memory allocations.

PRIVATE

Indicates that the memory in the buffer is mapped privately and changes won’t be replicated to the underlying file. See #private? for more details.

READONLY

Indicates that the memory in the buffer is read only, and attempts to modify it will fail. See readonly? for more details.