Processor, memory and disk

What this Mac, its extra Spaces and your other computers use: one snapshot, a stream of changes and the low-disk warning.

Spaces.resources returns one ResourcesSnapshot: this Mac's cores, memory and free disk, each extra Space's allocation, use and cost on this Mac's disk, and the summary each of your other computers published. Spaces.watch_resources calls a ResourcesListener with a snapshot, then only the entries that changed by more than 1 point or 256 MB, and a LowDisk event when the free-disk level changes. Numbers only: counts, bytes and percentages.

Resources#

Methods of Spaces.

`Spaces.resources`#

What this Mac, its extra Spaces and your other computers use now: processor, memory and disk, as one snapshot (a few seconds old at most). With visible, the call also says a window shows the numbers for the next 30 seconds, so the runtime samples every 10 seconds instead of every 5 minutes: call it every 10 seconds while a window is visible and stop when it is hidden.

async def resources(self, visible: bool) -> ResourcesSnapshot

Parameter	Type	Default
`visible`	`bool`	required

Returns ResourcesSnapshot · Async · Raises CuaError

`Spaces.watch_resources`#

The same numbers as events for listener: a snapshot first, then an update with only the entries that changed by more than 1 point or 256 MB, and LowDisk whenever the warning level changes. Reopens by itself if the daemon restarts (the snapshot comes again). Stop it with ResourcesWatch.stop.

def watch_resources(self, visible: bool, listener: ResourcesListener) -> ResourcesWatch

Parameter	Type	Default
`visible`	`bool`	required
`listener`	`ResourcesListener`	required

Returns ResourcesWatch

`ResourcesSnapshot` record#

One sample of everything.

Returned by Spaces.resources.

Field	Type	Description
`sequence`	`u64`	Grows by one per sample.
`sampled_at_ms` / `sampledAtMs`	`u64`	Unix ms.
`this_mac` / `thisMac`	`ComputerResources`	This Mac.
`spaces`	`Vec<SpaceResources>`	Extra Spaces on this Mac.
`computers`	`Vec<ComputerResources>`	Your other computers, from the summaries they published.
`warning`	`DiskWarning`	`this_mac.warning`, for the menu bar.

`ComputerResources` record#

A computer: this Mac, or one of your other computers (from the summary it published).

Field	Type	Description
`id`	`String`	`this-mac`, or the relay machine id.
`name`	`String`	Display name (empty for this Mac).
`online`	`bool`	Reachable now (always true for this Mac).
`sampled_at_ms` / `sampledAtMs`	`u64`	When the computer measured this, unix ms (another computer's can be minutes old).
`cpu_count` / `cpuCount`	`u32`	Processor cores.
`cpu_percent` / `cpuPercent`	`f64`	Busy now, 0 to 100.
`load_average_1m` / `loadAverage1m`	`f64`	1-minute load average.
`memory_total` / `memoryTotal`	`u64`	Memory size, bytes.
`memory_used` / `memoryUsed`	`u64`	Memory in use, bytes (without reclaimable cache).
`disk_total` / `diskTotal`	`u64`	Size of the volume that holds Spaces, bytes.
`disk_free` / `diskFree`	`u64`	Free bytes on it.
`spaces_count` / `spacesCount`	`u32`	Extra Spaces on it.
`spaces_running` / `spacesRunning`	`u32`	Of those, running.
`spaces_cpu_allocated` / `spacesCpuAllocated`	`u32`	Cores given to the running ones.
`spaces_memory_allocated` / `spacesMemoryAllocated`	`u64`	Memory given to the running ones, bytes.
`spaces_memory_used` / `spacesMemoryUsed`	`u64`	Memory the running guests report in use, bytes.
`spaces_disk_bytes` / `spacesDiskBytes`	`u64`	Bytes all its extra Spaces take on it.
`spaces_disk_exact` / `spacesDiskExact`	`bool`	False when some Space's disk could only be estimated.
`warning`	`DiskWarning`	The low-disk signal.

`SpaceResources` record#

One extra Space on this Mac.

Field	Type	Description
`id`	`String`	`local:<name>`.
`power_state` / `powerState`	`String`	`running`, `stopped`, `suspended`, or empty when unknown.
`cpu_allocated` / `cpuAllocated`	`u32`	Cores given to it (0: unknown).
`memory_allocated` / `memoryAllocated`	`u64`	Memory given to it, bytes (0: unknown).
`disk_allocated` / `diskAllocated`	`u64`	Its disk's size limit, bytes (0: unknown).
`usage`	`Option<GuestUsage>`	The guest's own numbers; absent while it is off or unreachable.
`disk_on_host` / `diskOnHost`	`Option<DiskOnHost>`	What it costs this Mac; absent for a container.

`GuestUsage` record#

What SystemService.Metrics reports from inside a Space.

Field	Type	Description
`cpu_count` / `cpuCount`	`u32`	Cores the guest sees.
`cpu_percent` / `cpuPercent`	`f64`	Busy now, 0 to 100.
`load_average_1m` / `loadAverage1m`	`f64`	1-minute load average.
`memory_used` / `memoryUsed`	`u64`	Memory in use, bytes.
`memory_total` / `memoryTotal`	`u64`	Memory size, bytes.
`memory_limited` / `memoryLimited`	`bool`	`memory_total` is the guest's own limit.
`disk_used` / `diskUsed`	`u64`	Disk in use, bytes.
`disk_total` / `diskTotal`	`u64`	Disk size, bytes.
`disk_limited` / `diskLimited`	`bool`	`disk_total` is the guest's own disk.

`DiskOnHost` record#

What a Space costs this computer's disk, as opposed to what the guest sees.

Field	Type	Description
`bytes`	`Option<u64>`	Bytes only this Space holds (what deleting it frees); absent when they could not be measured.
`allocated`	`u64`	Blocks its files occupy, clones counted in full: an upper bound.
`shares_space` / `sharesSpace`	`bool`	Part of it is shared with other copies.

`DiskWarning` record#

The low-disk signal for the app and the menu bar.

Field	Type	Description
`level`	`DiskLevel`	How low it is.
`free`	`u64`	Free bytes on the volume that holds Spaces.
`total`	`u64`	Size of that volume.
`threshold`	`u64`	The line that was crossed (0 when `ok`).

`DiskLevel` enum#

How low the free disk is.

DiskLevel.OK
DiskLevel.LOW
DiskLevel.CRITICAL

Variant	Description
`Ok`	Plenty.
`Low`	Under 50 GB or 15% of the volume, whichever line is higher (the line never rises above 100 GB).
`Critical`	Under the floor where creating a Space already fails (5 GiB).

`ResourcesUpdate` record#

What changed since the last event: only entries that moved by more than 1 point or 256 MB. Replace entries by id; drop the removed ids.

Field	Type	Description
`sequence`	`u64`	The sample it brings you to.
`sampled_at_ms` / `sampledAtMs`	`u64`	Unix ms.
`this_mac` / `thisMac`	`Option<ComputerResources>`	This Mac, when it changed.
`spaces`	`Vec<SpaceResources>`	Extra Spaces that changed or appeared.
`computers`	`Vec<ComputerResources>`	Other computers that changed or appeared.
`removed`	`Vec<String>`	Ids (Spaces or computers) that are gone.

`ResourcesEvent` enum#

What Spaces.watch_resources reports.

ResourcesEvent.SNAPSHOT(snapshot: ResourcesSnapshot)
ResourcesEvent.UPDATE(update: ResourcesUpdate)
ResourcesEvent.LOW_DISK(warning: DiskWarning)

Variant	Description
`Snapshot`	Everything, at the start (and again after a reconnect). Fields: `snapshot: ResourcesSnapshot`
`Update`	Only what changed. Fields: `update: ResourcesUpdate`
`LowDisk`	The low-disk level changed (including back to `ok`). Fields: `warning: DiskWarning`

`ResourcesListener`#

Receives ResourcesEvents from Spaces.watch_resources, in order. Called on an SDK worker thread; return quickly.

You implement ResourcesListener and pass it to the SDK (a callback interface): subclass it in Python, implement the interface in TypeScript, the ResourcesListener protocol in Swift, the interface in Kotlin and the trait in Rust.

Method	Description
`on_event`	Something moved.

`ResourcesListener.on_event`#

Something moved.

def on_event(self, event: ResourcesEvent) -> None

Parameter	Type	Default
`event`	`ResourcesEvent`	required

`ResourcesWatch`#

A running Spaces.watch_resources: tell it whether a window shows the numbers, and stop it when done. Dropping it also stops it.

Returned by Spaces.watch_resources.

Method	Description
`set_visible`	Whether a window shows the numbers: visible watchers are sampled every 10 seconds, hidden ones every 5 minutes (and still hear `LowDisk`, for the menu bar).

Accessor	Returns	Description
`stop()`		Ends the watch. No event is delivered after this returns.

`ResourcesWatch.set_visible`#

Whether a window shows the numbers: visible watchers are sampled every 10 seconds, hidden ones every 5 minutes (and still hear LowDisk, for the menu bar).

def set_visible(self, visible: bool) -> None

Parameter	Type	Default
`visible`	`bool`	required

All items#

11 items, across this page and its subpages, grouped by page (each item's section is on its page). Methods are listed on their object.

Processor, memory and disk: ComputerResources, DiskLevel, DiskOnHost, DiskWarning, GuestUsage, ResourcesEvent, ResourcesListener, ResourcesSnapshot, ResourcesUpdate, ResourcesWatch, SpaceResources

Processor, memory and disk

Resources#

Spaces.resources#

Spaces.watch_resources#

ResourcesSnapshot record#

ComputerResources record#

SpaceResources record#

GuestUsage record#

DiskOnHost record#

DiskWarning record#

DiskLevel enum#

ResourcesUpdate record#

ResourcesEvent enum#

ResourcesListener#

ResourcesListener.on_event#

ResourcesWatch#

ResourcesWatch.set_visible#