class RemiLib::MmappedFile

Overview

The MmappedFile class provides a convenient way to read from and write to files using mmap(). This is only supported on POSIX systems, and is not meant to be a complete interface to everything you can do with mmap().

Defined in:

remilib/mmappedfile.cr

Constructors

Class Method Summary

Instance Method Summary

Instance methods inherited from class IO

endBold : self endBold, endColor : self endColor, endConceal : self endConceal, endCrossedOut : self endCrossedOut, endEncircled : self endEncircled, endFaint : self endFaint, endFastBlink : self endFastBlink, endFraktur : self endFraktur, endFramed : self endFramed, endItalic : self endItalic, endOverlined : self endOverlined, endReverseVideo : self endReverseVideo, endSlowBlink : self endSlowBlink, endUnderline : self endUnderline, readBytes(count : Int) : Bytes readBytes, readFloat32 readFloat32, readFloat32BE readFloat32BE, readFloat64 readFloat64, readFloat64BE readFloat64BE, readInt128 readInt128, readInt128BE readInt128BE, readInt16 readInt16, readInt16BE readInt16BE, readInt24 readInt24, readInt24BE readInt24BE, readInt32 readInt32, readInt32BE readInt32BE, readInt64 readInt64, readInt64BE readInt64BE, readInt8 readInt8, readUInt128 readUInt128, readUInt128BE readUInt128BE, readUInt16 readUInt16, readUInt16BE readUInt16BE, readUInt32 readUInt32, readUInt32BE readUInt32BE, readUInt64 readUInt64, readUInt64BE readUInt64BE, readUInt8 readUInt8, startBold : self startBold, startColor(fg : RemiLib::Console::Color, bg : RemiLib::Console::Color = RemiLib::Console::Color::Default) : self startColor, startConceal : self startConceal, startCrossedOut : self startCrossedOut, startEncircled : self startEncircled, startFaint : self startFaint, startFastBlink : self startFastBlink, startFraktur : self startFraktur, startFramed : self startFramed, startItalic : self startItalic, startOverlined : self startOverlined, startReverseVideo : self startReverseVideo, startSlowBlink : self startSlowBlink, startUnderline : self startUnderline, withBold(&) withBold, withColor(fg : RemiLib::Console::Color, bg : RemiLib::Console::Color = RemiLib::Console::Color::Default, &) : self withColor, withConceal(&) withConceal, withCrossedOut(&) withCrossedOut, withEncircled(&) withEncircled, withExcursion(gotoHere, &)
withExcursion(&) withExcursion, withFaint(&) withFaint, withFastBlink(&) withFastBlink, withFraktur(&) withFraktur, withFramed(&) withFramed, withItalic(&) withItalic, withOverlined(&) withOverlined, withReverseVideo(&) withReverseVideo, withSlowBlink(&) withSlowBlink, withUnderline(&) withUnderline, writeFloat32(value : Float32) : self writeFloat32, writeFloat32BE(value : Float32) : self writeFloat32BE, writeFloat64(value : Float64) : self writeFloat64, writeFloat64BE(value : Float64) : self writeFloat64BE, writeInt128(value : Int128) : self writeInt128, writeInt128BE(value : Int128) : self writeInt128BE, writeInt16(value : Int16) : self writeInt16, writeInt16BE(value : Int16) : self writeInt16BE, writeInt24(data : Int32) writeInt24, writeInt24BE(data : Int32) writeInt24BE, writeInt32(value : Int32) : self writeInt32, writeInt32BE(value : Int32) : self writeInt32BE, writeInt64(value : Int64) : self writeInt64, writeInt64BE(value : Int64) : self writeInt64BE, writeInt8(value : Int8) : Nil writeInt8, writeUInt128(value : UInt128) : self writeUInt128, writeUInt128BE(value : UInt128) : self writeUInt128BE, writeUInt16(value : UInt16) : self writeUInt16, writeUInt16BE(value : UInt16) : self writeUInt16BE, writeUInt32(value : UInt32) : self writeUInt32, writeUInt32BE(value : UInt32) : self writeUInt32BE, writeUInt64(value : UInt64) : self writeUInt64, writeUInt64BE(value : UInt64) : self writeUInt64BE, writeUInt8(value : UInt8) : Nil writeUInt8

Class methods inherited from class IO

readBytes(io : IO, count : Int) : Bytes readBytes, readFloat32(io : IO) : Float32 readFloat32, readFloat32BE(io : IO) : Float32 readFloat32BE, readFloat64(io : IO) : Float64 readFloat64, readFloat64BE(io : IO) : Float64 readFloat64BE, readInt128(io : IO) : Int128 readInt128, readInt128BE(io : IO) : Int128 readInt128BE, readInt16(io : IO) : Int16 readInt16, readInt16BE(io : IO) : Int16 readInt16BE, readInt24(io : IO) : Int32 readInt24, readInt24BE(io : IO) : Int32 readInt24BE, readInt32(io : IO) : Int32 readInt32, readInt32BE(io : IO) : Int32 readInt32BE, readInt64(io : IO) : Int64 readInt64, readInt64BE(io : IO) : Int64 readInt64BE, readInt8(io : IO) : Int8 readInt8, readUInt128(io : IO) : UInt128 readUInt128, readUInt128BE(io : IO) : UInt128 readUInt128BE, readUInt16(io : IO) : UInt16 readUInt16, readUInt16BE(io : IO) : UInt16 readUInt16BE, readUInt32(io : IO) : UInt32 readUInt32, readUInt32BE(io : IO) : UInt32 readUInt32BE, readUInt64(io : IO) : UInt64 readUInt64, readUInt64BE(io : IO) : UInt64 readUInt64BE, readUInt8(io : IO) : UInt8 readUInt8, writeInt8(io : IO, value : Int8) : Nil writeInt8, writeUInt8(io : IO, value : UInt8) : Nil writeUInt8

Instance methods inherited from class Object

toRsconf(io : IO, *, indentSize : Int = 2, alwaysQuoteKeys : Bool = false, explicitRootObject : Bool = false, commaAfterValues : Bool = false, extraNewlineBetweenToplevelKeys : Bool = false) : Nil
toRsconf(*, indentSize : Int = 2, alwaysQuoteKeys : Bool = false, explicitRootObject : Bool = false, commaAfterValues : Bool = false, extraNewlineBetweenToplevelKeys : Bool = false) : String toRsconf

Class methods inherited from class Object

fromRsconf(toplevel : RemiLib::RSConf::RSValue)
fromRsconf(data : String | IO | Path) fromRsconf

Constructor Detail

def self.new(path : Path | String, size : Int, *, mode : Mode = Mode::Read, mapping : Mapping = Mapping::Private, syncMode : MsyncFlags = MsyncFlags::Async) #

Creates a new MmappedFile instance by mapping the file at path into the memory space.

If mode is Mode::Read, then the file must already exist.

If mode is Mode::ReadWrite, then the file is always overwritten if it exists and is recreated with the requested size. If it does not exist, it is created with the requested size.

In all cases, size must be at least 1.

When you are finished with the instance, you should call #close to unmap the file and release the resources. This can also happen during finalization.


[View source]

Class Method Detail

def self.open(path : Path | String, size : Int, *, mode : Mode = Mode::Read, mapping : Mapping = Mapping::Private, &) #

Creates a new MmappedFile instance by mapping the file at path into the memory spacem, then yields that instance and executes the block. The file must already exist.

Look at MmappedFile.new for the explanation of the other parameters.

This will automatically call #close at the end.


[View source]

Instance Method Detail

def close : Nil #

Unmaps the file from memory.


[View source]
def fd : Int64 #

The file descriptor this mapping was created from.


[View source]
def finalize #

[View source]
def getBytes(count : Int32, position : LibC::SizeT) : Bytes #

Gets count bytes from the given position, then returns a new Bytes slice containing those bytes. This does not change the internal position of the internal cursor (#pos).


[View source]
def getInt128(position : LibC::SizeT) : Int128 #

Returns an Int128 from the file at the given position. Raises an MmappedFileEofError if there are not enough bytes to read an Int128 at the given position. This does not change the internal position of the internal cursor (#pos).


[View source]
def getInt16(position : LibC::SizeT) : Int16 #

Returns an Int16 from the file at the given position. Raises an MmappedFileEofError if there are not enough bytes to read an Int16 at the given position. This does not change the internal position of the internal cursor (#pos).


[View source]
def getInt24(position : LibC::SizeT) : Int32 #

Gets three bytes from position and returns an Int32. MmappedFileEofError if there are not enough bytes to read a 24-bit integer at the given position. This does not change the internal position of the internal cursor (#pos).


[View source]
def getInt32(position : LibC::SizeT) : Int32 #

Returns an Int32 from the file at the given position. Raises an MmappedFileEofError if there are not enough bytes to read an Int32 at the given position. This does not change the internal position of the internal cursor (#pos).


[View source]
def getInt64(position : LibC::SizeT) : Int64 #

Returns an Int64 from the file at the given position. Raises an MmappedFileEofError if there are not enough bytes to read an Int64 at the given position. This does not change the internal position of the internal cursor (#pos).


[View source]
def getInt8(position : LibC::SizeT) : Int8 #

Returns an Int8 from the file at the given position. Raises an MmappedFileEofError if there are not enough bytes to read an Int8 at the given position. This does not change the internal position of the internal cursor (#pos).


[View source]
def getString(count : Int32, position : LibC::SizeT) : String #

Gets a String of count bytes long at the given position, then returns the new String. This does not change the internal position of the internal cursor (#pos).


[View source]
def getUInt128(position : LibC::SizeT) : UInt128 #

Returns a UInt128 from the file at the given position. Raises an MmappedFileEofError if there are not enough bytes to read a UInt128 at the given position. This does not change the internal position of the internal cursor (#pos).


[View source]
def getUInt16(position : LibC::SizeT) : UInt16 #

Returns a UInt16 from the file at the given position. Raises an MmappedFileEofError if there are not enough bytes to read a UInt16 at the given position. This does not change the internal position of the internal cursor (#pos).


[View source]
def getUInt24(position : LibC::SizeT) : UInt32 #

Gets three bytes from position and returns a UInt32. MmappedFileEofError if there are not enough bytes to read a 24-bit number at the given position. This does not change the internal position of the internal cursor (#pos).


[View source]
def getUInt32(position : LibC::SizeT) : UInt32 #

Returns a UInt32 from the file at the given position. Raises an MmappedFileEofError if there are not enough bytes to read a UInt32 at the given position. This does not change the internal position of the internal cursor (#pos).


[View source]
def getUInt64(position : LibC::SizeT) : UInt64 #

Returns a UInt64 from the file at the given position. Raises an MmappedFileEofError if there are not enough bytes to read a UInt64 at the given position. This does not change the internal position of the internal cursor (#pos).


[View source]
def getUInt8(position : LibC::SizeT) : UInt8 #

Returns a UInt8 from the file at the given position. Raises an MmappedFileEofError if there are not enough bytes to read a UInt8 at the given position. This does not change the internal position of the internal cursor (#pos).


[View source]
def len : LibC::SizeT #

Length of the file.


[View source]
def mapping : Mapping #

The Mapping this instance was created with.


[View source]
def mode : Mode #

The Mode this instance was opened with.


[View source]
def open? : Bool #

Returns true if this instance is open, or false otherwise.


[View source]
def pos : LibC::SizeT #

Current read position.


[View source]
def pos=(position : LibC::SizeT) : Nil #

[View source]
def pos=(value) #
Description copied from class IO

Sets the current position (in bytes) in this IO.

The IO class raises on this method, but some subclasses, notable IO::FileDescriptor and IO::Memory implement it.

File.write("testfile", "hello")

file = File.new("testfile")
file.pos = 3
file.gets_to_end # => "lo"

[View source]
def putBytes(data : Bytes, position : LibC::SizeT) : Nil #

Writes a Bytes slice to the file at the given position. If there is not enough space to write the value, then this raises a MmappedFileEofError. This does not change the internal position of the internal cursor (#pos).


[View source]
def putInt128(val : Int128, position : LibC::SizeT) : Nil #

Writes an Int128 to the file at the given position. If there is no space to write the value, then this raises a MmappedFileEofError. This does not change the internal position of the internal cursor (#pos).


[View source]
def putInt16(val : Int16, position : LibC::SizeT) : Nil #

Writes an Int16 to the file at the given position. If there is no space to write the value, then this raises a MmappedFileEofError. This does not change the internal position of the internal cursor (#pos).


[View source]
def putInt24(val : Int32, position : LibC::SizeT) : Nil #

Writes a 24-bit integer stored in a UInt32 to the file at the given position. If there is no space to write the value, then this raises a MmappedFileEofError. This does not change the internal position of the internal cursor (#pos).

If val does not contain a 24-bit integer, this raises an ArgumentError.


[View source]
def putInt32(val : Int32, position : LibC::SizeT) : Nil #

Writes an Int32 to the file at the given position. If there is no space to write the value, then this raises a MmappedFileEofError. This does not change the internal position of the internal cursor (#pos).


[View source]
def putInt64(val : Int64, position : LibC::SizeT) : Nil #

Writes an Int64 to the file at the given position. If there is no space to write the value, then this raises a MmappedFileEofError. This does not change the internal position of the internal cursor (#pos).


[View source]
def putInt8(val : Int8, position : LibC::SizeT) : Nil #

Writes an Int8 to the file at the given position. If there is no space to write the value, then this raises a MmappedFileEofError. This does not change the internal position of the internal cursor (#pos).


[View source]
def putString(str : String, position : LibC::SizeT) : Nil #

Writes a String as raw bytes to the file at the given position. If there is not enough space to write the value, then this raises a MmappedFileEofError. This does not change the internal position of the internal cursor (#pos).


[View source]
def putUInt128(val : UInt128, position : LibC::SizeT) : Nil #

Writes a UInt128 to the file at the given position. If there is no space to write the value, then this raises a MmappedFileEofError. This does not change the internal position of the internal cursor (#pos).


[View source]
def putUInt16(val : UInt16, position : LibC::SizeT) : Nil #

Writes a UInt16 to the file at the given position. If there is no space to write the value, then this raises a MmappedFileEofError. This does not change the internal position of the internal cursor (#pos).


[View source]
def putUInt24(val : UInt32, position : LibC::SizeT, littleEndian? : Bool = true) : Nil #

Writes a 24-bit integer stored in a UInt32 to the file at the given position. If there is no space to write the value, then this raises a MmappedFileEofError. This does not change the internal position of the internal cursor (#pos).

If val does not contain a 24-bit integer, this raises an ArgumentError.


[View source]
def putUInt32(val : UInt32, position : LibC::SizeT) : Nil #

Writes a UInt32 to the file at the given position. If there is no space to write the value, then this raises a MmappedFileEofError. This does not change the internal position of the internal cursor (#pos).


[View source]
def putUInt64(val : UInt64, position : LibC::SizeT) : Nil #

Writes a UInt64 to the file at the given position. If there is no space to write the value, then this raises a MmappedFileEofError. This does not change the internal position of the internal cursor (#pos).


[View source]
def putUInt8(val : UInt8, position : LibC::SizeT) : Nil #

Writes a UInt8 to the file at the given position. If there is no space to write the value, then this raises a MmappedFileEofError. This does not change the internal position of the internal cursor (#pos).


[View source]
def read(slice : Bytes) #

Reads at most slice.size bytes from this IO into slice. Returns the number of bytes read, which is 0 if and only if there is no more data to read (so checking for 0 is the way to detect end of file).

io = IO::Memory.new "hello"
slice = Bytes.new(4)
io.read(slice) # => 4
slice          # => Bytes[104, 101, 108, 108]
io.read(slice) # => 1
slice          # => Bytes[111, 101, 108, 108]
io.read(slice) # => 0

[View source]
def readBytes(count : Int32) : Bytes #

Reads count bytes, then returns a new Bytes slice containing those bytes.


[View source]
def readInt128 : Int128 #

Reads an Int128 from the file at the current position. Raises an MmappedFileEofError if there are not enough bytes to read an Int128.


[View source]
def readInt16 : Int16 #

Reads a Int16 from the file at the current position. Raises an MmappedFileEofError if there are not enough bytes to read a Int16.


[View source]
def readInt24 : Int32 #

Reads three bytes from the file at the current position and returns a 24-bit integer as an Int32. Raises an MmappedFileEofError if there are not enough bytes to read a 24-bit integer.


[View source]
def readInt32 : Int32 #

Reads an Int32 from the file at the current position. Raises an MmappedFileEofError if there are not enough bytes to read an Int32.


[View source]
def readInt64 : Int64 #

Reads an Int64 from the file at the current position. Raises an MmappedFileEofError if there are not enough bytes to read an Int64.


[View source]
def readInt8 : Int8 #

Reads a Int8 from the file at the current position. Raises an MmappedFileEofError if there are not enough bytes to read a Int8.


[View source]
def readString(count : Int32) : String #

Reads a String of count bytes long, then returns the new String.


[View source]
def readUInt128 : UInt128 #

Reads a UInt128 from the file at the current position. Raises an MmappedFileEofError if there are not enough bytes to read a UInt128.


[View source]
def readUInt16 : UInt16 #

Reads a UInt16 from the file at the current position. Raises an MmappedFileEofError if there are not enough bytes to read a UInt16.


[View source]
def readUInt24 : UInt32 #

Reads three bytes from the file at the current position and returns a 24-bit integer as a UInt32. Raises an MmappedFileEofError if there are not enough bytes to read a 24-bit unsigned integer.


[View source]
def readUInt32 : UInt32 #

Reads a UInt32 from the file at the current position. Raises an MmappedFileEofError if there are not enough bytes to read a UInt32.


[View source]
def readUInt64 : UInt64 #

Reads a UInt64 from the file at the current position. Raises an MmappedFileEofError if there are not enough bytes to read a UInt64.


[View source]
def readUInt8 : UInt8 #

Reads a UInt8 from the file at the current position. Raises an MmappedFileEofError if there are not enough bytes to read a UInt8.


[View source]
def rewind : Nil #
Description copied from class IO

Rewinds this IO. By default this method raises, but including types may implement it.


[View source]
def sync : Nil #

[View source]
def syncMode : MsyncFlags #

Specifies the behavior when #sync or #close are called and this instance is writeable. If the instance isn't writeable, this is ignored.


[View source]
def syncMode=(syncMode : MsyncFlags) #

Specifies the behavior when #sync or #close are called and this instance is writeable. If the instance isn't writeable, this is ignored.


[View source]
def write(slice : Bytes) : Nil #

Writes the contents of slice into this IO.

io = IO::Memory.new
slice = Bytes.new(4) { |i| ('a'.ord + i).to_u8 }
io.write(slice)
io.to_s # => "abcd"

[View source]
def writeBytes(data : Bytes) : Nil #

Writes a Bytes slice to the file at the current position. If there is not enough space to write the value, then this raises a MmappedFileEofError.


[View source]
def writeInt128(val : Int128) : Nil #

Writes an Int128 to the file at the current position. If there is no space to write the value, then this raises a MmappedFileEofError.


[View source]
def writeInt16(val : Int16) : Nil #

Writes an Int16 to the file at the current position. If there is no space to write the value, then this raises a MmappedFileEofError.


[View source]
def writeInt24(val : Int32) : Nil #

Writes a 24-bit integer stored in an Int32 to the file at the current position. If there is no space to write the value, then this raises a MmappedFileEofError.


[View source]
def writeInt32(val : Int32) : Nil #

Writes an Int32 to the file at the current position. If there is no space to write the value, then this raises a MmappedFileEofError.


[View source]
def writeInt64(val : Int64) : Nil #

Writes an Int64 to the file at the current position. If there is no space to write the value, then this raises a MmappedFileEofError.


[View source]
def writeInt8(val : Int8) : Nil #

Writes an Int8 to the file at the current position. If there is no space to write the value, then this raises a MmappedFileEofError.


[View source]
def writeString(str : String) : Nil #

Writes a String as raw bytes to the file at the current position. If there is not enough space to write the value, then this raises a MmappedFileEofError.


[View source]
def writeUInt128(val : UInt128) : Nil #

Writes a UInt128 to the file at the current position. If there is no space to write the value, then this raises a MmappedFileEofError.


[View source]
def writeUInt16(val : UInt16) : Nil #

Writes a UInt16 to the file at the current position. If there is no space to write the value, then this raises a MmappedFileEofError.


[View source]
def writeUInt24(val : UInt32, littleEndian? : Bool = true) : Nil #

Writes a 24-bit integer stored in a UInt32 to the file at the current position. If there is no space to write the value, then this raises a MmappedFileEofError.

If val does not contain a 24-bit integer, this raises an ArgumentError.


[View source]
def writeUInt32(val : UInt32) : Nil #

Writes a UInt32 to the file at the current position. If there is no space to write the value, then this raises a MmappedFileEofError.


[View source]
def writeUInt64(val : UInt64) : Nil #

Writes a UInt64 to the file at the current position. If there is no space to write the value, then this raises a MmappedFileEofError.


[View source]
def writeUInt8(val : UInt8) : Nil #

Writes a UInt8 to the file at the current position. If there is no space to write the value, then this raises a MmappedFileEofError.


[View source]