README
¶
go-mmstruct / mmf 
working with memory mapped files in golang.
Installation
Go and get it...
$ go get github.com/HellButcher/go-mmstruct/mmf
Usage
Creating a file:
package main
import (
"github.com/HellButcher/go-mmstruct/mmf"
)
func main() {
mf, err := mmf.CreateMappedFile("aNewFile.bin", 4096)
if err != nil {
// ...
}
defer mf.Close()
// do something in the mapped memory area
data := mf.Bytes()
data[1337] = 42 // writing
foo := data[666] // reading
}
Opening a file:
package main
import (
"github.com/HellButcher/go-mmstruct/mmf"
)
func main() {
mf, err := mmf.OpenMappedFile("anExistingFile.bin")
if err != nil {
// ...
}
defer mf.Close()
// do something in the mapped memory area
data := mf.Bytes()
data[666] = 42 // writing
foo := data[1337] // reading
}
The MappedFile
object can also be used as a Reader or
Writer (and some other interfaces).
Documentation
¶
Index ¶
- Constants
- type BlockFile
- func CreateBlockFile(filename string) (*BlockFile, error)
- func CreateBlockFileInMapper(mapper Mapper) (*BlockFile, error)
- func CreateBlockFileInMapperWithSize(mapper Mapper, blocksize uint32) (*BlockFile, error)
- func CreateBlockFileWithSize(filename string, blocksize uint32) (*BlockFile, error)
- func OpenBlockFile(filename string) (*BlockFile, error)
- func OpenBlockFileFromMapper(mapper Mapper) (*BlockFile, error)
- func (bf *BlockFile) AllocateBlock() (int, error)
- func (bf *BlockFile) AllocateBlocks(num int) ([]int, error)
- func (bf *BlockFile) BlockSize() int
- func (bf *BlockFile) Close() error
- func (bf *BlockFile) FreeBlock(block int) error
- func (bf *BlockFile) FreeBlocks(blocks []int) (int, error)
- func (bf *BlockFile) MapBlock(block int, handler func([]byte) error) error
- func (bf *BlockFile) MapHeader(handler func(data []byte, contentType uint32) error) error
- type MappedFile
- func (mf *MappedFile) Bytes() []byte
- func (mf *MappedFile) Close() error
- func (mf *MappedFile) Fd() uintptr
- func (mf *MappedFile) Len() int
- func (mf *MappedFile) Map(off int64, length int, handler func([]byte) error) error
- func (mf *MappedFile) Name() string
- func (mf *MappedFile) Next(n int) []byte
- func (mf *MappedFile) Offset() int
- func (mf *MappedFile) Read(p []byte) (int, error)
- func (mf *MappedFile) ReadAt(b []byte, off int64) (int, error)
- func (mf *MappedFile) ReadByte() (byte, error)
- func (mf *MappedFile) Seek(offset int64, whence int) (int64, error)
- func (mf *MappedFile) Size() int
- func (mf *MappedFile) Sync() error
- func (mf *MappedFile) Truncate(size int64) error
- func (mf *MappedFile) Write(p []byte) (int, error)
- func (mf *MappedFile) WriteAt(b []byte, off int64) (int, error)
- func (mf *MappedFile) WriteByte(c byte) error
- type Mapper
Constants ¶
const ( SeekStart = io.SeekStart // seek relative to the origin of the file SeekCurrent = io.SeekCurrent // seek relative to the current offset SeekEnd = io.SeekEnd // seek relative to the end )
const BlockFileMagic uint32 = 0xB10CF11E // the first 4 byte of a block-file
const ContentFreeList uint32 = 0xF9337157
const DefaultBlocksize = 4096
The default block size that is used by CreateBlockFile and CreateBlockFileInMapper
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type BlockFile ¶
type BlockFile struct {
// contains filtered or unexported fields
}
func CreateBlockFile ¶
CreateBlockFile creates a new block-file at the given filename with the DefaultBlocksize.
func CreateBlockFileInMapper ¶
CreateBlockFileInMapper creates a new block-file in the given Mapper with the DefaultBlocksize.
func CreateBlockFileInMapperWithSize ¶
CreateBlockFileInMapperWithSize creates a new block-file in the given Mapper with the given blocksize.
func CreateBlockFileWithSize ¶
CreateBlockFileWithSize creates a new block-file at the given filename with the given blocksize.
func OpenBlockFile ¶
OpenBlockFile opens an existing block-file that is given as filename.
func OpenBlockFileFromMapper ¶
OpenBlockFileFromMapper opens an existing block-file by providig a Mapper.
func (*BlockFile) AllocateBlock ¶
AllocateBlock returns a new unused block-index. This either returns a block from an internal free-list (a block that was Freed earlier by FreeBlock), or allocates new space by calling Truncate on the mapper.
func (*BlockFile) AllocateBlocks ¶
AllocateBlocks allocates a given number ob blocks (see AllocateBlock)
func (*BlockFile) FreeBlock ¶
FreeBlock puts the given block to an internal free-list, so that the block can be returned by future call to AllocateBlock.
func (*BlockFile) FreeBlocks ¶
FreeBlocks frees a given number ob blocks (see FreeBlock)
type MappedFile ¶
type MappedFile struct {
// contains filtered or unexported fields
}
MappedFile is a struct that defines an open memory mapped file
func CreateMappedFile ¶
func CreateMappedFile(filename string, size int64) (*MappedFile, error)
CreateMappedFile creates a new file (or replaces an existing one) with the given initial size. The file is then mapped to memory. The mapped memory is Readable and Writeable. The operating system will write the changes to the file at some point later. When multiple processes open the same file, the mapped memory for will be shared between the processes. It returns an error, if any.
func OpenMappedFile ¶
func OpenMappedFile(filename string) (*MappedFile, error)
OpenMappedFile opens an existing file and maps it to memory. The mapped memory is Readable and Writeable. The operating system will write the changes to the file at some point later. When multiple processes open the same file, the mapped memory for will be shared between the processes. It returns an error, if any.
func (*MappedFile) Bytes ¶
func (mf *MappedFile) Bytes() []byte
Bytes returns a slice to the mapped memory area. The slice is valid only until mf.Close or mf.Truncate is called or mf is garbage collected.
func (*MappedFile) Close ¶
func (mf *MappedFile) Close() error
Close unmaps the mapped memory and closes the File. It returns an error, if any.
func (*MappedFile) Fd ¶
func (mf *MappedFile) Fd() uintptr
Fd returns the file descriptor handle referencing the open file. The file descriptor is valid only until mf.Close is called or mf is garbage collected.
func (*MappedFile) Len ¶
func (mf *MappedFile) Len() int
Len returns the number of bytes of the unread portion of the memory. mf.Offset() + mf.Len() == mf.Size().
func (*MappedFile) Name ¶
func (mf *MappedFile) Name() string
Name returns the name of the file as presented to CreateMappedFile or OpenMappedFile.
func (*MappedFile) Next ¶
func (mf *MappedFile) Next(n int) []byte
Next returns a slice containing the next n bytes in the mapped memory and advances the current position as if the bytes had been returned by Read. If there are fewer than n bytes in the buffer, Next only returns the subset until the end of the mapped memory. The slice is valid only until mf.Close or mf.Truncate is called or mf is garbage collected.
func (*MappedFile) Offset ¶
func (mf *MappedFile) Offset() int
Offset returns the current position in the mapped memory. The next call to Read or Write will start at this position.
func (*MappedFile) Read ¶
func (mf *MappedFile) Read(p []byte) (int, error)
Read reads up to len(b) bytes from the mapped memory. It returns the number of bytes read and an error, if any. EOF is signaled by a zero count with err set to io.EOF.
func (*MappedFile) ReadAt ¶
func (mf *MappedFile) ReadAt(b []byte, off int64) (int, error)
ReadAt reads up to len(b) bytes from the mapped memory starting at byte offset off. It returns the number of bytes read and the error, if any. ReadAt always returns a non-nil error when n < len(b). At end of file, that error is io.EOF.
func (*MappedFile) ReadByte ¶
func (mf *MappedFile) ReadByte() (byte, error)
ReadByte reads and returns the next byte from the mapped memory. If no byte is available, it returns error io.EOF.
func (*MappedFile) Seek ¶
func (mf *MappedFile) Seek(offset int64, whence int) (int64, error)
Seek sets the offset for the next Read or Write on mapped memory to offset, interpreted according to whence:
0 means relative to the origin of the file, 1 means relative to the current offset, and 2 means relative to the end.
It returns the new offset and an error, if any.
func (*MappedFile) Size ¶
func (mf *MappedFile) Size() int
Size returns the total size of the mapped memory. mf.Size() == len(mf.Bytes()).
func (*MappedFile) Sync ¶
func (mf *MappedFile) Sync() error
Sync tells the operating system to write the changes back to the file soon. It returns an error, if any.
func (*MappedFile) Truncate ¶
func (mf *MappedFile) Truncate(size int64) error
Truncate changes the size of the file and the mapped memory area. The (virtual-)address of the mapped memory area will possibly change. It returns an error, if any.
func (*MappedFile) Write ¶
func (mf *MappedFile) Write(p []byte) (int, error)
Write writes up to len(b) bytes to the mapped memory. It returns the number of bytes written and an error, if any. Write returns a non-nil error when n != len(b). The file/memory doesn't grow automatically. EOF is signaled by a zero count with err set to io.EOF.
func (*MappedFile) WriteAt ¶
func (mf *MappedFile) WriteAt(b []byte, off int64) (int, error)
WriteAt writes up to len(b) bytes to the mapped memory starting at byte offset off. It returns the number of bytes written and an error, if any. ReadAt always returns a non-nil error when n < len(b). At end of file, that error is io.EOF.
func (*MappedFile) WriteByte ¶
func (mf *MappedFile) WriteByte(c byte) error
WriteByte writes the next byte to the mapped memory. If the end of the mapped memory area is reached, it returns error io.EOF.
Source Files