shm

Documentation

Overview

Package shm implements shared memory objects.

Index

• func DestroyMemoryObject(name string) error
• type MemoryObject
  • func NewMemoryObject(name string, flag int, perm os.FileMode) (*MemoryObject, error)
  • func (obj *MemoryObject) Close() error
  • func (obj *MemoryObject) Destroy() error
  • func (obj *MemoryObject) Fd() uintptr
  • func (obj *MemoryObject) Name() string
  • func (obj *MemoryObject) Size() int64
  • func (obj *MemoryObject) Truncate(size int64) error
• type SharedMemoryObject
  • func NewMemoryObjectSize(name string, flag int, perm os.FileMode, size int64) (SharedMemoryObject, bool, error)

Examples

• MemoryObject
• MemoryObject (ReadWriter)

Functions

func DestroyMemoryObject

func DestroyMemoryObject(name string) error

DestroyMemoryObject permanently removes given memory object.

Types

type MemoryObject

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

MemoryObject represents an object which can be used to map shared memory regions into the process' address space.

Example

// cleanup previous objects
DestroyMemoryObject("obj")
// create new object and resize it.
obj, err := NewMemoryObject("obj", os.O_CREATE|os.O_EXCL|os.O_RDWR, 0666)
if err != nil {
	panic("new")
}
if err := obj.Truncate(1024); err != nil {
	panic("truncate")
}
// create two regions for reading and writing.
rwRegion, err := mmf.NewMemoryRegion(obj, mmf.MEM_READWRITE, 0, 1024)
if err != nil {
	panic("new region")
}
defer rwRegion.Close()
roRegion, err := mmf.NewMemoryRegion(obj, mmf.MEM_READ_ONLY, 0, 1024)
if err != nil {
	panic("new region")
}
defer roRegion.Close()
// copy some data to the first region and read it via the second one.
data := []byte{1, 2, 3, 4, 5, 6, 7, 8}
copy(rwRegion.Data(), data)
for i, b := range data {
	if b != roRegion.Data()[i] {
		panic("bad data")
	}
}

Example (ReadWriter)

// this example shows how to use memory obects with memory region readers/writers.

// cleanup previous objects
DestroyMemoryObject("obj")
// create new object and resize it.
obj, err := NewMemoryObject("obj", os.O_CREATE|os.O_EXCL|os.O_RDWR, 0666)
if err != nil {
	panic("new")
}
if err := obj.Truncate(1024); err != nil {
	panic("truncate")
}
// create two regions for reading and writing.
rwRegion, err := mmf.NewMemoryRegion(obj, mmf.MEM_READWRITE, 0, 1024)
if err != nil {
	panic("new region")
}
defer rwRegion.Close()
roRegion, err := mmf.NewMemoryRegion(obj, mmf.MEM_READ_ONLY, 0, 1024)
if err != nil {
	panic("new region")
}
defer roRegion.Close()
// for each region we create a reader and a writer, which is a better solution, than
// using region.Data() bytes directly.
writer := mmf.NewMemoryRegionWriter(rwRegion)
reader := mmf.NewMemoryRegionReader(roRegion)
// write data at the specified offset
data := []byte{1, 2, 3, 4, 5, 6, 7, 8}
written, err := writer.WriteAt(data, 128)
if err != nil || written != len(data) {
	panic("write")
}
// read data at the same offset via another region.
actual := make([]byte, len(data))
read, err := reader.ReadAt(actual, 128)
if err != nil || read != len(data) {
	panic("read")
}
for i, b := range data {
	if b != actual[i] {
		panic("wrong data")
	}
}

func NewMemoryObject

func NewMemoryObject(name string, flag int, perm os.FileMode) (*MemoryObject, error)

NewMemoryObject creates a new shared memory object.

name - a name of the object. should not contain '/' and exceed 255 symbols (30 on darwin).
size - object size.
flag - flag is a combination of open flags from 'os' package.
perm - object's permission bits.

func (*MemoryObject) Close

func (obj *MemoryObject) Close() error

Close closes object's underlying file object. Darwin: a call to Close() causes invalid argument error, if the object was not truncated. So, in this case we return nil as an error.

func (*MemoryObject) Destroy

func (obj *MemoryObject) Destroy() error

Destroy closes the object and removes it permanently.

func (*MemoryObject) Fd

func (obj *MemoryObject) Fd() uintptr

Fd returns a descriptor of the object's underlying file object.

func (*MemoryObject) Name

func (obj *MemoryObject) Name() string

Name returns the name of the object as it was given to NewMemoryObject().

func (*MemoryObject) Size

func (obj *MemoryObject) Size() int64

Size returns the current object size. Darwin: it may differ from the size passed passed to Truncate.

func (*MemoryObject) Truncate

func (obj *MemoryObject) Truncate(size int64) error

Truncate resizes the shared memory object. Darwin: it is possible to truncate an object only once after it was created. Darwin: the size should be divisible by system page size, otherwise the size is set to the nearest page size divider greater, then the given size.

type SharedMemoryObject

type SharedMemoryObject interface {
	Size() int64
	Truncate(size int64) error
	Close() error
	Destroy() error
	mmf.Mappable
}

SharedMemoryObject is an interface, which must be implemented by any implemetation of an object used for mapping into memory.

func NewMemoryObjectSize

func NewMemoryObjectSize(name string, flag int, perm os.FileMode, size int64) (SharedMemoryObject, bool, error)

NewMemoryObjectSize opens or creates a shared memory object with the given name. If the object was created, it is truncated to 'size'. Otherwise, checks, that the existing object is at least 'size' bytes long. Returns an object, true, if it was created, and an error.