Single-shot declarative reconciliation for a cgroup's resource limits — observe the interface files, diff against a desired set of knobs, apply once, and return what happened.

This is the mechanism half of declarative cgroups: caller-driven, holds no long-lived state, owns no process. The long-lived loop is the opt-in Linx.Reconcile; the cadence and persistence are a consumer's. Linx.Cgroup stays pure primitives — this module composes Linx.Cgroup.read/2 and write/3 into the observe → diff → converge triad.

Limits only — existence and membership stay in the composite

This reconciles the limit knobs of one already-existing cgroup (memory.max, pids.max, cpu.max, cpu.weight, memory.high, …) — the drift-prone, observable, value-shaped state. It deliberately does not create or destroy the cgroup, enable controllers, or move processes: that is lifecycle, owned by the consumer's composite and torn down with it (see the reconcile design notes, §5). If the cgroup or a controller's interface file is absent, the corresponding write simply lands in report.failed; the next pass retries once the composite has set it up.

This is "sysctl-with-hierarchy" — a flat %{interface_file => value} map against one cgroup path — so it mirrors Linx.Sysctl.Reconcile exactly, including the three-way last_applied ownership and the best-effort strategy.

Desired state

A map from interface-file name to the value you want, using the same value shapes the Linx.Cgroup setters accept:

%{
  "memory.max" => 256 * 1024 * 1024,   # bytes, or :max to clear
  "pids.max" => 100,                    # count, or :max
  "cpu.max" => {50_000, 100_000},       # {quota_us, period_us}, or :max
  "cpu.weight" => 200                    # 1..10000
}

Values are integers, the atom :max (clear the limit), a {quota, period} tuple (for cpu.max), or a raw binary (escape hatch for any other knob).

last_applied — three-way ownership

Threaded between passes, never persisted — see Linx.Sysctl.Reconcile for the full rationale (it captures live pre-management values that die with the node). It is a map:

%{file => %{applied: value_we_wrote, original: raw_value_before_we_touched_it}}

When a file leaves the desired set it is released:

• default — left at its current value, reported {:release, file} (we simply stop managing it);
• with revert_on_release: true — the captured :original raw string is written back, reported {:revert, file, original}.

Strategy

cgroup limit writes are independent per file, so a pass is best-effort: every op is attempted, and any that fail collect in report.failed without starving the others. The next pass re-converges anything still wrong.

Example

{:ok, cg} = Linx.Cgroup.create("/sys/fs/cgroup/myorg/web-42")
:ok = Linx.Cgroup.enable_controllers("/sys/fs/cgroup/myorg", [:memory, :pids])

desired = %{"memory.max" => 256 * 1024 * 1024, "pids.max" => 100}

{:ok, r} = Linx.Cgroup.Reconcile.reconcile(cg, desired)
r.converged?
{:ok, r2} = Linx.Cgroup.Reconcile.reconcile(cg, desired, r.last_applied)  # idempotent