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.
fmt.Println(runtime.GOOS, runtime.GOARCH, runtime.Version())
Try it
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.
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
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
Goschedis not synchronization. Using it to "wait for" another goroutine is a bug; use channels,sync.WaitGroupor a mutex.Goexitfrom 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 ast.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 theGOGCand memory limit lesson.- Prefer
log/slogAddSourceorerrorswrapping over hand-rolledCallercalls for logging locations;Callercosts 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;AddCleanupis the safer modern alternative. - Environment knobs such as
GOMAXPROCS,GOGC,GOMEMLIMITandGODEBUGare read at startup and documented in the package overview.