runtimebp

Documentation

Overview

Package runtimebp provides extensions to the stdlib runtime package.

Index

• Constants
• Variables
• func GOMAXPROCS(min, max int) (oldVal, newVal int)
• func GOMAXPROCSwithFormula(min, max int, formula MaxProcsFormula) (oldVal, newVal int)
• func GetFirstIPv4() (string, error)
• func HandleShutdown(ctx context.Context, handler ShutdownHandler, signals ...os.Signal)
• func InitFromConfig(_ Config)
• func NumCPU() float64
• type Config
• type MaxProcsFormula
• type ShutdownHandler

Constants

const UndefinedIP = "undefined"

UndefinedIP is used when we fail to get the ip address of this machine.

Variables

var ErrNoIPv4Found = errors.New("runtimebp: no IPv4 ip found")

ErrNoIPv4Found is an error could be returned by GetFirstIPv4 when we can't find any non-loopback IPv4 addresses on this machine.

Functions

func GOMAXPROCS

func GOMAXPROCS(min, max int) (oldVal, newVal int)

GOMAXPROCS sets runtime.GOMAXPROCS with the default formula, in bound of [min, max].

Currently the default formula is NumCPU() rounding up.

Deprecated: GOMAXPROCS is deprecated. Instead, tune GOMAXPROCS as described in runtimebp.InitFromConfig.

func GOMAXPROCSwithFormula

func GOMAXPROCSwithFormula(min, max int, formula MaxProcsFormula) (oldVal, newVal int)

GOMAXPROCSwithFormula sets runtime.GOMAXPROCS with the given formula, in bound of [min, max].

Deprecated: GOMAXPROCSwithFormula is deprecated. Instead, tune GOMAXPROCS as described in runtimebp.InitFromConfig.

func GetFirstIPv4

func GetFirstIPv4() (string, error)

GetFirstIPv4 returns the first local IPv4 address that's not a loopback.

func HandleShutdown

func HandleShutdown(ctx context.Context, handler ShutdownHandler, signals ...os.Signal)

HandleShutdown register a handler to do cleanups for a graceful shutdown.

This function blocks until the ctx passed in is cancelled, or a signal happens, whichever comes first. So it should usually be started in its own goroutine.

Baseplate services should use baseplate.Serve which will manage this for you rather than using HandleShutdown directly.

SIGTERM, as specified in https://kubernetes.io/docs/concepts/workloads/pods/pod/#termination-of-pods, and os.Interrupt as for handling ^C in command line, are always registered in this function and there's no need to pass them in (but passing them in won't cause any harm), the signals vararg is for any additional signals you wish to handle.

func InitFromConfig

func InitFromConfig(_ Config)

InitFromConfig configures the runtime's GOMAXPROCS using the following heuristic:

1. If $GOMAXPROCS is set, it relinquishes control to the Go runtime. This should cause the runtime to respect this value directly.
2. If $BASEPLATE_CPU_REQUEST is unset/invalid, it relinquishes control to automaxprocs, minimum 2. See https://pkg.go.dev/go.uber.org/automaxprocs for specific behavior.
3. Otherwise, $BASEPLATE_CPU_REQUEST is multiplied by $BASEPLATE_CPU_REQUEST_SCALE (or defaultCPURequestScale) to compute the new GOMAXPROCS, minimum 2.

InitFromConfig also exports several metrics to facilitate further tuning/analysis.

NOTE: It does NOT respect the passed-in config.

func NumCPU

func NumCPU() float64

NumCPU returns the number of CPUs assigned to this running container.

This is the container aware version of runtime.NumCPU. It reads from the cgroup v2 cpu.max values to determine the hard CPU limit of the container.

If the current process is not running with cgroup v2, it falls back to read from the cgroup v1 cpu.cfs_quota_us and cpu.cfs_period_us values. If the current process is not running inside a container, or if there's no limit set in cgroup, it will fallback to runtime.NumCPU() instead.

Depending on your application, $BASEPLATE_CPU_REQUEST may also be helpful. Infrared sets $BASEPLATE_CPU_REQUEST to the container's Kubernetes CPU _request_ (rather than _limit_ as this function returns), rounded up to the nearest whole CPU.

To tune GOMAXPROCS, see runtimebp.InitFromConfig.

Types

type Config

type Config struct {
	// Deprecated: No-op for now, will be removed in a future release.
	NumProcesses struct {
		// Deprecated: Always overridden to math.MaxInt.
		Max int `yaml:"max"`

		// Deprecated: Always overridden to 1.
		Min int `yaml:"min"`
	} `yaml:"numProcesses"`
}

Config is the configuration struct for the runtimebp package.

Can be parsed from YAML.

type MaxProcsFormula

type MaxProcsFormula func(n float64) int

MaxProcsFormula is the function to calculate GOMAXPROCS based on NumCPU value passed in.

type ShutdownHandler

type ShutdownHandler func(signal os.Signal)

ShutdownHandler is the callback type used in HandleSignals.