Documentation
¶
Overview ¶
Package cgroup provides a thin helper for placing a child process under a cgroup v2 group with CPU quota and I/O weight limits. Linux-only.
This is a building block for resource-throttled child supervision; the runner (internal/agent) does NOT consume it automatically yet. Callers pass an existing PID to AddPID after starting the child, then configure the relevant controller files. On child exit, call Remove to delete the cgroup directory.
Requirements:
- cgroup v2 unified hierarchy (Linux 4.5+; ubiquitous on systemd hosts).
- Write access to the parent cgroup directory. This typically means either running under a delegated subtree (e.g. via a systemd `Delegate=yes` user slice) or as root.
Errors:
- ErrUnsupportedPlatform: returned by every constructor on non-Linux.
- ErrCgroupV2Unavailable: cgroup v2 not mounted at /sys/fs/cgroup, or the parent path does not exist.
- ErrPermission: filesystem permission denied (typically: not running under a delegated subtree).
Index ¶
Constants ¶
const DefaultMountPoint = "/sys/fs/cgroup"
DefaultMountPoint is the conventional cgroup v2 unified-hierarchy mount.
Variables ¶
var ( ErrUnsupportedPlatform = errors.New("cgroup: unsupported platform (Linux only)") ErrPermission = errors.New("cgroup: permission denied (run under a delegated subtree or as root)") )
Sentinel errors.
Functions ¶
This section is empty.
Types ¶
type CPUMax ¶
type CPUMax struct {
Quota int64 // microseconds; 0 = no limit
Period int64 // microseconds; defaults to 100_000 (100ms) on the kernel side
}
CPUMax describes a CPU quota for a cgroup. The kernel format is "<quota> <period>" where quota is microseconds-of-CPU per period microseconds-of-wall-clock. Setting Quota=0 produces "max <period>" (no limit).
type Group ¶
type Group struct {
// Path is the absolute filesystem path to the cgroup directory,
// e.g. /sys/fs/cgroup/cliwrap/proc-123.
Path string
}
Group is a handle to a single cgroup directory. Methods write to the kernel-exposed control files under that directory.
func New ¶
New creates a new cgroup directory under parent (e.g. /sys/fs/cgroup/user.slice/user-1000.slice/user@1000.service/cliwrap.slice) with the given subgroup name. The parent directory must already exist and be writeable by the caller.
Returns ErrCgroupV2Unavailable if the unified hierarchy is not mounted or the parent path is missing; ErrPermission on filesystem permission errors; or a wrapped error for other failures.
func (*Group) AddPID ¶
AddPID places pid into this cgroup by writing it to cgroup.procs. Subsequent threads of pid follow it automatically (cgroup v2 process migration semantics).
func (*Group) Remove ¶
Remove deletes the cgroup directory. The kernel rejects rmdir on a non-empty cgroup (i.e. while it still contains processes); callers must wait for the contained processes to exit before calling Remove.
func (*Group) SetCPUMax ¶
SetCPUMax writes the cpu.max controller file. Quota=0 is interpreted as "max" (no limit). Period defaults to 100_000 µs when zero.
func (*Group) SetIOWeight ¶
SetIOWeight writes io.weight (1..10000; default 100). Values outside the kernel-accepted range surface as a wrapped write error.
func (*Group) SetMemoryMax ¶
SetMemoryMax writes the memory.max controller file. A zero value writes "max" (no limit).
Source Files