/*
Package runtime contains operations that interact with Go's runtime system,
such as functions to control goroutines. It also includes the low-level type information
-used by the reflect package; see reflect's documentation for the programmable
+used by the reflect package; see [reflect]'s documentation for the programmable
interface to the run-time type system.
# Environment Variables
requires a rebuild), see https://pkg.go.dev/internal/goexperiment for details.
dontfreezetheworld: by default, the start of a fatal panic or throw
- "freezes the world", stopping all goroutines, which makes it possible
- to traceback all goroutines (running goroutines cannot be traced), and
+ "freezes the world", preempting all threads to stop all running
+ goroutines, which makes it possible to traceback all goroutines, and
keeps their state close to the point of panic. Setting
- dontfreezetheworld=1 disables freeze, allowing goroutines to continue
- executing during panic processing. This can be useful when debugging
- the runtime scheduler, as freezetheworld perturbs scheduler state and
- thus may hide problems.
+ dontfreezetheworld=1 disables this preemption, allowing goroutines to
+ continue executing during panic processing. Note that goroutines that
+ naturally enter the scheduler will still stop. This can be useful when
+ debugging the runtime scheduler, as freezetheworld perturbs scheduler
+ state and thus may hide problems.
efence: setting efence=1 causes the allocator to run in a mode
where each object is allocated on a unique page and addresses are
gctrace: setting gctrace=1 causes the garbage collector to emit a single line to standard
error at each collection, summarizing the amount of memory collected and the
- length of the pause. The format of this line is subject to change.
+ length of the pause. The format of this line is subject to change. Included in
+ the explanation below is also the relevant runtime/metrics metric for each field.
Currently, it is:
gc # @#s #%: #+#+# ms clock, #+#/#/#+# ms cpu, #->#-># MB, # MB goal, # MB stacks, #MB globals, # P
where the fields are as follows:
@#s time in seconds since program start
#% percentage of time spent in GC since program start
#+...+# wall-clock/CPU times for the phases of the GC
- #->#-># MB heap size at GC start, at GC end, and live heap
- # MB goal goal heap size
- # MB stacks estimated scannable stack size
- # MB globals scannable global size
- # P number of processors used
+ #->#-># MB heap size at GC start, at GC end, and live heap, or /gc/scan/heap:bytes
+ # MB goal goal heap size, or /gc/heap/goal:bytes
+ # MB stacks estimated scannable stack size, or /gc/scan/stack:bytes
+ # MB globals scannable global size, or /gc/scan/globals:bytes
+ # P number of processors used, or /sched/gomaxprocs:threads
The phases are stop-the-world (STW) sweep termination, concurrent
mark and scan, and STW mark termination. The CPU times
for mark/scan are broken down in to assist time (GC performed in
This increases tracer overhead, but could be helpful as a workaround or for
debugging unexpected regressions caused by frame pointer unwinding.
+ traceadvanceperiod: the approximate period in nanoseconds between trace generations. Only
+ applies if a program is built with GOEXPERIMENT=exectracer2. Used primarily for testing
+ and debugging the execution tracer.
+
asyncpreemptoff: asyncpreemptoff=1 disables signal-based
asynchronous goroutine preemption. This makes some loops
non-preemptible for long periods, which may delay GC and
// It returns the number of entries written to pc.
//
// To translate these PCs into symbolic information such as function
-// names and line numbers, use CallersFrames. CallersFrames accounts
+// names and line numbers, use [CallersFrames]. CallersFrames accounts
// for inlined functions and adjusts the return program counters into
// call program counters. Iterating over the returned slice of PCs
-// directly is discouraged, as is using FuncForPC on any of the
+// directly is discouraged, as is using [FuncForPC] on any of the
// returned PCs, since these cannot account for inlining or return
// program counter adjustment.
func Callers(skip int, pc []uintptr) int {