free

Documentation

Overview

Package free finds what the machine can give back without touching running work and frees it on request: dead sessions' scratch in the tmpfs /tmp, orphaned go-build dirs, throwaway temp dirs and orphaned workers. What only a person decides on it reports with the memory the action would return: kind clusters, idle Claude CLIs, heavy or runaway processes and Chrome renderers. The swap reset and root-owned leftovers need root: beekeeper never runs as root, so they are printed as the commands a person runs.

Index

• Constants
• Variables
• func BuildCPULine(b *machine.BuildCPU, configured platform.Cap) string
• func Nice(n int)
• func ParseOnly(list []string) ([]string, error)
• type Freed
  • func (f Freed) String() string
• type Machine
• type Options
• type Run
  • func (r *Run) Do()
  • func (r *Run) Free() []Freed
• type Shared
  • func (s Shared) Print(out io.Writer, scan func(io.Writer) error) error

Constants

const (
	SessionDirs = "session-dirs"
	GoBuild     = "go-build"
	TmpDirs     = "tmp-dirs"
	Orphans     = "orphans"
	Swap        = "swap"
)

The sections --apply acts on, in the order they run and are summarized.

const (
	// CachedRow heads rows reused from an earlier scan: cached <age s>.
	CachedRow = "cached"
	// PartialRow ends rows cut short by the timeout: partial <timeout s>.
	PartialRow = "partial"
)

Row kinds Shared adds to the summary, after the scan's own.

const BuildCPUSample = 500 * time.Millisecond

BuildCPUSample is how long a reading samples memcap.slice's CPU use: a few of the quota's 100 ms periods, so that the figure is not one period's.

const DefaultStale = 3 * time.Hour

DefaultStale is how long a session's scratch or a temp dir stays untouched before it counts as stale, unless --stale-hours says otherwise.

const GoBuildAge = time.Hour

GoBuildAge is how long an orphaned go-build dir stays unchanged before it is freed: `go build -work` keeps its dir on purpose, to be looked at.

const SwapResetCmd = "sudo swapoff -a && sudo swapon -a"

SwapResetCmd is what a person runs to pull the swapped pages back into RAM.

Variables

var Automatic = []string{SessionDirs, GoBuild}

Automatic are the sections the watch frees by itself: what dead sessions and dead go commands leave in the tmpfs /tmp.

var Sections = []string{SessionDirs, GoBuild, TmpDirs, Orphans, Swap}

Sections lists the acting sections.

Functions

func BuildCPULine

func BuildCPULine(b *machine.BuildCPU, configured platform.Cap) string

BuildCPULine says memcap.slice's CPU budget and use: what the slice's cgroup reads, or the configured budget while the slice does not run; a slice with no quota says so and that the next run sets the configured one.

func Nice

func Nice(n int)

Nice lowers this process's priority to n. Linux keeps a nice value per thread, so every thread of the Go runtime is set; threads and children started later inherit it.

func ParseOnly

func ParseOnly(list []string) ([]string, error)

ParseOnly checks a --only list against the sections.

Types

type Freed

type Freed struct {
	Section string
	N, KiB  int
}

Freed is what one section freed, or would free: how many dirs or workers and their size.

func (Freed) String

func (f Freed) String() string

String says it as "12 dead sessions' dirs, 340 MiB".

type Machine

type Machine struct {
	UID  int
	Home string
	// TmpDir holds the go-build and throwaway temp dirs; Scratch Claude
	// Code's session dirs (<TmpDir>/claude-<uid>), Projects the transcripts.
	TmpDir, Scratch, Projects string
	Table                     *proc.Table
	Sessions                  []*claude.Session
	// Desk is beekeeper's state: the roster and the roles; nil when it
	// cannot be read, and then no CLI has either and every session's
	// scratch stays.
	Desk *state.State
	// Records maps CLI session ids, current and prior, to their desktop
	// records (their titles), read when needed.
	Records  func() map[string]*claude.Record
	Clusters []machine.Cluster
	// ClustersErr is set when docker cannot be asked.
	ClustersErr error
	// TableErr is set when the platform cannot list processes: Table is
	// empty, and every section that reads it says so instead.
	TableErr error
	// ClusterNotes says per cluster name which lab lease stands for it and
	// whether it is held or idle.
	ClusterNotes map[string]string
	// MaxLabs is how many kind clusters the machine holds.
	MaxLabs int
	SlotDir string
	Slots   int
	// BuildCPU is memcap.slice's configured CPU budget (its CPUQuota and
	// CPUWeight), said while the slice does not run.
	BuildCPU platform.Cap
	Now      time.Time
}

Machine is what free reads of the machine, gathered by the caller.

type Options

type Options struct {
	// Apply deletes and kills; without it free only reports.
	Apply bool
	// Summary prints the TSV candidates instead of the report (a dry run).
	Summary bool
	// Only restricts the acting sections; empty means every one.
	Only []string
	// Stale is how long a session's scratch or a temp dir must be untouched.
	Stale time.Duration
	// CLIStale is how long a CLI's session must be untouched for the CLI to
	// be reported stale (0: none is).
	CLIStale time.Duration
	// Orphan is how old an orphaned worker must be.
	Orphan time.Duration
	// HeavyMiB is the anonymous RSS from which a process is heavy (0: off).
	HeavyMiB int
	// RunawayCPU is the lifetime CPU share (percent) of a runaway process,
	// which has also burned at least Runaway of CPU time.
	RunawayCPU int
	Runaway    time.Duration
	// TabMiB is the anonymous RSS from which a Chrome renderer is reported
	// (0: off).
	TabMiB int
}

Options are the thresholds and the mode.

type Run

type Run struct {
	Options
	Machine
	Out io.Writer
	// contains filtered or unexported fields
}

Run is one invocation.

func (*Run) Do

func (r *Run) Do()

Do reports, and with Apply frees, the wanted sections.

func (*Run) Free

func (r *Run) Free() []Freed

Free runs only the wanted acting sections, their lines to Out without the report around them, and returns what each freed or, without Apply, would free.

type Shared

type Shared struct {
	// Dir holds the lock and the cached rows.
	Dir string
	// Key tells scans with other options apart: a cached result made with
	// another key is not used.
	Key string
	// MaxAge is how long a finished scan's rows are reused.
	MaxAge time.Duration
	// Timeout bounds the call, the wait for a running scan included. On
	// timeout the rows collected so far are printed with a partial row.
	Timeout time.Duration
	// Now is the clock, replaced in tests.
	Now func() time.Time
}

Shared runs the --summary scan at most once at a time and shares its rows. A front end starts free --summary on every click, and on a starved machine each scan takes minutes: without sharing, every impatient click adds a full scan to the load that made the first one slow. A caller that finds a scan running waits for it and prints its rows; a caller within MaxAge of a finished scan prints the cached rows under a header row with their age.

func (Shared) Print

func (s Shared) Print(out io.Writer, scan func(io.Writer) error) error

Print writes the summary rows to out: cached ones when a fresh result exists, otherwise those of one scan, run here or by the caller holding the lock.