memoryguard

memoryguard

import "github.com/cognusion/go-memoryguard"

• Overview
• Index
• Examples

Overview

Package memoryguard is a system to track the PSS memory usage of an os.Process and kill it if the usage exceeds the stated Limit.

Index

• Constants
• type Error
  • func (e Error) Error() string
• type MemoryGuard
  • func New(Process *os.Process) *MemoryGuard
  • func (m *MemoryGuard) Cancel()
  • func (m *MemoryGuard) CancelWait()
  • func (m *MemoryGuard) Limit(max int64) error
  • func (m *MemoryGuard) PSS() int64

Examples

• MemoryGuard
• MemoryGuard.CancelWait

Package files

athena.go errors.go

Constants

const (
    // LimitZeroError is returned by Limit(int64) when the passed variable is <= 0.
    LimitZeroError = Error("please call Limit(int64) with a value greater than zero")
    // LimitNilProcessError is returned by Limit(int64) when the referenced *os.Process is nil.
    LimitNilProcessError = Error("a Process has not been created and assigned, or is nil")
    // LimitOnceError is returned by Limit(int64) if it has been called without error previously.
    LimitOnceError = Error("Limit(int64) already called once")
)

type Error

type Error string

Error is an error type

func (Error) Error

func (e Error) Error() string

Error returns the stringified version of Error

type MemoryGuard

type MemoryGuard struct {
    // Name is a name to use in lieu of PID for messaging
    Name string
    // Interval is a time.Duration to wait between checking usage
    Interval time.Duration
    // DebugOut is a logger for debug information
    DebugOut *log.Logger
    // ErrOut is a logger for StdErr coming from a process
    ErrOut *log.Logger
    // KillChan will be closed if/when the process is killed
    KillChan chan struct{}
    // KillError will be any error returned by the "Kill" operation. Varies widely by OS. Usually nil.
    KillError error
    // StatsFrequency updates the internal frequency to which statistics are emitted to the debug logger. Default is 1 minute.
    StatsFrequency time.Duration
    // contains filtered or unexported fields
}

MemoryGuard is our encapsulating mechanation, and should only be acquired via a New helper. Member functions are goro-safe, but all struct attributes should be set immediatelyish after New(), and before Limit() is called.

// Get a handle on our process
us, _ := os.FindProcess(os.Getpid())

// Create a new MemoryGuard around the process
mg := New(us)
mg.Limit(512 * 1024 * 1024) // Set the HWM memory limit. You can change this at any time

// Do stuff that is memory-hungry

// Stop guarding. After this, if you want to guard the process again,
// Make a New() guard.
mg.Cancel()
// Cancel returns immediately, goros will end eventually.

func New

func New(Process *os.Process) *MemoryGuard

New takes an os.Process and returns a MemoryGuard for that process

func (*MemoryGuard) Cancel

func (m *MemoryGuard) Cancel()

Cancel signals a Limit() operation to stop, returning immediately. After calling Cancel this MemoryGuard will be non-functional

func (*MemoryGuard) CancelWait

func (m *MemoryGuard) CancelWait()

CancelWait signals a Limit() operation to stop, and waits to return until it is done. After calling CancelWait this MemoryGuard will be non-functional

// Get a handle on our process
us, _ := os.FindProcess(os.Getpid())

// Create a new MemoryGuard around the process
mg := New(us)
mg.Limit(512 * 1024 * 1024) // Set the HWM memory limit. You can change this at any time

// Do stuff that is memory-hungry

// Stop guarding. After this, if you want to guard the process again,
// Make a New() guard.
mg.CancelWait()
// CancelWait pauses until the goros are all done.

func (*MemoryGuard) Limit

func (m *MemoryGuard) Limit(max int64) error

Limit takes the max usage (in Bytes) for the process and acts on the PSS. Returns an error if Limit is called with a zero or negative value, with a nil Process reference (did you use New()?), or if it has already been called once before, successfully.

func (*MemoryGuard) PSS

func (m *MemoryGuard) PSS() int64

PSS returns the last known PSS value for the watched process, or the current value, if there was no last value. After a process is killed for going over, this will be the last value observed prior to process death.

Generated by godoc2md