Skip to content
Tutorials Center
My learning

Topics

Go Reference ยท Concurrency and Context

The Go runtime package

Overview of Go's runtime package: GOOS and GOARCH, NumCPU, GOMAXPROCS, NumGoroutine, Gosched, GC, MemStats, Caller, Stack and Goexit, with live examples.

The runtime package is the window into Go's scheduler, garbage collector and call stack. Most programs never need it, but it answers practical questions: how many CPUs can I use, how many goroutines are alive, how much memory is allocated, and which function is calling me?

It also holds a few controls: GOMAXPROCS to cap parallelism, Gosched to yield the processor, GC to force a collection, and Goexit to end a goroutine. Treat the controls as tools for tests, tuning and diagnostics, not for everyday logic.

Go
fmt.Println(runtime.GOOS, runtime.GOARCH, runtime.Version())

Try it

Go Goroutines and the scheduler

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Go Memory statistics and caller info

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Syntax

Go
const GOOS string
const GOARCH string
func Version() string
func NumCPU() int
func GOMAXPROCS(n int) int
func NumGoroutine() int
func Gosched()
func Goexit()
func GC()
func ReadMemStats(m *MemStats)
func Caller(skip int) (pc uintptr, file string, line int, ok bool)
func Callers(skip int, pc []uintptr) int
func Stack(buf []byte, all bool) int
func KeepAlive(x any)
func SetFinalizer(obj, finalizer any)
func AddCleanup[T, S any](ptr *T, cleanup func(S), arg S) Cleanup  // Go 1.24
Function Description
GOOS, GOARCH, Version() Target operating system, architecture and Go release.
NumCPU() Logical CPUs usable by the process.
GOMAXPROCS(n) Sets the number of OS threads that run Go code at once and returns the previous setting; n < 1 changes nothing. Defaults to NumCPU (container CPU limits are honored since Go 1.25).
NumGoroutine() Number of goroutines that currently exist.
Gosched() Yields the processor so other goroutines can run.
Goexit() Runs deferred calls, then terminates the calling goroutine.
GC() Forces a full collection and waits for it.
ReadMemStats Fills a MemStats (heap size, total allocations, GC counts...). It briefly stops the world, so don't call it in hot paths.
Caller, Callers, CallersFrames, FuncForPC Inspect the call stack: file, line and function name.
Stack Writes a formatted stack trace into a buffer.
KeepAlive, SetFinalizer, AddCleanup Interact with the garbage collector for resources owned outside Go.

Usage notes

  • Gosched is not synchronization. Using it to "wait for" another goroutine is a bug; use channels, sync.WaitGroup or a mutex.
  • Goexit from the main goroutine lets the other goroutines run on, and the program then crashes with "no goroutines (main called runtime.Goexit) - deadlock!" when none are left. Reserve it for helpers such as t.FailNow.
  • Counting goroutines is useful in tests to detect leaks, but the number is a snapshot; give workers a moment to exit before comparing.
  • runtime.GC() is for tests and benchmarks. In production the collector paces itself; see the GOGC and memory limit lesson.
  • Prefer log/slog AddSource or errors wrapping over hand-rolled Caller calls for logging locations; Caller costs microseconds.
  • Finalizers are unreliable. They run at an unspecified time, may never run before exit, and keep objects alive one extra cycle. Prefer an explicit Close; AddCleanup is the safer modern alternative.
  • Environment knobs such as GOMAXPROCS, GOGC, GOMEMLIMIT and GODEBUG are read at startup and documented in the package overview.