memctl

README

memctl

Periodic memory sampling with caller-defined policy.

err := memctl.Watch(ctx, memctl.Options{
    Interval:  2 * time.Second,
    Immediate: true,
}, func(ctx context.Context, m memctl.MemInfo) {
    headroom, ok := m.Headroom()
    if !ok {
        return
    }
    if headroom < 512<<20 {
        stage.SetMaxWIP(1)
    } else if headroom > 1<<30 {
        stage.SetMaxWIP(4)
    }
})

What It Does

Watch periodically reads memory metrics and calls your function. You decide what to do — the controller is intentionally dumb. Policy (throttle, pause, alert) lives in the callback.

Memory Signals

Signal	Source	Platform
SystemAvailable	/proc/meminfo MemAvailable	Linux
ProcessRSS	/proc/self/status VmRSS	Linux
GoRuntimeTotal	runtime/metrics /memory/classes/total:bytes	All
CgroupCurrent	cgroup v2 memory.current	Linux (containerized)
CgroupLimit	cgroup v2 memory.max	Linux (containerized)

Each field has an OK bool — false means unavailable, not "value is zero."

Headroom

MemInfo.Headroom() returns effective memory headroom:

• Uses cgroup headroom (limit - current) if a cgroup limit is detected
• Falls back to SystemAvailable (host-level) otherwise
• Returns (0, false) if neither signal is available

This means the controller automatically uses the tighter of container vs host limits.

Callback Contract

• Must be fast and non-blocking
• Invoked serially — no overlapping calls
• If callback exceeds interval, subsequent ticks are coalesced
• OnPanic hook controls panic behavior; nil (default) re-raises the panic

Options

• Interval — sampling period (required, > 0)
• Immediate — take first sample immediately, don't wait for first tick
• OnPanic — called if callback panics; nil = re-panic

Documentation

Overview

Package memctl provides periodic memory sampling with a caller-defined callback. The controller reads system, process, and cgroup memory metrics and calls a function with the results. Policy (what to do about memory pressure) lives in the callback — the controller is intentionally dumb.

On Linux, reads /proc/meminfo (MemAvailable), /proc/self/status (VmRSS), and cgroup v2 memory.current/memory.max. On other platforms, only Go runtime metrics are available.

The callback must be fast and non-blocking. Callbacks are invoked serially — no overlapping invocations. If a callback exceeds the interval, subsequent ticks are coalesced.

Index

• func Watch(ctx context.Context, opts Options, fn func(context.Context, MemInfo)) error
• type MemInfo
  • func (m MemInfo) Headroom() (uint64, bool)
  • func (m MemInfo) String() string
• type Options

Functions

func Watch

func Watch(ctx context.Context, opts Options, fn func(context.Context, MemInfo)) error

Watch blocks, sampling memory every interval and calling fn with the results until ctx is canceled. Returns nil on clean cancellation. Returns an error if options are invalid.

Callbacks are invoked serially — no overlapping invocations. If a callback exceeds the interval, subsequent ticks are coalesced.

Types

type MemInfo

type MemInfo struct {
	At time.Time // when this sample was taken

	SystemAvailable   uint64 // /proc/meminfo MemAvailable (bytes)
	SystemAvailableOK bool

	ProcessRSS   uint64 // /proc/self/status VmRSS (bytes)
	ProcessRSSOK bool

	GoRuntimeTotal   uint64 // runtime/metrics /memory/classes/total:bytes
	GoRuntimeTotalOK bool

	CgroupCurrent uint64 // cgroup v2 memory.current (bytes)
	CgroupLimit   uint64 // cgroup v2 memory.max (bytes; 0 = unlimited)
	CgroupOK      bool   // true when cgroup v2 is detected and readable
}

MemInfo holds process and system memory information. Each metric has an OK flag — false means unavailable on this platform or a read error occurred, not "value is zero."

func (MemInfo) Headroom

func (m MemInfo) Headroom() (uint64, bool)

Headroom returns the effective memory headroom in bytes. Uses cgroup headroom (limit - current) if a cgroup limit is set, otherwise falls back to SystemAvailable. Returns (0, false) if neither signal is available.

func (MemInfo) String

func (m MemInfo) String() string

String returns a compact summary of the memory info.

type Options

type Options struct {
	// Interval between memory samples. Must be > 0.
	Interval time.Duration

	// Immediate, when true, takes a sample immediately on entry
	// before waiting for the first tick. Catches startup spikes.
	Immediate bool

	// OnPanic is called if the callback panics. If nil, the panic
	// is re-raised (default: don't mask bugs). If non-nil, Watch
	// logs the panic via OnPanic and continues sampling.
	OnPanic func(any)
}

Options configures Watch.