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
OnPanichook 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 tickOnPanic— 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 ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Watch ¶
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."
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.
Source Files