var (
ErrInvalidPid = errors.New("cgroups: pid must be greater than 0")
ErrMountPointNotExist = errors.New("cgroups: cgroup mountpoint does not exist")
ErrInvalidFormat = errors.New("cgroups: parsing file with invalid format failed")
ErrFreezerNotSupported = errors.New("cgroups: freezer cgroup not supported on this system")
ErrMemoryNotSupported = errors.New("cgroups: memory cgroup not supported on this system")
ErrCgroupDeleted = errors.New("cgroups: cgroup deleted")
ErrNoCgroupMountDestination = errors.New("cgroups: cannot find cgroup mount destination")
)
var (
// ErrIgnoreSubsystem allows the specific subsystem to be skipped
ErrIgnoreSubsystem = errors.New("skip subsystem")
// ErrDevicesRequired is returned when the devices subsystem is required but
// does not exist or is not active
ErrDevicesRequired = errors.New("devices subsystem is required")
)
ErrControllerNotActive is returned when a controller is not supported or enabled
var ErrControllerNotActive = errors.New("controller is not supported")
func AllowAny(_ Subsystem, _ Path, _ error) error
AllowAny allows any subsystem errors to be skipped
func IgnoreModules(names ...string) func(*memoryController)
IgnoreModules configure the memory controller to not read memory metrics for some module names (e.g. passing "memsw" would avoid all the memory.memsw.* entries)
func IgnoreNotExist(err error) error
IgnoreNotExist ignores any errors that are for not existing files
func NewBlkio(root string, options ...func(controller *blkioController)) *blkioController
NewBlkio returns a Blkio controller given the root folder of cgroups. It may optionally accept other configuration options, such as ProcRoot(path)
func NewCpu(root string) *cpuController
func NewCpuacct(root string) *cpuacctController
func NewCpuset(root string) *cpusetController
func NewDevices(root string) *devicesController
func NewFreezer(root string) *freezerController
func NewHugetlb(root string) (*hugetlbController, error)
func NewMemory(root string, options ...func(*memoryController)) *memoryController
NewMemory returns a Memory controller given the root folder of cgroups. It may optionally accept other configuration options, such as IgnoreModules(...)
func NewNamed(root string, name Name) *namedController
func NewNetCls(root string) *netclsController
func NewNetPrio(root string) *netprioController
func NewPids(root string) *pidsController
func NewRdma(root string) *rdmaController
func OptionalSwap() func(*memoryController)
OptionalSwap allows the memory controller to not fail if cgroups is not accounting Swap memory (there are no memory.memsw.* entries)
func ParseCgroupFile(path string) (map[string]string, error)
ParseCgroupFile parses the given cgroup file, typically /proc/self/cgroup or /proc/<pid>/cgroup, into a map of subsystems to cgroup paths, e.g.
"cpu": "/user.slice/user-1000.slice" "pids": "/user.slice/user-1000.slice"
etc.
The resulting map does not have an element for cgroup v2 unified hierarchy. Use ParseCgroupFileUnified to get the unified path.
func ParseCgroupFileUnified(path string) (map[string]string, string, error)
ParseCgroupFileUnified returns legacy subsystem paths as the first value, and returns the unified path as the second value.
func ProcRoot(path string) func(controller *blkioController)
ProcRoot overrides the default location of the "/proc" filesystem
func RequireDevices(s Subsystem, _ Path, _ error) error
RequireDevices requires the device subsystem but no others
func RootPath(subsystem Name) (string, error)
func RunningInUserNS() bool
RunningInUserNS detects whether we are currently running in a user namespace. Copied from github.com/lxc/lxd/shared/util.go
CGMode is the cgroups mode of the host system
type CGMode int
const (
// Unavailable cgroup mountpoint
CGMode = iota
// Legacy cgroups v1
Legacy
// Hybrid with cgroups v1 and v2 controllers mounted
Hybrid
// Unified with only cgroups v2 mounted
Unified
)
func Mode() CGMode
Mode returns the cgroups mode running on the host
Cgroup handles interactions with the individual groups to perform actions on them as them main interface to this cgroup package
type Cgroup interface {
// New creates a new cgroup under the calling cgroup
New(string, *specs.LinuxResources) (Cgroup, error)
// Add adds a process to the cgroup (cgroup.procs). Without additional arguments,
// the process is added to all the cgroup subsystems. When giving Add a list of
// subsystem names, the process is only added to those subsystems, provided that
// they are active in the targeted cgroup.
Add(Process, ...Name) error
// AddProc adds the process with the given id to the cgroup (cgroup.procs).
// Without additional arguments, the process with the given id is added to all
// the cgroup subsystems. When giving AddProc a list of subsystem names, the process
// id is only added to those subsystems, provided that they are active in the targeted
// cgroup.
AddProc(uint64, ...Name) error
// AddTask adds a process to the cgroup (tasks). Without additional arguments, the
// task is added to all the cgroup subsystems. When giving AddTask a list of subsystem
// names, the task is only added to those subsystems, provided that they are active in
// the targeted cgroup.
AddTask(Process, ...Name) error
// Delete removes the cgroup as a whole
Delete() error
// MoveTo moves all the processes under the calling cgroup to the provided one
// subsystems are moved one at a time
MoveTo(Cgroup) error
// Stat returns the stats for all subsystems in the cgroup
Stat(...ErrorHandler) (*v1.Metrics, error)
// Update updates all the subsystems with the provided resource changes
Update(resources *specs.LinuxResources) error
// Processes returns all the processes in a select subsystem for the cgroup
Processes(Name, bool) ([]Process, error)
// Tasks returns all the tasks in a select subsystem for the cgroup
Tasks(Name, bool) ([]Task, error)
// Freeze freezes or pauses all processes inside the cgroup
Freeze() error
// Thaw thaw or resumes all processes inside the cgroup
Thaw() error
// OOMEventFD returns the memory subsystem's event fd for OOM events
OOMEventFD() (uintptr, error)
// RegisterMemoryEvent returns the memory subsystems event fd for whatever memory event was
// registered for. Can alternatively register for the oom event with this method.
RegisterMemoryEvent(MemoryEvent) (uintptr, error)
// State returns the cgroups current state
State() State
// Subsystems returns all the subsystems in the cgroup
Subsystems() []Subsystem
}
func Load(hierarchy Hierarchy, path Path, opts ...InitOpts) (Cgroup, error)
Load will load an existing cgroup and allow it to be controlled All static path should not include `/sys/fs/cgroup/` prefix, it should start with your own cgroups name
func New(hierarchy Hierarchy, path Path, resources *specs.LinuxResources, opts ...InitOpts) (Cgroup, error)
New returns a new control via the cgroup cgroups interface
ErrorHandler is a function that handles and acts on errors
type ErrorHandler func(err error) error
EventNotificationMode corresponds to the notification modes for the memory cgroups pressure level notifications.
type EventNotificationMode string
There are three optional modes that specify different propagation behavior:
const (
DefaultMode EventNotificationMode = "default"
LocalMode EventNotificationMode = "local"
HierarchyMode EventNotificationMode = "hierarchy"
)
Hierarchy enables both unified and split hierarchy for cgroups
type Hierarchy func() ([]Subsystem, error)
func SingleSubsystem(baseHierarchy Hierarchy, subsystem Name) Hierarchy
SingleSubsystem returns a single cgroup subsystem within the base Hierarchy
InitCheck allows subsystems errors to be checked when initialized or loaded
type InitCheck func(Subsystem, Path, error) error
InitConfig provides configuration options for the creation or loading of a cgroup and its subsystems
type InitConfig struct {
// InitCheck can be used to check initialization errors from the subsystem
InitCheck InitCheck
}
InitOpts allows configuration for the creation or loading of a cgroup
type InitOpts func(*InitConfig) error
MemoryEvent is an interface that V1 memory Cgroup notifications implement. Arg returns the file name whose fd should be written to "cgroups.event_control". EventFile returns the name of the file that supports the notification api e.g. "memory.usage_in_bytes".
type MemoryEvent interface {
Arg() string
EventFile() string
}
func MemoryPressureEvent(pressureLevel MemoryPressureLevel, hierarchy EventNotificationMode) MemoryEvent
MemoryPressureEvent returns a new memory pressure event to be used with RegisterMemoryEvent.
func MemoryThresholdEvent(threshold uint64, swap bool) MemoryEvent
MemoryThresholdEvent returns a new memory threshold event to be used with RegisterMemoryEvent. If swap is true, the event will be registered using memory.memsw.usage_in_bytes
func OOMEvent() MemoryEvent
OOMEvent returns a new oom event to be used with RegisterMemoryEvent.
MemoryPressureLevel corresponds to the memory pressure levels defined for memory cgroups.
type MemoryPressureLevel string
The three memory pressure levels are as follows.
const (
LowPressure MemoryPressureLevel = "low"
MediumPressure MemoryPressureLevel = "medium"
CriticalPressure MemoryPressureLevel = "critical"
)
Name is a typed name for a cgroup subsystem
type Name string
const (
Devices Name = "devices"
Hugetlb Name = "hugetlb"
Freezer Name = "freezer"
Pids Name = "pids"
NetCLS Name = "net_cls"
NetPrio Name = "net_prio"
PerfEvent Name = "perf_event"
Cpuset Name = "cpuset"
Cpu Name = "cpu"
Cpuacct Name = "cpuacct"
Memory Name = "memory"
Blkio Name = "blkio"
Rdma Name = "rdma"
)
const (
SystemdDbus Name = "systemd"
)
func Subsystems() []Name
Subsystems returns a complete list of the default cgroups available on most linux systems
type Path func(subsystem Name) (string, error)
func NestedPath(suffix string) Path
NestedPath will nest the cgroups based on the calling processes cgroup placing its child processes inside its own path
func PidPath(pid int) Path
PidPath will return the correct cgroup paths for an existing process running inside a cgroup This is commonly used for the Load function to restore an existing container
func Slice(slice, name string) Path
func StaticPath(path string) Path
StaticPath returns a static path to use for all cgroups
type PerfEventController struct {
// contains filtered or unexported fields
}
func NewPerfEvent(root string) *PerfEventController
func (p *PerfEventController) Name() Name
func (p *PerfEventController) Path(path string) string
type Process struct {
// Subsystem is the name of the subsystem that the process / task is in.
Subsystem Name
// Pid is the process id of the process / task.
Pid int
// Path is the full path of the subsystem and location that the process / task is in.
Path string
}
State is a type that represents the state of the current cgroup
type State string
const (
Unknown State = ""
Thawed State = "thawed"
Frozen State = "frozen"
Freezing State = "freezing"
Deleted State = "deleted"
)
type Subsystem interface {
Name() Name
}
func Systemd() ([]Subsystem, error)
func V1() ([]Subsystem, error)
V1 returns all the groups in the default cgroups mountpoint in a single hierarchy
type SystemdController struct {
// contains filtered or unexported fields
}
func NewSystemd(root string) (*SystemdController, error)
func (s *SystemdController) Create(path string, _ *specs.LinuxResources) error
func (s *SystemdController) Delete(path string) error
func (s *SystemdController) Name() Name
type Task = Process