sysmem

Documentation

Overview

Package sysmem reports machine memory.

It reads /proc/meminfo on Linux and reports "unknown" elsewhere, so callers must handle absence rather than assume a number. Needs no cgroup, no systemd, and no privileges — which is why it still works on Termux/Android, where scope isolation does not.

Index

• Constants
• func Available() (uint64, bool)
• func Total() (uint64, bool)
• type DiskUsage
  • func Disk(path string) (DiskUsage, bool)
  • func (d DiskUsage) Pressure() string
  • func (d DiskUsage) UsedBytes() uint64
  • func (d DiskUsage) UsedPct() float64

Constants

const (
	PressureOK   = "ok"
	PressureWarn = "warn"
	PressureFull = "full"
)

Pressure levels for the UI.

Functions

func Available

func Available() (uint64, bool)

Available reports the kernel's estimate of allocatable memory in bytes; ok is false when unknown.

func Total

func Total() (uint64, bool)

Total reports total RAM in bytes; ok is false when unknown.

Types

type DiskUsage

type DiskUsage struct {
	Path       string
	TotalBytes uint64
	FreeBytes  uint64
	AvailBytes uint64
}

DiskUsage is the capacity of the filesystem holding one path.

Available is what a NON-ROOT process may actually use, which is smaller than Free on most filesystems: ext4 reserves a percentage for root. Reporting Free would tell an unprivileged wick it has room it cannot take.

func Disk

func Disk(path string) (DiskUsage, bool)

Disk reports the capacity of the filesystem holding path.

ok is false when the path cannot be stat'd — a relocated data dir that does not exist yet, or a platform without statfs. Callers must render "unknown" rather than a zeroed row, or an unreadable disk looks like an empty one.

func (DiskUsage) Pressure

func (d DiskUsage) Pressure() string

Pressure grades how close this filesystem is to causing failures.

Percentage ALONE is the wrong signal, and gets it wrong in both directions. A 328 GB laptop disk at 93% still has 22 GB free — nothing is about to fail — while a 20 GB volume at 89% has 2 GB left and very nearly is. Judging by absolute free alone is equally wrong: 5 GB left on a 6 TB array means something quite different from 5 GB on a 10 GB volume.

So both must agree before the UI cries wolf: a level is only reached when the disk is BOTH proportionally full AND short of room in absolute terms. An alarm that fires on a healthy laptop is an alarm operators learn to ignore.

func (DiskUsage) UsedBytes

func (d DiskUsage) UsedBytes() uint64

UsedBytes is what is actually occupied.

func (DiskUsage) UsedPct

func (d DiskUsage) UsedPct() float64

UsedPct is occupancy as a percentage of total, 0 when unknown.

Computed against Total/Free rather than Available so it matches what `df` prints — an operator comparing the two should not see a discrepancy they have to explain.