Documentation
¶
Overview ¶
Package mmap exposes the Unix mmap calls with helper utilities. mmap provides a memory caching scheme for files on disk that may save memory when shared between processes or save memory when doing random access. You can read more about mmap in the linux man pages. This package currently only works for Unix based systems.
The most basic type to use is a Map object. It can be created as follows:
// Create a file to be mmapped or in open a file with os.Open().
f, err := ioutil.TempFile("", "")
if err != nil {
panic(err)
}
// Because we are creating a new file, give it some content as you can't mmap an empty file.
_, err = io.WriteString(f, "hello world")
if err != nil {
panic(err)
}
// Create an mmapped file that can be read, written, and shared between processes.
m, err := NewMap(f, Prot(Read), Prot(Write), Flag(Shared))
if err != nil {
// Do something
}
defer m.Close()
// You now have access to all the methods in io.Reader/io.Writer/io.Seeker()/io.ReaderAt/io.Closer.
p := make([]byte, 5)
_, err := m.Read(p)
if err != nil {
// Do something
}
// You can access the Map's []byte directly. However, there is no goroutine mutexes or other protections
// that prevent faults (not panic, good old C like faults).
fmt.Println(m.Bytes()[5:])
Also included is a String type that is useful if you need to access the data as a text file .
m, err := NewString(f, Prot(Read), Prot(Write), Flag(Shared))
if err != nil {
// Do something
}
defer m.Close()
// Read the next line (including the carriage return)
s, err := m.ReadLine()
if err != nil {
// Do something
}
// You can also seek to a position and write a new line
_, err := m.Seek(0, 0)
if err != nil {
// Do something
}
if err := m.WriteString("yo\n"); err != nil {
// Do something
}
In addition it should be noted that because this package exports various types that satisfy io.Read/Writer, you can use the bufio pacakge on some of the types.
Index ¶
Constants ¶
const ( // Read indicates the data can be read. Read = syscall.PROT_READ // Write indicates the data can be written. Write = syscall.PROT_WRITE // Exec indicates the data can be executed. Exec = syscall.PROT_EXEC )
Values that can be used for the Prot() arg to New().
const ( Shared = syscall.MAP_SHARED // Private indicates changes to the data is for the current process only and will not change the underlying object. // Private and Shared cannot be used together. Private = syscall.MAP_PRIVATE )
Values that can be used with the Flag() option to New().
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Map ¶
type Map interface {
io.ReadWriteCloser
io.Seeker
io.ReaderAt
// Bytes returns the bytes in the map. Modifying this slice modifies the inmemory representation.
// This data should only be used as read-only and instead you should use the Write() method that offers
// better protections. Write() will protect you from faults like writing to a read-only mmap or other
// errors that cannot be caught via defer/recover. It also protects you from writing data that cannot
// be sync'd to disk because the underlying file does not have the capactiy (regardless to what you
// set the mmap length to).
Bytes() []byte
// Len returns the size of the file, which can be larger than the memory mapped area.
Len() int
// Pos returns the current index of the file pointer.
Pos() int
// Lock prevents the physical memory from being swapped out to disk.
Lock() error
// Unlock allows the physical memory to be swapped out to disk. If the memory is not locked, nothing happens.
Unlock() error
}
Map represents a mapped file in memory and implements the io.ReadWriteCloser/io.Seeker/io.ReaderAt interfaces. Note that any change to the []byte returned by various methods is changing the underlying memory representation for all users of this mmap data. For safety reasons or when using concurrent access, use the built in methods to read and write the data
type Option ¶
type Option func(m *mmap)
Option is an option to the New() constructor.
func Anon ¶
func Anon() Option
Anon indicates that the memory should not be backed by a file. In this case, the fd and length arguments are ignored by New().
func Length ¶
Length sets the length in bytes of the file from the offset that we are mapping to memory. Unless Offset() is called, this is from the beginning of the file. You can use this to provide extra room for the file to grow.
type String ¶
type String interface {
// Embedded Map gives access to all Map methods and satisfies io.ReadWriteCloser/io.Seeker/io.ReaderAt.
Map
// Readline returns each line of text, stripped of any trailing end-of-line marker. The returned line may be empty.
// The end-of-line marker is one optional carriage return followed by one mandatory newline.
// In regular expression notation, it is `\r?\n`. The last non-empty line of input will be returned even if it has no newline.
ReadLine() (string, error)
// Write writes the string to the internal data starting at the current offset. It moves the internal offset pointer.
// If the data would go over the file length, no data is written and an error is returned.
WriteString(string) (int, error)
// String() returns the entire mmap'd data as a string.
String() string
}
String provides methods for working with the mmaped file as a UTF-8 text file and retrieving data as a string.
Source Files