mmap

README

nntp-mmap

nntp-server mmap unix module

Documentation

Overview

Package Mmap allows mapping files into memory. It tries to provide a simple, reasonably portable interface, but doesn't go out of its way to abstract away every little platform detail. This specifically means:

• forked processes may or may not inherit mappings
• a file's timestamp may or may not be updated by writes through mappings
• specifying a size larger than the file's actual size can increase the file's size
• If the mapped file is being modified by another process while your program's running, don't expect consistent results between platforms

Index

• Constants
• func MmapMount(len int, inprot, inflags, fd uintptr, off int64) ([]byte, error)
• type Map
• type Mmap
  • func NewMmap(f *os.File, length int, prot int, flags int, offset int64) (*Mmap, error)
  • func (m *Mmap) Bytes() []byte
  • func (m *Mmap) Close() error
  • func (m *Mmap) FlushMmap() error
  • func (m *Mmap) Len() int
  • func (m *Mmap) LockMmap() error
  • func (m *Mmap) Pos() int
  • func (m *Mmap) Read(p []byte) (int, error)
  • func (m *Mmap) ReadAt(p []byte, off int64) (n int, err error)
  • func (m *Mmap) Seek(offset int64, whence int) (int64, error)
  • func (m *Mmap) UnlockMmap() error
  • func (m *Mmap) UnmapMmap() error
  • func (m *Mmap) Write(p []byte) (n int, err error)

Constants

const (
	// RDONLY maps the memory read-only.
	// Attempts to write to the MMap object will result in undefined behavior.
	RDONLY = 0
	// RDWR maps the memory as read-write. Writes to the MMap object will update the
	// underlying file.
	RDWR = 1 << iota
	// COPY maps the memory as copy-on-write. Writes to the MMap object will affect
	// memory, but the underlying file will remain unchanged.
	COPY
	// If EXEC is set, the mapped memory is marked as executable.
	EXEC
)

const (
	// If the ANON flag is set, the mapped memory will not be backed by a file.
	ANON = 1 << iota
)

Functions

func MmapMount

func MmapMount(len int, inprot, inflags, fd uintptr, off int64) ([]byte, error)

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.
	LockMmap() error

	// Unlock allows the physical memory to be swapped out to disk. If the memory is not locked, nothing happens.
	UnlockMmap() error

	FlushMmap() error

	UnmapMmap() error

	Close() 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 Mmap

type Mmap struct {
	// contains filtered or unexported fields
}

Mmap implements Map.

func NewMmap

func NewMmap(f *os.File, length int, prot int, flags int, offset int64) (*Mmap, error)

NewMap creates a new Map object that provides methods for interacting with the Mmap'd file.

func (*Mmap) Bytes

func (m *Mmap) Bytes() []byte

Bytes implements Map.Bytes().

func (*Mmap) Close

func (m *Mmap) Close() error

Close implements Map.Close().

func (*Mmap) FlushMmap

func (m *Mmap) FlushMmap() error

Flush implements Map.Flush(). Flush synchronizes the mapping's contents to the file's contents on disk.

func (*Mmap) Len

func (m *Mmap) Len() int

Len returns the size of the file, which can be larger than the memory mapped area.

func (*Mmap) LockMmap

func (m *Mmap) LockMmap() error

Lock implements Map.Lock(). Lock keeps the mapped region in physical memory, ensuring that it will not be swapped out.

func (*Mmap) Pos

func (m *Mmap) Pos() int

Pos implements Map.Pos().

func (*Mmap) Read

func (m *Mmap) Read(p []byte) (int, error)

Read implements io.Reader.Read().

func (*Mmap) ReadAt

func (m *Mmap) ReadAt(p []byte, off int64) (n int, err error)

ReadAt implements ReaderAt.ReadAt().

func (*Mmap) Seek

func (m *Mmap) Seek(offset int64, whence int) (int64, error)

Seek implements io.Seeker.Seek().

func (*Mmap) UnlockMmap

func (m *Mmap) UnlockMmap() error

Unlock implements Map.Unlock(). Unlock reverses the effect of Lock, allowing the mapped region to potentially be swapped out. If m is already unlocked, aan error will result.

func (*Mmap) UnmapMmap

func (m *Mmap) UnmapMmap() error

Unmap implements Map.Unmap(). Unmap deletes the memory mapped region, flushes any remaining changes, and sets m to nil. Trying to read or write any remaining references to m after Unmap is called will result in undefined behavior. Unmap should only be called on the slice value that was originally returned from a call to Map. Calling Unmap on a derived slice may cause errors.

func (*Mmap) Write

func (m *Mmap) Write(p []byte) (n int, err error)

Write implements io.Writer.Write().