Documentation
¶
Overview ¶
Package machine works out what host this process is running on: which distribution and release, and how much machine there is to use.
It is its own package because two callers need the same answer and neither should depend on the other: the agent reports these facts to the controller so a pool asking for Ubuntu 24.04 can be placed correctly, and the configuration loader uses them to give an unnamed host a name that says what it is instead of whatever the cloud provider called it.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DefaultHostName ¶
func DefaultHostName() string
DefaultHostName is the name an unnamed host is given: what it is, then which one it is, in the grammar of internal/naming -- "zoomies-16vcpu-32gb-ubuntu-2404-build01".
A machine that would say nothing about itself falls back to its bare hostname rather than to the bare prefix, because "zoomies" is not a name and the hostname at least distinguishes two hosts.
func Hostname ¶
func Hostname() string
Hostname is this machine's short name, or "localhost" when the host will not say. It is the discriminator in a canonical host name.
func MemoryReadable ¶ added in v1.3.8
func MemoryReadable() bool
MemoryReadable reports whether this platform has a way to read the host's memory that the memory valve can check a loan against: Linux's procfs, and nothing else for now.
Types ¶
type Facts ¶
type Facts struct {
// OS is the kernel, as Go names it: linux, darwin, windows.
OS string
// Distro and OSVersion are the distribution and its release, e.g.
// "ubuntu" and "24.04". Empty when the host cannot say, which is not an
// error: an unstated platform simply constrains nothing.
Distro string
OSVersion string
Arch string
// CPUs and MemoryMB are what this agent may actually use, which is not
// always what the machine has -- an agent in a container gets the cgroup's
// share, and reporting the host's 64 cores from inside a two-core cgroup
// would size every pool wrong.
CPUs int
MemoryMB int64
// CPUMHz is the fastest clock a processor runs at, and MemoryMTs the
// memory modules' rated figure, both in their own devices' units. The
// controller scores a host's placement priority from them beside CPUs and
// MemoryMB, so a beefier machine is offered work before a slower one of
// the same shape. Every probe behind them is best-effort: a zero is
// "not measured", which is what constrains nothing rather than what
// scores lowest.
CPUMHz int
MemoryMTs int
// DiskKind is the work filesystem's storage, "ssd" or "hdd" as the device
// reports itself. A spinning disk is the one speed difference the kernel
// will say out loud, and it is the axis a sector order matters on most.
// Empty when nothing could answer, and read like a zero above.
DiskKind string
}
Facts is what this host actually is: which distribution and release it runs, and how much of it there is.
The controller needs all of it. The distribution and release decide whether a pool asking for Ubuntu 24.04 may be placed here -- "linux" cannot pick a runner image -- and the size is what lets a host be named for what it is rather than for whatever the cloud provider called it.
type Memory ¶ added in v1.3.8
type Memory struct {
TotalMB, AvailableMB int64
// SwapTotalMB and SwapFreeMB are the machine's swap, both zero on a host
// with none -- which is a measurement and not a failure to measure.
SwapTotalMB, SwapFreeMB int64
}
Memory is the host's memory as the kernel reports it at one moment.
type Usage ¶
type Usage struct {
CPUPercent *float64
MemoryAvailableMB *int64
// LoadAverage1 is the kernel's one-minute load average: the mean number
// of runnable or uninterruptible tasks. It is the figure that keeps
// climbing after CPU occupancy has pinned at 100%, so it is what says how
// far past its cores a host has been pushed rather than merely that it is
// busy. Whole-machine, like the other two, so it is only reported where
// the CPU count is the machine's.
LoadAverage1 *float64
// IOWaitPercent is the share of CPU time the machine spent idle with
// something waiting on disk, between two samples. CPUPercent counts that
// time as busy, which is right for deciding whether a host has room and
// wrong for asking why a job is slow: a build waiting on a saturated disk
// reads as a machine hard at work. This is the figure that tells the two
// apart, and the reason a pool is told its scratch folders could live in
// memory.
IOWaitPercent *float64
}
Usage describes the whole machine, including work not owned by Zoomies. A missing value means unmeasured, never idle. Linux procfs is the only source for now; other platforms retain reservation-based placement.
type UsageSampler ¶
type UsageSampler struct {
// contains filtered or unexported fields
}
UsageSampler takes CPU deltas between heartbeats without sleeping or asking Docker to do more work while it may already be overloaded.
func (*UsageSampler) Memory ¶ added in v1.3.8
func (s *UsageSampler) Memory(memoryMB int64) (Memory, bool)
Memory reads the host's memory now. It is the look the memory valve takes before it lends any: unlike the CPU sample it needs no interval, so it can be taken every second without costing anything.
It answers only for the machine the caller believes it is on, as Sample does: a total that is not memoryMB is an agent's cgroup or a remote daemon's machine, and its free memory says nothing about the host the runners share.
Source Files