# `Sys.Linux.Cgroup.V2.CpuStat`
[🔗](https://github.com/harmont-dev/hyper/blob/main/lib/sys/linux/cgroup/v2/cpu_stat.ex#L1)

Reads a cgroup v2 `cpu.stat` interface file — the cumulative CPU time the
cgroup's processes have actually executed since the cgroup was created.

`usage_usec` only advances while a process in the cgroup is on-CPU, so an
idle cgroup's counter stands still: it measures compute *performed*, not
compute allocated. A single reading is meaningless on its own; consumption
over a window is the delta between two readings (see
`Hyper.Node.FireVMM.Meter`).

Laws under test: a rendered payload round-trips `usage_usec`/`user_usec`/
`system_usec` regardless of line order or unknown lines; a payload without
`usage_usec` is always refused.

# `t`

```elixir
@type t() :: %Sys.Linux.Cgroup.V2.CpuStat{
  system: Unit.Time.t(),
  usage: Unit.Time.t(),
  user: Unit.Time.t()
}
```

# `parse`

```elixir
@spec parse(String.t()) :: {:ok, t()} | {:error, :missing_usage}
```

Parse a `cpu.stat` payload. Refuses a payload without a well-formed
`usage_usec` — the billing counter must never silently read as zero.

# `read`

```elixir
@spec read(Path.t()) :: {:ok, t()} | {:error, File.posix() | :missing_usage}
```

Read and parse `<cgroup_dir>/cpu.stat`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*