Package: internal/runtime/cgroup

package cgroup Import Path internal/runtime/cgroup (on go.dev) Dependency Relation imports 4 packages, and imported by one package

Involved Source Files cgroup_linux.go line_reader.go runtime.go

Package-Level Type Names (total 4, in which 2 are exported)

/* sort exporteds by: alphabet | popularity */

type CPU (struct) CPU owns the FDs required to read the CPU limit from a cgroup. Fields (total 3, none are exported) /* 3 unexporteds ... *//* 3 unexporteds: */ periodFD int For cgroup v1, this is cpu.cfs_period_us. For cgroup v2, this is unused. quotaFD int For cgroup v1, this is cpu.cfs_quota_us. For cgroup v2, this is cpu.max. version Version Methods (only one, which is exported) ( CPU) Close() As Outputs Of (at least one exported) func OpenCPU(scratch []byte) (CPU, error) As Inputs Of (at least 2, in which 1 is exported) func ReadCPULimit(c CPU) (float64, bool, error) /* at least one unexported ... *//* at least one unexported: */ func runtime.adjustCgroupGOMAXPROCS(procs int32, cpu CPU) int32 As Types Of (only one, which is unexported) /* one unexported ... *//* one unexported: */ var runtime.cgroupCPU

type Version int (basic type) Version indicates the cgroup version. As Outputs Of (at least 3, in which 2 are exported) func FindCPU(out []byte, scratch []byte) (int, Version, error) func FindCPURelativePath(out []byte, scratch []byte) (int, Version, error) /* at least one unexported ... *//* at least one unexported: */ func parseCPURelativePath(fd int, read func(fd int, b []byte) (int, uintptr), out []byte, scratch []byte) (int, Version, error) As Types Of (total 3, all are exported) const V1 const V2 const VersionUnknown

/* 2 unexporteds ... *//* 2 unexporteds: */

type lineReader (struct) lineReader reads line-by-line using only a single fixed scratch buffer. When a single line is too long for the scratch buffer, the remainder of the line will be skipped. Fields (total 6, none are exported) /* 6 unexporteds ... *//* 6 unexporteds: */ eof bool // read reached EOF. fd int n int // bytes of scratch in use. newline int // index of the first newline in scratch. read func(fd int, b []byte) (int, uintptr) scratch []byte Methods (total 2, neither is exported) /* 2 unexporteds ... *//* 2 unexporteds: */ (*lineReader) line() []byte line returns a view of the current line, excluding the trailing newline. If [r.next] returned errIncompleteLine, then this returns only the beginning of the line. Preconditions: [r.next] is called prior to the first call to line. Postconditions: The caller must not keep a reference to the returned slice. (*lineReader) next() error next advances to the next line. May return errIncompleteLine if the scratch buffer is too small to hold the entire line, in which case [r.line] will return the beginning of the line. A subsequent call to next will skip the remainder of the incomplete line. N.B. this behavior is important for /proc/self/mountinfo. Some lines (mounts), such as overlayfs, may be extremely long due to long super-block options, but we don't care about those. The mount type will appear early in the line. Returns errEOF when there are no more lines. As Outputs Of (at least one unexported) /* at least one unexported ... *//* at least one unexported: */ func newLineReader(fd int, scratch []byte, read func(fd int, b []byte) (n int, errno uintptr)) *lineReader

type stringError string (basic type) stringError is a trival implementation of error, equivalent to errors.New, which cannot be imported from a runtime package. Methods (only one, which is exported) ( stringError) Error() string Implements (at least one exported) stringError : error

Package-Level Functions (total 16, in which 5 are exported)

func FindCPU(out []byte, scratch []byte) (int, Version, error) FindCPU finds the path to the CPU cgroup that this process is a member of and places it in out. scratch is a scratch buffer for internal use. out must have length PathSize. scratch must have length ParseSize. Returns the number of bytes written to out and the cgroup version (1 or 2). Returns ErrNoCgroup if the process is not in a CPU cgroup.

func FindCPUMountPoint(out []byte, scratch []byte) (int, error) FindCPUMountPoint finds the root of the CPU cgroup mount places it in out. scratch is a scratch buffer for internal use. out must have length PathSize. scratch must have length ParseSize. Returns the number of bytes written to out. Returns ErrNoCgroup if the process is not in a CPU cgroup.

func FindCPURelativePath(out []byte, scratch []byte) (int, Version, error) FindCPURelativePath finds the path to the CPU cgroup that this process is a member of relative to the root of the cgroup mount and places it in out. scratch is a scratch buffer for internal use. out must have length PathSize minus the size of the cgroup mount root (if known). scratch must have length ParseSize. Returns the number of bytes written to out and the cgroup version (1 or 2). Returns ErrNoCgroup if the process is not in a CPU cgroup.

func OpenCPU(scratch []byte) (CPU, error) OpenCPU returns a CPU for the CPU cgroup containing the current process, or ErrNoCgroup if the process is not in a CPU cgroup. scratch must have length ScratchSize.

func ReadCPULimit(c CPU) (float64, bool, error) Returns average CPU throughput limit from the cgroup, or ok false if there is no limit.

/* 11 unexporteds ... *//* 11 unexporteds: */

func checkBufferSize(s []byte, size int)

func containsCPU(b []byte) bool Returns true if comma-separated list b contains "cpu".

func newLineReader(fd int, scratch []byte, read func(fd int, b []byte) (n int, errno uintptr)) *lineReader newLineReader returns a lineReader which reads lines from fd. fd is the file descriptor to read from. scratch is the scratch buffer to read into. Note that len(scratch) is the longest line that can be read. Lines longer than len(scratch) will have the remainder of the line skipped. See next for more details. read is the function used to read more bytes from fd. This is usually internal/runtime/syscall.Read. Note that this follows syscall semantics (not io.Reader), so EOF is indicated with n=0, errno=0.

func parseCPUMount(fd int, read func(fd int, b []byte) (int, uintptr), out []byte, scratch []byte) (int, error) Returns the mount point for the cpu cgroup controller (v1 or v2) from /proc/self/mountinfo.

func parseCPURelativePath(fd int, read func(fd int, b []byte) (int, uintptr), out []byte, scratch []byte) (int, Version, error) Finds the path of the current process's CPU cgroup relative to the cgroup mount and writes it to out. Returns the number of bytes written and the cgroup version (1 or 2).

func parseV1Number(buf []byte) (int64, error)

func parseV2Limit(buf []byte) (float64, bool, error)

func readV1Number(fd int) (int64, error) Returns the value from the quota/period file.

func readV2Limit(fd int) (float64, bool, error) Returns CPU throughput limit, or ok false if there is no limit.

func throw(s string)

func unescapePath(out []byte, in []byte) (int, error) unescapePath copies in to out, unescaping escape sequences generated by Linux's show_path. That is, '\', ' ', '\t', and '\n' are converted to octal escape sequences, like '\040' for space. out must be at least as large as in. Returns the number of bytes written to out. Also see escapePath in cgroup_linux_test.go.

Package-Level Variables (total 6, in which 1 is exported)

var ErrNoCgroup error

/* 5 unexporteds ... *//* 5 unexporteds: */

var errEOF error Reached EOF.

var errIncompleteLine error The entire line did not fit into the scratch buffer.

var errInvalidEscape error

var errMalformedFile error

var errSyscallFailed error A system call failed.

Package-Level Constants (total 11, in which 6 are exported)

const ParseSize = 65536 Required space to parse /proc/self/mountinfo and /proc/self/cgroup. See findCPUMount and findCPURelativePath.

const PathSize = 4096 Required space to store a path of the cgroup in the filesystem.

const ScratchSize = 69632 Required amount of scratch space for CPULimit. TODO(prattmic): This is shockingly large (~70KiB) due to the (very unlikely) combination of extremely long paths consisting mostly escaped characters. The scratch buffer ends up in .bss in package runtime, so it doesn't contribute to binary size and generally won't be faulted in, but it would still be nice to shrink this. A more complex parser that did not need to keep entire lines in memory could get away with much less. Alternatively, we could do a one-off mmap allocation for this buffer, which is only mapped larger if we actually need the extra space.

const V1 Version = 1

const V2 Version = 2

const VersionUnknown Version = 0

/* 5 unexporteds ... *//* 5 unexporteds: */

const _PATH_MAX = 4096

const escapedPathMax = 16384 /proc/self/mountinfo path escape sequences are 4 characters long, so a path consisting entirely of escaped characters could be 4 times larger.

const v1PeriodFile = "/cpu.cfs_period_us\x00" Include explicit NUL to be sure we include it in the slice.

const v1QuotaFile = "/cpu.cfs_quota_us\x00" Include explicit NUL to be sure we include it in the slice.

const v2MaxFile = "/cpu.max\x00" Include explicit NUL to be sure we include it in the slice.