JezK
Edit File: buffer.rbs
%a{annotate:rdoc:skip} class IO # <!-- rdoc-file=io_buffer.c --> # IO::Buffer is a low-level efficient buffer for input/output. There are three # ways of using buffer: # # * Create an empty buffer with ::new, fill it with data using #copy or # #set_value, #set_string, get data with #get_string; # * Create a buffer mapped to some string with ::for, then it could be used # both for reading with #get_string or #get_value, and writing (writing will # change the source string, too); # * Create a buffer mapped to some file with ::map, then it could be used for # reading and writing the underlying file. # # # 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::SchedulerInterface#io_read and # Fiber::SchedulerInterface#io_write. # # **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' # buffer = IO::Buffer.for(str) # # => # # #<IO::Buffer 0x00007f3f02be9b18+4 SLICE> # # ... # 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---" # # Buffer from file: # # File.write('test.txt', 'test data') # # => 9 # buffer = IO::Buffer.map(File.open('test.txt')) # # => # # #<IO::Buffer 0x00007f3f0768c000+9 MAPPED IMMUTABLE> # # ... # 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" # # **The class is experimental and the interface is subject to change.** # class Buffer include Comparable # <!-- # rdoc-file=io_buffer.c # - IO::Buffer.for(string) -> io_buffer # --> # Creates a IO::Buffer from the given string's memory. The buffer remains # associated with the string, and writing to a buffer will update the string's # contents. # # Until #free is invoked on the buffer, either explicitly or via the garbage # collector, the source string will be locked and cannot be modified. # # If the string is frozen, it will create a read-only buffer which cannot be # modified. # # string = 'test' # buffer = IO::Buffer.for(str) # buffer.external? #=> true # # buffer.get_string(0, 1) # # => "t" # string # # => "best" # # buffer.resize(100) # # in `resize': Cannot resize external buffer! (IO::Buffer::AccessError) # def self.for: (String) -> Buffer # <!-- # rdoc-file=io_buffer.c # - IO::Buffer.map(file, [size, [offset, [flags]]]) -> io_buffer # --> # Create an IO::Buffer for reading from `file` by memory-mapping the file. # `file_io` should be a `File` instance, opened for reading. # # Optional `size` and `offset` of mapping can be specified. # # By default, the buffer would be immutable (read only); to create a writable # mapping, you need to open a file in read-write mode, and explicitly pass # `flags` argument without IO::Buffer::IMMUTABLE. # # File.write('test.txt', 'test') # # buffer = IO::Buffer.map(File.open('test.txt'), nil, 0, IO::Buffer::READONLY) # # => #<IO::Buffer 0x00000001014a0000+4 MAPPED READONLY> # # buffer.readonly? # => true # # buffer.get_string # # => "test" # # buffer.set_string('b', 0) # # `set_string': Buffer is not writable! (IO::Buffer::AccessError) # # # create read/write mapping: length 4 bytes, offset 0, flags 0 # buffer = IO::Buffer.map(File.open('test.txt', 'r+'), 4, 0) # buffer.set_string('b', 0) # # => 1 # # # Check it # File.read('test.txt') # # => "best" # # Note that some operating systems may not have cache coherency between mapped # buffers and file reads. # def self.map: (File file, ?Integer? size, ?Integer offset, ?Integer flags) -> Buffer public # <!-- # rdoc-file=io_buffer.c # - <=>(other) -> true or false # --> # Buffers are compared by size and exact contents of the memory they are # referencing using `memcmp`. # def <=>: (Buffer) -> Integer # <!-- # rdoc-file=io_buffer.c # - clear(value = 0, [offset, [length]]) -> self # --> # Fill buffer with `value`, starting with `offset` and going for `length` bytes. # # buffer = IO::Buffer.for('test') # # => # # <IO::Buffer 0x00007fca40087c38+4 SLICE> # # 0x00000000 74 65 73 74 test # # buffer.clear # # => # # <IO::Buffer 0x00007fca40087c38+4 SLICE> # # 0x00000000 00 00 00 00 .... # # buf.clear(1) # fill with 1 # # => # # <IO::Buffer 0x00007fca40087c38+4 SLICE> # # 0x00000000 01 01 01 01 .... # # buffer.clear(2, 1, 2) # fill with 2, starting from offset 1, for 2 bytes # # => # # <IO::Buffer 0x00007fca40087c38+4 SLICE> # # 0x00000000 01 02 02 01 .... # # buffer.clear(2, 1) # fill with 2, starting from offset 1 # # => # # <IO::Buffer 0x00007fca40087c38+4 SLICE> # # 0x00000000 01 02 02 02 .... # def clear: (?Integer value, ?Integer offset, ?Integer length) -> self # <!-- # rdoc-file=io_buffer.c # - copy(source, [offset, [length, [source_offset]]]) -> size # --> # Efficiently copy data from a source IO::Buffer into the buffer, at `offset` # using `memcpy`. For copying String instances, see #set_string. # # buffer = IO::Buffer.new(32) # # => # # #<IO::Buffer 0x0000555f5ca22520+32 INTERNAL> # # 0x00000000 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ # # 0x00000010 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ * # # buffer.copy(IO::Buffer.for("test"), 8) # # => 4 -- size of data copied # buffer # # => # # #<IO::Buffer 0x0000555f5cf8fe40+32 INTERNAL> # # 0x00000000 00 00 00 00 00 00 00 00 74 65 73 74 00 00 00 00 ........test.... # # 0x00000010 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ * # # #copy can be used to put data into strings associated with buffer: # # string= "data: " # # => "data: " # buffer = IO::Buffer.for(str) # buffer.copy(IO::Buffer.for("test"), 5) # # => 4 # string # # => "data:test" # # Attempt to copy into a read-only buffer will fail: # # File.write('test.txt', 'test') # buffer = IO::Buffer.map(File.open('test.txt'), nil, 0, IO::Buffer::READONLY) # buffer.copy(IO::Buffer.for("test"), 8) # # in `copy': Buffer is not writable! (IO::Buffer::AccessError) # # See ::map for details of creation of mutable file mappings, this will work: # # buffer = IO::Buffer.map(File.open('test.txt', 'r+')) # buffer.copy("boom", 0) # # => 4 # File.read('test.txt') # # => "boom" # # Attempt to copy the data which will need place outside of buffer's bounds will # fail: # # buffer = IO::Buffer.new(2) # buffer.copy('test', 0) # # in `copy': Specified offset+length exceeds source size! (ArgumentError) # def copy: (Buffer source, ?Integer offset, ?Integer length, ?Integer source_offset) -> Integer # <!-- # rdoc-file=io_buffer.c # - external? -> true or false # --> # If the buffer is _external_, meaning it references from memory which is not # allocated or mapped by the buffer itself. # # A buffer created using ::for has an external reference to the string's # memory. # # External buffer can't be resized. # def empty?: () -> bool # <!-- # rdoc-file=io_buffer.c # - external?() # --> # def external?: () -> bool # <!-- # rdoc-file=io_buffer.c # - free -> self # --> # If the buffer references memory, release it back to the operating system. # * for a *mapped* buffer (e.g. from file): unmap. # * for a buffer created from scratch: free memory. # * for a buffer created from string: undo the association. # # # After the buffer is freed, no further operations can't be performed on it. # # buffer = IO::Buffer.for('test') # buffer.free # # => #<IO::Buffer 0x0000000000000000+0 NULL> # # buffer.get_value(:U8, 0) # # in `get_value': The buffer is not allocated! (IO::Buffer::AllocationError) # # buffer.get_string # # in `get_string': The buffer is not allocated! (IO::Buffer::AllocationError) # # buffer.null? # # => true # # You can resize a freed buffer to re-allocate it. # def free: () -> self # <!-- # rdoc-file=io_buffer.c # - get_string([offset, [length, [encoding]]]) -> string # --> # Read a chunk or all of the buffer into a string, in the specified `encoding`. # If no encoding is provided `Encoding::BINARY` is used. # # buffer = IO::Buffer.for('test') # buffer.get_string # # => "test" # buffer.get_string(2) # # => "st" # buffer.get_string(2, 1) # # => "s" # def get_string: (?Integer offset, ?Integer length, ?Encoding encoding) -> String # <!-- # rdoc-file=io_buffer.c # - get_value(type, offset) -> numeric # --> # Read from buffer a value of `type` at `offset`. `type` should be one of # symbols: # # * `:U8`: unsigned integer, 1 byte # * `:S8`: signed integer, 1 byte # * `:u16`: unsigned integer, 2 bytes, little-endian # * `:U16`: unsigned integer, 2 bytes, big-endian # * `:s16`: signed integer, 2 bytes, little-endian # * `:S16`: signed integer, 2 bytes, big-endian # * `:u32`: unsigned integer, 4 bytes, little-endian # * `:U32`: unsigned integer, 4 bytes, big-endian # * `:s32`: signed integer, 4 bytes, little-endian # * `:S32`: signed integer, 4 bytes, big-endian # * `:u64`: unsigned integer, 8 bytes, little-endian # * `:U64`: unsigned integer, 8 bytes, big-endian # * `:s64`: signed integer, 8 bytes, little-endian # * `:S64`: signed integer, 8 bytes, big-endian # * `:f32`: float, 4 bytes, little-endian # * `:F32`: float, 4 bytes, big-endian # * `:f64`: double, 8 bytes, little-endian # * `:F64`: double, 8 bytes, big-endian # # # Example: # # string = [1.5].pack('f') # # => "\x00\x00\xC0?" # IO::Buffer.for(string).get_value(:f32, 0) # # => 1.5 # def get_value: (int_get_type, Integer offset) -> Integer | (float_get_type, Integer offset) -> Float type int_get_type = :U8 | :S8 | :u16 | :U16 | :s16 | :S16 | :u32 | :U32 | :s32 | :S32 | :u64 | :U64 | :s64 | :S64 type float_get_type = :f32 | :F32 | :f64 | :F64 # <!-- # rdoc-file=io_buffer.c # - hexdump() # --> # def hexdump: () -> String # <!-- # rdoc-file=io_buffer.c # - inspect() # --> # def inspect: () -> String # <!-- # rdoc-file=io_buffer.c # - internal? -> true or false # --> # If the buffer is *internal*, meaning it references memory allocated by the # buffer itself. # # An internal buffer is not associated with any external memory (e.g. string) or # file mapping. # # Internal buffers are created using ::new and is the default when the requested # size is less than the IO::Buffer::PAGE_SIZE and it was not requested to be # mapped on creation. # # Internal buffers can be resized, and such an operation will typically # invalidate all slices, but not always. # def internal?: () -> bool # <!-- # rdoc-file=io_buffer.c # - locked { ... } # --> # Allows to process a buffer in exclusive way, for concurrency-safety. While the # block is performed, the buffer is considered locked, and no other code can # enter the lock. Also, locked buffer can't be changed with #resize or #free. # # buffer = IO::Buffer.new(4) # buffer.locked? #=> false # # Fiber.schedule do # buffer.locked do # buffer.write(io) # theoretical system call interface # end # end # # Fiber.schedule do # # in `locked': Buffer already locked! (IO::Buffer::LockedError) # buffer.locked do # buffer.set_string(...) # end # end # # The following operations acquire a lock: #resize, #free. # # Locking is not thread safe. It is designed as a safety net around non-blocking # system calls. You can only share a buffer between threads with appropriate # synchronisation techniques. # def locked: [A] () { (IO::Buffer) -> A } -> A # <!-- # rdoc-file=io_buffer.c # - locked? -> true or false # --> # If the buffer is *locked*, meaning it is inside #locked block execution. # Locked buffer can't be resized or freed, and another lock can't be acquired on # it. # # Locking is not thread safe, but is a semantic used to ensure buffers don't # move while being used by a system call. # # buffer.locked do # buffer.write(io) # theoretical system call interface # end # def locked?: () -> bool # <!-- # rdoc-file=io_buffer.c # - mapped? -> true or false # --> # If the buffer is *mapped*, meaning it references memory mapped by the buffer. # # Mapped buffers are either anonymous, if created by ::new with the # IO::Buffer::MAPPED flag or if the size was at least IO::Buffer::PAGE_SIZE, or # backed by a file if created with ::map. # # Mapped buffers can usually be resized, and such an operation will typically # invalidate all slices, but not always. # def mapped?: () -> bool # <!-- # rdoc-file=io_buffer.c # - null? -> true or false # --> # If the buffer was freed with #free or was never allocated in the first place. # def null?: () -> bool # <!-- # rdoc-file=io_buffer.c # - pread(p1, p2, p3) # --> # def pread: (untyped, untyped, untyped) -> untyped # <!-- # rdoc-file=io_buffer.c # - pwrite(p1, p2, p3) # --> # def pwrite: (untyped, untyped, untyped) -> untyped # <!-- # rdoc-file=io_buffer.c # - read(p1, p2) # --> # def read: (untyped, untyped) -> untyped # <!-- # rdoc-file=io_buffer.c # - readonly?() # --> # def readonly?: () -> bool # <!-- # rdoc-file=io_buffer.c # - resize(new_size) -> self # --> # Resizes a buffer to a `new_size` bytes, preserving its content. Depending on # the old and new size, the memory area associated with the buffer might be # either extended, or rellocated at different address with content being copied. # # buffer = IO::Buffer.new(4) # buffer.set_string("test", 0) # buffer.resize(8) # resize to 8 bytes # # => # # #<IO::Buffer 0x0000555f5d1a1630+8 INTERNAL> # # 0x00000000 74 65 73 74 00 00 00 00 test.... # # External buffer (created with ::for), and locked buffer can not be resized. # def resize: (Integer) -> self # <!-- # rdoc-file=io_buffer.c # - set_string(*args) # --> # def set_string: (*untyped) -> untyped # <!-- # rdoc-file=io_buffer.c # - set_value(type, offset, value) -> offset # --> # Write to a buffer a `value` of `type` at `offset`. `type` should be one of # symbols described in #get_value. # # buffer = IO::Buffer.new(8) # # => # # #<IO::Buffer 0x0000555f5c9a2d50+8 INTERNAL> # # 0x00000000 00 00 00 00 00 00 00 00 # buffer.set_value(:U8, 1, 111) # # => 1 # buffer # # => # # #<IO::Buffer 0x0000555f5c9a2d50+8 INTERNAL> # # 0x00000000 00 6f 00 00 00 00 00 00 .o...... # # Note that if the `type` is integer and `value` is Float, the implicit # truncation is performed: # # buffer = IO::Buffer.new(8) # buffer.set_value(:U32, 0, 2.5) # buffer # # => # # #<IO::Buffer 0x0000555f5c9a2d50+8 INTERNAL> # # 0x00000000 00 00 00 02 00 00 00 00 # # ^^ the same as if we'd pass just integer 2 # def set_value: (int_get_type | float_get_type, Integer offset, Float | Integer value) -> Integer # <!-- # rdoc-file=io_buffer.c # - size -> integer # --> # Returns the size of the buffer that was explicitly set (on creation with ::new # or on #resize), or deduced on buffer's creation from string or file. # def size: () -> Integer # <!-- # rdoc-file=io_buffer.c # - slice(offset, length) -> io_buffer # --> # Produce another IO::Buffer which is a slice (or view into) the current one # starting at `offset` bytes and going for `length` bytes. # # The slicing happens without copying of memory, and the slice keeps being # associated with the original buffer's source (string, or file), if any. # # Raises RuntimeError if the <tt>offset+length<tt> is out of the current # buffer's bounds. # # string = 'test' # buffer = IO::Buffer.for(string) # # slice = buffer.slice(1, 2) # # => # # #<IO::Buffer 0x00007fc3d34ebc49+2 SLICE> # # 0x00000000 65 73 es # # # Put "o" into 0s position of the slice # slice.set_string('o', 0) # slice # # => # # #<IO::Buffer 0x00007fc3d34ebc49+2 SLICE> # # 0x00000000 6f 73 os # # # it is also visible at position 1 of the original buffer # buffer # # => # # #<IO::Buffer 0x00007fc3d31e2d80+4 SLICE> # # 0x00000000 74 6f 73 74 tost # # # ...and original string # string # # => tost # def slice: (Integer offset, Integer length) -> Buffer # <!-- # rdoc-file=io_buffer.c # - to_s -> string # --> # Short representation of the buffer. It includes the address, size and symbolic # flags. This format is subject to change. # # puts IO::Buffer.new(4) # uses to_s internally # # #<IO::Buffer 0x000055769f41b1a0+4 INTERNAL> # def to_s: () -> String # <!-- # rdoc-file=io_buffer.c # - transfer -> new_io_buffer # --> # Transfers ownership to a new buffer, deallocating the current one. # # buffer = IO::Buffer.new('test') # other = buffer.transfer # other # # => # # #<IO::Buffer 0x00007f136a15f7b0+4 SLICE> # # 0x00000000 74 65 73 74 test # buffer # # => # # #<IO::Buffer 0x0000000000000000+0 NULL> # buffer.null? # # => true # def transfer: () -> Buffer # <!-- # rdoc-file=io_buffer.c # - valid? -> true or false # --> # Returns whether the buffer data is accessible. # # A buffer becomes invalid if it is a slice of another buffer which has been # freed. # def valid?: () -> bool # <!-- # rdoc-file=io_buffer.c # - write(p1, p2) # --> # def write: (untyped, untyped) -> untyped private # <!-- # rdoc-file=io_buffer.c # - IO::Buffer.new([size = DEFAULT_SIZE, [flags = 0]]) -> io_buffer # --> # Create a new zero-filled IO::Buffer of `size` bytes. By default, the buffer # will be *internal*: directly allocated chunk of the memory. But if the # requested `size` is more than OS-specific IO::Bufer::PAGE_SIZE, the buffer # would be allocated using the virtual memory mechanism (anonymous `mmap` on # Unix, `VirtualAlloc` on Windows). The behavior can be forced by passing # IO::Buffer::MAPPED as a second parameter. # # Examples # # buffer = IO::Buffer.new(4) # # => # # #<IO::Buffer 0x000055b34497ea10+4 INTERNAL> # # 0x00000000 00 00 00 00 .... # # buffer.get_string(0, 1) # => "\x00" # # buffer.set_string("test") # buffer # # => # # #<IO::Buffer 0x000055b34497ea10+4 INTERNAL> # # 0x00000000 74 65 73 74 test # def initialize: (?Integer size, ?Integer flags) -> void BIG_ENDIAN: Integer DEFAULT_SIZE: Integer EXTERNAL: Integer HOST_ENDIAN: Integer INTERNAL: Integer LITTLE_ENDIAN: Integer LOCKED: Integer MAPPED: Integer NETWORK_ENDIAN: Integer PAGE_SIZE: Integer PRIVATE: Integer READONLY: Integer end end