cgroups

README

cgroups

Go package for creating, managing, inspecting, and destroying cgroups. The resources format for settings on the cgroup uses the OCI runtime-spec found here.

Examples

Create a new cgroup

This creates a new cgroup using a static path for all subsystems under /test.

• /sys/fs/cgroup/cpu/test
• /sys/fs/cgroup/memory/test
• etc....

It uses a single hierarchy and specifies cpu shares as a resource constraint and uses the v1 implementation of cgroups.

shares := uint64(100)
control, err := cgroups.New(cgroups.V1, cgroups.StaticPath("/test"), &specs.LinuxResources{
    CPU: &specs.CPU{
        Shares: &shares,
    },
})
defer control.Delete()

Create with systemd slice support

control, err := cgroups.New(cgroups.Systemd, cgroups.Slice("system.slice", "runc-test"), &specs.LinuxResources{
    CPU: &specs.CPU{
        Shares: &shares,
    },
})

Load an existing cgroup

control, err = cgroups.Load(cgroups.V1, cgroups.StaticPath("/test"))

Add a process to the cgroup

if err := control.Add(cgroups.Process{Pid:1234}); err != nil {
}

Update the cgroup

To update the resources applied in the cgroup

shares = uint64(200)
if err := control.Update(&specs.LinuxResources{
    CPU: &specs.CPU{
        Shares: &shares,
    },
}); err != nil {
}

Freeze and Thaw the cgroup

if err := control.Freeze(); err != nil {
}
if err := control.Thaw(); err != nil {
}

List all processes in the cgroup or recursively

processes, err := control.Processes(cgroups.Devices, recursive)

Get Stats on the cgroup

stats, err := control.Stat()

Move process across cgroups

This allows you to take processes from one cgroup and move them to another.

err := control.MoveTo(destination)

Create subcgroup

subCgroup, err := control.New("child", resources)

LICENSE

Copyright (c) 2016-2017 Michael Crosby. crosbymichael@gmail.com

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Documentation

Index

• Variables
• func IgnoreNotExist(err error) error
• func NewBlkio(root string) *blkioController
• func NewCpu(root string) *cpuController
• func NewCpuacct(root string) *cpuacctController
• func NewCputset(root string) *cpusetController
• func NewDevices(root string) *devicesController
• func NewFreezer(root string) *freezerController
• func NewHugetlb(root string) (*hugetlbController, error)
• func NewMemory(root string) *memoryController
• func NewNamed(root string, name Name) *namedController
• func NewNetCls(root string) *netclsController
• func NewNetPrio(root string) *netprioController
• func NewPids(root string) *pidsController
• func RootPath(subsysem Name) (string, error)
• type BlkioEntry
• type BlkioStat
• type Cgroup
  • func Load(hierarchy Hierarchy, path Path) (Cgroup, error)
  • func New(hierarchy Hierarchy, path Path, resources *specs.LinuxResources) (Cgroup, error)
• type CpuStat
• type CpuUsage
• type ErrorHandler
• type Hierarchy
  • func SingleSubsystem(baseHierarchy Hierarchy, subsystem Name) Hierarchy
• type HugetlbStat
• type MemoryEntry
• type MemoryStat
• type Name
  • func Subsystems() []Name
• type Path
  • func NestedPath(suffix string) Path
  • func PidPath(pid int) Path
  • func StaticPath(path string) Path
• type PerfEventController
  • func NewPerfEvent(root string) *PerfEventController
  • func (p *PerfEventController) Name() Name
  • func (p *PerfEventController) Path(path string) string
• type PidsStat
• type Process
• type State
• type Stats
• type Subsystem
  • func V1() ([]Subsystem, error)
• type Throttle

Variables

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 found cgroup mount destination")
)

Functions

func IgnoreNotExist

func IgnoreNotExist(err error) error

IgnoreNotExist ignores any errors that are for not existing files

func NewBlkio

func NewBlkio(root string) *blkioController

func NewCpu

func NewCpu(root string) *cpuController

func NewCpuacct

func NewCpuacct(root string) *cpuacctController

func NewCputset

func NewCputset(root string) *cpusetController

func NewDevices

func NewDevices(root string) *devicesController

func NewFreezer

func NewFreezer(root string) *freezerController

func NewHugetlb

func NewHugetlb(root string) (*hugetlbController, error)

func NewMemory

func NewMemory(root string) *memoryController

func NewNamed

func NewNamed(root string, name Name) *namedController

func NewNetCls

func NewNetCls(root string) *netclsController

func NewNetPrio

func NewNetPrio(root string) *netprioController

func NewPids

func NewPids(root string) *pidsController

func RootPath

func RootPath(subsysem Name) (string, error)

Types

type BlkioEntry

type BlkioEntry struct {
	Op    string
	Major uint64
	Minor uint64
	Value uint64
}

type BlkioStat

type BlkioStat struct {
	IoServiceBytesRecursive []BlkioEntry
	IoServicedRecursive     []BlkioEntry
	IoQueuedRecursive       []BlkioEntry
	IoServiceTimeRecursive  []BlkioEntry
	IoWaitTimeRecursive     []BlkioEntry
	IoMergedRecursive       []BlkioEntry
	IoTimeRecursive         []BlkioEntry
	SectorsRecursive        []BlkioEntry
}

type Cgroup

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
	Add(Process) 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) (*Stats, 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)
	// 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)
	// State returns the cgroups current state
	State() State
	// Subsystems returns all the subsystems in the cgroup
	Subsystems() []Subsystem
}

Cgroup handles interactions with the individual groups to perform actions on them as them main interface to this cgroup package

func Load

func Load(hierarchy Hierarchy, path Path) (Cgroup, error)

Load will load an existing cgroup and allow it to be controlled

func New

func New(hierarchy Hierarchy, path Path, resources *specs.LinuxResources) (Cgroup, error)

New returns a new control via the cgroup cgroups interface

type CpuStat

type CpuStat struct {
	Usage      CpuUsage
	Throttling Throttle
}

type CpuUsage

type CpuUsage struct {
	// Units: nanoseconds.
	Total  uint64
	PerCpu []uint64
	Kernel uint64
	User   uint64
}

type ErrorHandler

type ErrorHandler func(err error) error

ErrorHandler is a function that handles and acts on errors

type Hierarchy

type Hierarchy func() ([]Subsystem, error)

Hierarchy enableds both unified and split hierarchy for cgroups

func SingleSubsystem

func SingleSubsystem(baseHierarchy Hierarchy, subsystem Name) Hierarchy

SingleSubsystem returns a single cgroup subsystem within the base Hierarchy

type HugetlbStat

type HugetlbStat struct {
	Usage   uint64
	Max     uint64
	Failcnt uint64
}

type MemoryEntry

type MemoryEntry struct {
	Limit   uint64
	Usage   uint64
	Max     uint64
	Failcnt uint64
}

type MemoryStat

type MemoryStat struct {
	Cache                   uint64
	RSS                     uint64
	RSSHuge                 uint64
	MappedFile              uint64
	Dirty                   uint64
	Writeback               uint64
	PgPgIn                  uint64
	PgPgOut                 uint64
	PgFault                 uint64
	PgMajFault              uint64
	InactiveAnon            uint64
	ActiveAnon              uint64
	InactiveFile            uint64
	ActiveFile              uint64
	Unevictable             uint64
	HierarchicalMemoryLimit uint64
	HierarchicalSwapLimit   uint64
	TotalCache              uint64
	TotalRSS                uint64
	TotalRSSHuge            uint64
	TotalMappedFile         uint64
	TotalDirty              uint64
	TotalWriteback          uint64
	TotalPgPgIn             uint64
	TotalPgPgOut            uint64
	TotalPgFault            uint64
	TotalPgMajFault         uint64
	TotalInactiveAnon       uint64
	TotalActiveAnon         uint64
	TotalInactiveFile       uint64
	TotalActiveFile         uint64
	TotalUnevictable        uint64

	Usage     MemoryEntry
	Swap      MemoryEntry
	Kernel    MemoryEntry
	KernelTCP MemoryEntry
}

type Name

type Name string

Name is a typed name for a cgroup subsystem

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"
)

func Subsystems

func Subsystems() []Name

Subsystems returns a complete list of the default cgroups avaliable on most linux systems

type Path

type Path func(subsystem Name) (string, error)

func NestedPath

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

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 StaticPath

func StaticPath(path string) Path

StaticPath returns a static path to use for all cgroups

type PerfEventController

type PerfEventController struct {
	// contains filtered or unexported fields
}

func NewPerfEvent

func NewPerfEvent(root string) *PerfEventController

func (*PerfEventController) Name

func (p *PerfEventController) Name() Name

func (*PerfEventController) Path

func (p *PerfEventController) Path(path string) string

type PidsStat

type PidsStat struct {
	Current uint64
	Limit   uint64
}

type Process

type Process struct {
	// Subsystem is the name of the subsystem that the process is in
	Subsystem Name
	// Pid is the process id of the process
	Pid int
	// Path is the full path of the subsystem and location that the process is in
	Path string
}

type State

type State string

State is a type that represents the state of the current cgroup

const (
	Unknown  State = ""
	Thawed   State = "thawed"
	Frozen   State = "frozen"
	Freezing State = "freezing"
	Deleted  State = "deleted"
)

type Stats

type Stats struct {
	Hugetlb map[string]HugetlbStat
	Pids    *PidsStat
	Cpu     *CpuStat
	Memory  *MemoryStat
	Blkio   *BlkioStat
	// contains filtered or unexported fields
}

type Subsystem

type Subsystem interface {
	Name() Name
}

func V1

func V1() ([]Subsystem, error)

V1 returns all the groups in the default cgroups mountpoint in a single hierarchy

type Throttle

type Throttle struct {
	Periods          uint64
	ThrottledPeriods uint64
	ThrottledTime    uint64
}