README
¶
mmap
Package mmap provides an interface to memory mapped files.
Memory maps can be opened as read-only with Read or read-write with Write. To specify additional flags and a file mode use Open.
There are two different ways to work with memory maps. They cannot be used simultaneously. Creating a Direct accessor will fail if any Readers or Writers are open. Creating Reader or Writer will fail if any Direct accessors are open.
The first is through direct access via a Direct, which is a pointer to a byte slice. This lets you write directly to the mapped memory, but you will need to manage access between go routines.
The second is through Readers and Writers. These implement the standard interfaces from the io package and can be treated like files while still benefitting from the improved performance of memory mapping.
You can have multiple Readers and Writers. The map will ensure that writes don't conflict with reads. That is, the underlying map won't change during the middle of a read.
When the map is resized via Truncate, all open Direct, Reader, and Writer objects are closed.
Documentation
¶
Overview ¶
Package mmap provides an interface to memory mapped files.
Memory maps can be opened as read-only with Read or read-write with Write. To specify additional flags and a file mode use Open.
There are two different ways to work with memory maps. They cannot be used simultaneously. Creating a Direct accessor will fail if any Readers or Writers are open. Creating Reader or Writer will fail if any Direct accessors are open.
The first is through direct access via a Direct, which is a pointer to a byte slice. This lets you write directly to the mapped memory, but you will need to manage access between go routines.
The second is through Readers and Writers. These implement the standard interfaces from the io package and can be treated like files while still benefitting from the improved performance of memory mapping.
You can have multiple Readers and Writers. The map will ensure that writes don't conflict with reads. That is, the underlying map won't change during the middle of a read.
When the map is resized via Truncate, all open Direct, Reader, and Writer objects are closed.
Index ¶
- Constants
- type Direct
- type Map
- func (m *Map) Close() error
- func (m *Map) Closed() bool
- func (m *Map) Direct() (Direct, error)
- func (m *Map) DirectAt(offset int, size int) (Direct, error)
- func (m *Map) Free(direct Direct) error
- func (m *Map) Name() string
- func (m *Map) Reader() (*Reader, error)
- func (m *Map) Size() int
- func (m *Map) Sync(wait bool) error
- func (m *Map) Truncate(size int64) error
- func (m *Map) WriteSync() bool
- func (m *Map) Writeable() bool
- func (m *Map) Writer() (*Writer, error)
- type Reader
- func (r *Reader) Close() error
- func (r *Reader) Peek(offset int) (byte, error)
- func (r *Reader) Read(b []byte) (n int, err error)
- func (r *Reader) ReadAt(b []byte, offset int64) (n int, err error)
- func (r *Reader) ReadByte() (byte, error)
- func (r *Reader) Seek(offset int64, whence int) (ret int64, err error)
- type Writer
Constants ¶
const ( ReadOnly int = os.O_RDONLY // open the file read-only ReadWrite int = os.O_RDWR // open the file read-write Create int = os.O_CREATE // create a new file if none exists Exclusive int = os.O_EXCL // used with O_CREATE, file must not exist Sync int = os.O_SYNC // calls Sync() after each write Truncate int = os.O_TRUNC // if possible, truncate file when opened )
Exactly one of ReadOnly or ReadWrite must be specified. The remaining values may be or'ed in to control behavior.
const ( SeekStart int = 0 // seek relative to the start of the file SeekCurrent int = 1 // seek relative to the current offset SeekEnd int = 2 // seek relative to the end )
Constants used for whence in Seek.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Direct ¶
type Direct *[]byte
Direct is a pointer to a byte slice that directly accesses the memory map. Multiple Direct pointers can be created, but only if there are no open Readers or Writers on the Map.
As a pointer, the value will have to be dereferenced when used.
b, _ := memmap.Direct()
n := len(*b)
for i := range *b {
*(b)[i] = i % 256
}
Warning: Do not copy or assign the Direct to another variable. The copy won't be released when the original is and will become invalid if the map is closed or resized.
b, _ := memmap.Direct() x := *b // Do not do this!
type Map ¶
Map represents a file on disk that has been mapped into memory.
func Open ¶
Open opens a file as a memory map using the given flags. It does not support the O_WRONLY or O_APPEND flags. It will create the file if it doesn't exist. If the file is empty or O_TRUNC is specified, the file will be resized to the size of a memory page as returned by os.Getpagesize() and the bytes will be zeroed out.
func Write ¶
Write opens a file as a writeable memory map. It will create the file if it doesn't exist with FileMode 0600. It does not truncate the file, however if the file size is 0, it will resize the file to be size of a memory page as returned by os.Getpagesize(). If a different size is needed, call Truncate after opening.
func (*Map) DirectAt ¶
DirectAt creates a Direct slice to a region of the memory map specified by offset and size.
func (*Map) Truncate ¶
Truncate resizes the backing file and the memory map to the requested size. Any open Direct, Readers, and Writers are closed.
type Reader ¶
type Reader struct {
*Map
// contains filtered or unexported fields
}
Reader reads from a map. It implements the following interfaces from the io standard package:
- Reader (Read)
- ReaderAt (ReadAt)
- ByteReader (ReadByte)
- Seeker (Seek)
- Closer (Close)
- ReadCloser (Read, Close)
- ReadSeeker (Read, Seek)
func (*Reader) Read ¶
Read reads up to len(b) bytes from the map Reader. It returns the number of bytes read and any error encountered. At end of map, Read returns 0, io.EOF.
func (*Reader) ReadAt ¶
ReadAt reads len(b) bytes from the Map starting at offset. It returns the number of bytes read and the error, if any. ReadAt returns io.EOF when n < len(b).
func (*Reader) ReadByte ¶
ReadByte reads and returns the next byte from the map. It returns io.EOF if the Reader is at the end of the file.
type Writer ¶
type Writer struct {
*Reader
}
Writer reads from and writes to a map. In addition to the methods of mmap.Reader, it also implements the following interfaces from the io standard package:
- Writer (Write)
- WriterAt (WriteAt)
- ByteWriter (WriteByte)
- WriteSeeker (Write, Seek)
- WriteCloser (Write, Close)
- ReadWriter (Read, Write)
- ReadWriteSeeker (Read, Write, Seek)
- ReadWriteCloser (Read, Write, Close)
func (*Writer) Write ¶
Write writes len(b) bytes to the File. It returns the number of bytes written and an error, if any. Write returns io.ErrShortWrite when n < len(b).
func (*Writer) WriteAt ¶
WriteAt writes len(b) bytes to the File starting at byte offset off. It returns the number of bytes written and an error, if any. WriteAt returns io.ErrShortWrite when n < len(b).
Source Files