package runtime

Import Path
	runtime (on go.dev)

Dependency Relation
	imports 14 packages, and imported by 49 packages

Involved Source Files alg.go arena.go asan0.go atomic_pointer.go cgo.go cgo_mmap.go cgo_sigaction.go cgocall.go cgocallback.go cgocheck.go chan.go checkptr.go compiler.go complex.go coro.go covercounter.go covermeta.go cpuflags.go cpuflags_amd64.go cpuprof.go cputicks.go create_file_unix.go debug.go debugcall.go debuglog.go debuglog_off.go defs_linux_amd64.go env_posix.go error.go exithook.go 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 interface to the run-time type system. # Environment Variables The following environment variables ($name or %name%, depending on the host operating system) control the run-time behavior of Go programs. The meanings and use may change from release to release. The GOGC variable sets the initial garbage collection target percentage. A collection is triggered when the ratio of freshly allocated data to live data remaining after the previous collection reaches this percentage. The default is GOGC=100. Setting GOGC=off disables the garbage collector entirely. [runtime/debug.SetGCPercent] allows changing this percentage at run time. The GOMEMLIMIT variable sets a soft memory limit for the runtime. This memory limit includes the Go heap and all other memory managed by the runtime, and excludes external memory sources such as mappings of the binary itself, memory managed in other languages, and memory held by the operating system on behalf of the Go program. GOMEMLIMIT is a numeric value in bytes with an optional unit suffix. The supported suffixes include B, KiB, MiB, GiB, and TiB. These suffixes represent quantities of bytes as defined by the IEC 80000-13 standard. That is, they are based on powers of two: KiB means 2^10 bytes, MiB means 2^20 bytes, and so on. The default setting is [math.MaxInt64], which effectively disables the memory limit. [runtime/debug.SetMemoryLimit] allows changing this limit at run time. The GODEBUG variable controls debugging variables within the runtime. It is a comma-separated list of name=val pairs setting these named variables: allocfreetrace: setting allocfreetrace=1 causes every allocation to be profiled and a stack trace printed on each object's allocation and free. clobberfree: setting clobberfree=1 causes the garbage collector to clobber the memory content of an object with bad content when it frees the object. cpu.*: cpu.all=off disables the use of all optional instruction set extensions. cpu.extension=off disables use of instructions from the specified instruction set extension. extension is the lower case name for the instruction set extension such as sse41 or avx as listed in internal/cpu package. As an example cpu.avx=off disables runtime detection and thereby use of AVX instructions. cgocheck: setting cgocheck=0 disables all checks for packages using cgo to incorrectly pass Go pointers to non-Go code. Setting cgocheck=1 (the default) enables relatively cheap checks that may miss some errors. A more complete, but slow, cgocheck mode can be enabled using GOEXPERIMENT (which requires a rebuild), see https://pkg.go.dev/internal/goexperiment for details. disablethp: setting disablethp=1 on Linux disables transparent huge pages for the heap. It has no effect on other platforms. disablethp is meant for compatibility with versions of Go before 1.21, which stopped working around a Linux kernel default that can result in significant memory overuse. See https://go.dev/issue/64332. This setting will be removed in a future release, so operators should tweak their Linux configuration to suit their needs before then. See https://go.dev/doc/gc-guide#Linux_transparent_huge_pages. dontfreezetheworld: by default, the start of a fatal panic or throw "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 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 never recycled. gccheckmark: setting gccheckmark=1 enables verification of the garbage collector's concurrent mark phase by performing a second mark pass while the world is stopped. If the second pass finds a reachable object that was not found by concurrent mark, the garbage collector will panic. gcpacertrace: setting gcpacertrace=1 causes the garbage collector to print information about the internal state of the concurrent pacer. gcshrinkstackoff: setting gcshrinkstackoff=1 disables moving goroutines onto smaller stacks. In this mode, a goroutine's stack can only grow. gcstoptheworld: setting gcstoptheworld=1 disables concurrent garbage collection, making every garbage collection a stop-the-world event. Setting gcstoptheworld=2 also disables concurrent sweeping after the garbage collection finishes. 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. 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: gc # the GC number, incremented at each GC @#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, 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 line with allocation), background GC time, and idle GC time. If the line ends with "(forced)", this GC was forced by a runtime.GC() call. harddecommit: setting harddecommit=1 causes memory that is returned to the OS to also have protections removed on it. This is the only mode of operation on Windows, but is helpful in debugging scavenger-related issues on other platforms. Currently, only supported on Linux. inittrace: setting inittrace=1 causes the runtime to emit a single line to standard error for each package with init work, summarizing the execution time and memory allocation. No information is printed for inits executed as part of plugin loading and for packages without both user defined and compiler generated init work. The format of this line is subject to change. Currently, it is: init # @#ms, # ms clock, # bytes, # allocs where the fields are as follows: init # the package name @# ms time in milliseconds when the init started since program start # clock wall-clock time for package initialization work # bytes memory allocated on the heap # allocs number of heap allocations madvdontneed: setting madvdontneed=0 will use MADV_FREE instead of MADV_DONTNEED on Linux when returning memory to the kernel. This is more efficient, but means RSS numbers will drop only when the OS is under memory pressure. On the BSDs and Illumos/Solaris, setting madvdontneed=1 will use MADV_DONTNEED instead of MADV_FREE. This is less efficient, but causes RSS numbers to drop more quickly. memprofilerate: setting memprofilerate=X will update the value of runtime.MemProfileRate. When set to 0 memory profiling is disabled. Refer to the description of MemProfileRate for the default value. pagetrace: setting pagetrace=/path/to/file will write out a trace of page events that can be viewed, analyzed, and visualized using the x/debug/cmd/pagetrace tool. Build your program with GOEXPERIMENT=pagetrace to enable this functionality. Do not enable this functionality if your program is a setuid binary as it introduces a security risk in that scenario. Currently not supported on Windows, plan9 or js/wasm. Setting this option for some applications can produce large traces, so use with care. panicnil: setting panicnil=1 disables the runtime error when calling panic with nil interface value or an untyped nil. runtimecontentionstacks: setting runtimecontentionstacks=1 enables inclusion of call stacks related to contention on runtime-internal locks in the "mutex" profile, subject to the MutexProfileFraction setting. When runtimecontentionstacks=0, contention on runtime-internal locks will report as "runtime._LostContendedRuntimeLock". When runtimecontentionstacks=1, the call stacks will correspond to the unlock call that released the lock. But instead of the value corresponding to the amount of contention that call stack caused, it corresponds to the amount of time the caller of unlock had to wait in its original call to lock. A future release is expected to align those and remove this setting. invalidptr: invalidptr=1 (the default) causes the garbage collector and stack copier to crash the program if an invalid pointer value (for example, 1) is found in a pointer-typed location. Setting invalidptr=0 disables this check. This should only be used as a temporary workaround to diagnose buggy code. The real fix is to not store integers in pointer-typed locations. sbrk: setting sbrk=1 replaces the memory allocator and garbage collector with a trivial allocator that obtains memory from the operating system and never reclaims any memory. scavtrace: setting scavtrace=1 causes the runtime to emit a single line to standard error, roughly once per GC cycle, summarizing the amount of work done by the scavenger as well as the total amount of memory returned to the operating system and an estimate of physical memory utilization. The format of this line is subject to change, but currently it is: scav # KiB work (bg), # KiB work (eager), # KiB total, #% util where the fields are as follows: # KiB work (bg) the amount of memory returned to the OS in the background since the last line # KiB work (eager) the amount of memory returned to the OS eagerly since the last line # KiB now the amount of address space currently returned to the OS #% util the fraction of all unscavenged heap memory which is in-use If the line ends with "(forced)", then scavenging was forced by a debug.FreeOSMemory() call. scheddetail: setting schedtrace=X and scheddetail=1 causes the scheduler to emit detailed multiline info every X milliseconds, describing state of the scheduler, processors, threads and goroutines. schedtrace: setting schedtrace=X causes the scheduler to emit a single line to standard error every X milliseconds, summarizing the scheduler state. tracebackancestors: setting tracebackancestors=N extends tracebacks with the stacks at which goroutines were created, where N limits the number of ancestor goroutines to report. This also extends the information returned by runtime.Stack. Ancestor's goroutine IDs will refer to the ID of the goroutine at the time of creation; it's possible for this ID to be reused for another goroutine. Setting N to 0 will report no ancestry information. tracefpunwindoff: setting tracefpunwindoff=1 forces the execution tracer to use the runtime's default stack unwinder instead of frame pointer unwinding. 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 goroutine scheduling. This is useful for debugging GC issues because it also disables the conservative stack scanning used for asynchronously preempted goroutines. The [net] and [net/http] packages also refer to debugging variables in GODEBUG. See the documentation for those packages for details. The GOMAXPROCS variable limits the number of operating system threads that can execute user-level Go code simultaneously. There is no limit to the number of threads that can be blocked in system calls on behalf of Go code; those do not count against the GOMAXPROCS limit. This package's [GOMAXPROCS] function queries and changes the limit. The GORACE variable configures the race detector, for programs built using -race. See the [Race Detector article] for details. The GOTRACEBACK variable controls the amount of output generated when a Go program fails due to an unrecovered panic or an unexpected runtime condition. By default, a failure prints a stack trace for the current goroutine, eliding functions internal to the run-time system, and then exits with exit code 2. The failure prints stack traces for all goroutines if there is no current goroutine or the failure is internal to the run-time. GOTRACEBACK=none omits the goroutine stack traces entirely. GOTRACEBACK=single (the default) behaves as described above. GOTRACEBACK=all adds stack traces for all user-created goroutines. GOTRACEBACK=system is like “all” but adds stack frames for run-time functions and shows goroutines created internally by the run-time. GOTRACEBACK=crash is like “system” but crashes in an operating system-specific manner instead of exiting. For example, on Unix systems, the crash raises SIGABRT to trigger a core dump. GOTRACEBACK=wer is like “crash” but doesn't disable Windows Error Reporting (WER). For historical reasons, the GOTRACEBACK settings 0, 1, and 2 are synonyms for none, all, and system, respectively. The [runtime/debug.SetTraceback] function allows increasing the amount of output at run time, but it cannot reduce the amount below that specified by the environment variable. The GOARCH, GOOS, GOPATH, and GOROOT environment variables complete the set of Go environment variables. They influence the building of Go programs (see [cmd/go] and [go/build]). GOARCH, GOOS, and GOROOT are recorded at compile time and made available by constants or functions in this package, but they do not influence the execution of the run-time system. # Security On Unix platforms, Go's runtime system behaves slightly differently when a binary is setuid/setgid or executed with setuid/setgid-like properties, in order to prevent dangerous behaviors. On Linux this is determined by checking for the AT_SECURE flag in the auxiliary vector, on the BSDs and Solaris/Illumos it is determined by checking the issetugid syscall, and on AIX it is determined by checking if the uid/gid match the effective uid/gid. When the runtime determines the binary is setuid/setgid-like, it does three main things: - The standard input/output file descriptors (0, 1, 2) are checked to be open. If any of them are closed, they are opened pointing at /dev/null. - The value of the GOTRACEBACK environment variable is set to 'none'. - When a signal is received that terminates the program, or the program encounters an unrecoverable panic that would otherwise override the value of GOTRACEBACK, the goroutine stack, registers, and other memory related information are omitted. fastlog2.go fastlog2table.go fds_unix.go float.go hash64.go heapdump.go histogram.go iface.go lfstack.go lock_futex.go lockrank.go lockrank_off.go malloc.go map.go map_fast32.go map_fast64.go map_faststr.go mbarrier.go mbitmap.go mbitmap_allocheaders.go mcache.go mcentral.go mcheckmark.go mem.go mem_linux.go metrics.go mfinal.go mfixalloc.go mgc.go mgclimit.go mgcmark.go mgcpacer.go mgcscavenge.go mgcstack.go mgcsweep.go mgcwork.go mheap.go minmax.go mpagealloc.go mpagealloc_64bit.go mpagecache.go mpallocbits.go mprof.go mranges.go msan0.go msize_allocheaders.go mspanset.go mstats.go mwbbuf.go nbpipe_pipe2.go netpoll.go netpoll_epoll.go nonwindows_stub.go os_linux.go os_linux_generic.go os_linux_noauxv.go os_linux_x86.go os_nonopenbsd.go os_unix.go pagetrace_off.go panic.go pinner.go plugin.go preempt.go preempt_nonwindows.go print.go proc.go profbuf.go proflabel.go race0.go rand.go rdebug.go retry.go runtime.go runtime1.go runtime2.go runtime_boring.go rwmutex.go security_linux.go security_unix.go select.go sema.go signal_amd64.go signal_linux_amd64.go signal_unix.go sigqueue.go sigqueue_note.go sigtab_linux_generic.go sizeclasses.go slice.go softfloat64.go stack.go stkframe.go string.go stubs.go stubs2.go stubs3.go stubs_amd64.go stubs_linux.go symtab.go symtabinl.go sys_nonppc64x.go sys_x86.go tagptr.go tagptr_64bit.go test_amd64.go time.go time_nofake.go timeasm.go tls_stub.go trace2.go trace2buf.go trace2cpu.go trace2event.go trace2map.go trace2region.go trace2runtime.go trace2stack.go trace2status.go trace2string.go trace2time.go traceback.go type.go typekind.go unsafe.go utf8.go vdso_elf64.go vdso_linux.go vdso_linux_amd64.go write_err.go asm_amd64.h asm_ppc64x.h funcdata.h go_tls.h textflag.h asm.s asm_amd64.s duff_amd64.s memclr_amd64.s memmove_amd64.s preempt_amd64.s rt0_linux_amd64.s sys_linux_amd64.s test_amd64.s time_linux_amd64.s
Code Examples package main import ( "fmt" "runtime" "strings" ) func main() { c := func() { // Ask runtime.Callers for up to 10 PCs, including runtime.Callers itself. pc := make([]uintptr, 10) n := runtime.Callers(0, pc) if n == 0 { // No PCs available. This can happen if the first argument to // runtime.Callers is large. // // Return now to avoid processing the zero Frame that would // otherwise be returned by frames.Next below. return } pc = pc[:n] // pass only valid pcs to runtime.CallersFrames frames := runtime.CallersFrames(pc) // Loop to get frames. // A fixed number of PCs can expand to an indefinite number of Frames. for { frame, more := frames.Next() // Process this frame. // // To keep this example's output stable // even if there are changes in the testing package, // stop unwinding when we leave package runtime. if !strings.Contains(frame.File, "runtime/") { break } fmt.Printf("- more:%v | %s\n", more, frame.Function) // Check whether there are more frames to process after this one. if !more { break } } } b := func() { c() } a := func() { b() } a() }
Package-Level Type Names (total 11)
/* sort by: | */
BlockProfileRecord describes blocking events originated at a particular call sequence (stack trace). Count int64 Cycles int64 StackRecord StackRecord // stack trace for this record; ends at first 0 entry Stack returns the stack trace associated with the record, a prefix of r.Stack0. func BlockProfile(p []BlockProfileRecord) (n int, ok bool) func MutexProfile(p []BlockProfileRecord) (n int, ok bool)
The Error interface identifies a run time error. ( Error) Error() builtin.string RuntimeError is a no-op function but serves to distinguish types that are run time errors from ordinary errors: a type is a run time error if it has a RuntimeError method. *PanicNilError *TypeAssertionError Error : error
Frame is the information returned by [Frames] for each call frame. Entry point program counter for the function; may be zero if not known. If Func is not nil then Entry == Func.Entry(). File and Line are the file name and line number of the location in this frame. For non-leaf frames, this will be the location of a call. These may be the empty string and zero, respectively, if not known. Func is the Func value of this call frame. This may be nil for non-Go code or fully inlined functions. Function is the package path-qualified function name of this call frame. If non-empty, this string uniquely identifies a single function in the program. This may be the empty string if not known. If Func is not nil then Function == Func.Name(). Line int PC is the program counter for the location in this frame. For a frame that calls another frame, this will be the program counter of a call instruction. Because of inlining, multiple frames may have the same PC value, but different symbolic information. func (*Frames).Next() (frame Frame, more bool)
Frames may be used to get function/file/line information for a slice of PC values returned by [Callers]. Next returns a [Frame] representing the next call frame in the slice of PC values. If it has already returned all call frames, Next returns a zero [Frame]. The more result indicates whether the next call to Next will return a valid [Frame]. It does not necessarily indicate whether this call returned one. See the [Frames] example for idiomatic usage. func CallersFrames(callers []uintptr) *Frames
A Func represents a Go function in the running binary. Entry returns the entry address of the function. FileLine returns the file name and line number of the source code corresponding to the program counter pc. The result will not be accurate if pc is not a program counter within f. Name returns the name of the function. func FuncForPC(pc uintptr) *Func
A MemProfileRecord describes the live objects allocated by a particular call sequence (stack trace). // number of bytes allocated, freed // number of objects allocated, freed // number of bytes allocated, freed // number of objects allocated, freed // stack trace for this record; ends at first 0 entry InUseBytes returns the number of bytes in use (AllocBytes - FreeBytes). InUseObjects returns the number of objects in use (AllocObjects - FreeObjects). Stack returns the stack trace associated with the record, a prefix of r.Stack0. func MemProfile(p []MemProfileRecord, inuseZero bool) (n int, ok bool)
A MemStats records statistics about the memory allocator. Alloc is bytes of allocated heap objects. This is the same as HeapAlloc (see below). BuckHashSys is bytes of memory in profiling bucket hash tables. BySize reports per-size class allocation statistics. BySize[N] gives statistics for allocations of size S where BySize[N-1].Size < S ≤ BySize[N].Size. This does not report allocations larger than BySize[60].Size. DebugGC is currently unused. EnableGC indicates that GC is enabled. It is always true, even if GOGC=off. Frees is the cumulative count of heap objects freed. GCCPUFraction is the fraction of this program's available CPU time used by the GC since the program started. GCCPUFraction is expressed as a number between 0 and 1, where 0 means GC has consumed none of this program's CPU. A program's available CPU time is defined as the integral of GOMAXPROCS since the program started. That is, if GOMAXPROCS is 2 and a program has been running for 10 seconds, its "available CPU" is 20 seconds. GCCPUFraction does not include CPU time used for write barrier activity. This is the same as the fraction of CPU reported by GODEBUG=gctrace=1. GCSys is bytes of memory in garbage collection metadata. HeapAlloc is bytes of allocated heap objects. "Allocated" heap objects include all reachable objects, as well as unreachable objects that the garbage collector has not yet freed. Specifically, HeapAlloc increases as heap objects are allocated and decreases as the heap is swept and unreachable objects are freed. Sweeping occurs incrementally between GC cycles, so these two processes occur simultaneously, and as a result HeapAlloc tends to change smoothly (in contrast with the sawtooth that is typical of stop-the-world garbage collectors). HeapIdle is bytes in idle (unused) spans. Idle spans have no objects in them. These spans could be (and may already have been) returned to the OS, or they can be reused for heap allocations, or they can be reused as stack memory. HeapIdle minus HeapReleased estimates the amount of memory that could be returned to the OS, but is being retained by the runtime so it can grow the heap without requesting more memory from the OS. If this difference is significantly larger than the heap size, it indicates there was a recent transient spike in live heap size. HeapInuse is bytes in in-use spans. In-use spans have at least one object in them. These spans can only be used for other objects of roughly the same size. HeapInuse minus HeapAlloc estimates the amount of memory that has been dedicated to particular size classes, but is not currently being used. This is an upper bound on fragmentation, but in general this memory can be reused efficiently. HeapObjects is the number of allocated heap objects. Like HeapAlloc, this increases as objects are allocated and decreases as the heap is swept and unreachable objects are freed. HeapReleased is bytes of physical memory returned to the OS. This counts heap memory from idle spans that was returned to the OS and has not yet been reacquired for the heap. HeapSys is bytes of heap memory obtained from the OS. HeapSys measures the amount of virtual address space reserved for the heap. This includes virtual address space that has been reserved but not yet used, which consumes no physical memory, but tends to be small, as well as virtual address space for which the physical memory has been returned to the OS after it became unused (see HeapReleased for a measure of the latter). HeapSys estimates the largest size the heap has had. LastGC is the time the last garbage collection finished, as nanoseconds since 1970 (the UNIX epoch). Lookups is the number of pointer lookups performed by the runtime. This is primarily useful for debugging runtime internals. MCacheInuse is bytes of allocated mcache structures. MCacheSys is bytes of memory obtained from the OS for mcache structures. MSpanInuse is bytes of allocated mspan structures. MSpanSys is bytes of memory obtained from the OS for mspan structures. Mallocs is the cumulative count of heap objects allocated. The number of live objects is Mallocs - Frees. NextGC is the target heap size of the next GC cycle. The garbage collector's goal is to keep HeapAlloc ≤ NextGC. At the end of each GC cycle, the target for the next cycle is computed based on the amount of reachable data and the value of GOGC. NumForcedGC is the number of GC cycles that were forced by the application calling the GC function. NumGC is the number of completed GC cycles. OtherSys is bytes of memory in miscellaneous off-heap runtime allocations. PauseEnd is a circular buffer of recent GC pause end times, as nanoseconds since 1970 (the UNIX epoch). This buffer is filled the same way as PauseNs. There may be multiple pauses per GC cycle; this records the end of the last pause in a cycle. PauseNs is a circular buffer of recent GC stop-the-world pause times in nanoseconds. The most recent pause is at PauseNs[(NumGC+255)%256]. In general, PauseNs[N%256] records the time paused in the most recent N%256th GC cycle. There may be multiple pauses per GC cycle; this is the sum of all pauses during a cycle. PauseTotalNs is the cumulative nanoseconds in GC stop-the-world pauses since the program started. During a stop-the-world pause, all goroutines are paused and only the garbage collector can run. StackInuse is bytes in stack spans. In-use stack spans have at least one stack in them. These spans can only be used for other stacks of the same size. There is no StackIdle because unused stack spans are returned to the heap (and hence counted toward HeapIdle). StackSys is bytes of stack memory obtained from the OS. StackSys is StackInuse, plus any memory obtained directly from the OS for OS thread stacks. In non-cgo programs this metric is currently equal to StackInuse (but this should not be relied upon, and the value may change in the future). In cgo programs this metric includes OS thread stacks allocated directly from the OS. Currently, this only accounts for one stack in c-shared and c-archive build modes and other sources of stacks from the OS (notably, any allocated by C code) are not currently measured. Note this too may change in the future. Sys is the total bytes of memory obtained from the OS. Sys is the sum of the XSys fields below. Sys measures the virtual address space reserved by the Go runtime for the heap, stacks, and other internal data structures. It's likely that not all of the virtual address space is backed by physical memory at any given moment, though in general it all was at some point. TotalAlloc is cumulative bytes allocated for heap objects. TotalAlloc increases as heap objects are allocated, but unlike Alloc and HeapAlloc, it does not decrease when objects are freed. func ReadMemStats(m *MemStats)
A PanicNilError happens when code calls panic(nil). Before Go 1.21, programs that called panic(nil) observed recover returning nil. Starting in Go 1.21, programs that call panic(nil) observe recover returning a *PanicNilError. Programs can change back to the old behavior by setting GODEBUG=panicnil=1. (*PanicNilError) Error() string (*PanicNilError) RuntimeError() *PanicNilError : Error *PanicNilError : error
A Pinner is a set of Go objects each pinned to a fixed location in memory. The [Pinner.Pin] method pins one object, while [Pinner.Unpin] unpins all pinned objects. See their comments for more information. Pin pins a Go object, preventing it from being moved or freed by the garbage collector until the [Pinner.Unpin] method has been called. A pointer to a pinned object can be directly stored in C memory or can be contained in Go memory passed to C functions. If the pinned object itself contains pointers to Go objects, these objects must be pinned separately if they are going to be accessed from C code. The argument must be a pointer of any type or an [unsafe.Pointer]. It's safe to call Pin on non-Go pointers, in which case Pin will do nothing. Unpin unpins all pinned objects of the [Pinner].
A StackRecord describes a single execution stack. // stack trace for this record; ends at first 0 entry Stack returns the stack trace associated with the record, a prefix of r.Stack0. func GoroutineProfile(p []StackRecord) (n int, ok bool) func ThreadCreateProfile(p []StackRecord) (n int, ok bool)
A TypeAssertionError explains a failed type assertion. (*TypeAssertionError) Error() string (*TypeAssertionError) RuntimeError() *TypeAssertionError : Error *TypeAssertionError : error
Package-Level Functions (total 33)
BlockProfile returns n, the number of records in the current blocking profile. If len(p) >= n, BlockProfile copies the profile into p and returns n, true. If len(p) < n, BlockProfile does not change p and returns n, false. Most clients should use the [runtime/pprof] package or the [testing] package's -test.blockprofile flag instead of calling BlockProfile directly.
Breakpoint executes a breakpoint trap.
Caller reports file and line number information about function invocations on the calling goroutine's stack. The argument skip is the number of stack frames to ascend, with 0 identifying the caller of Caller. (For historical reasons the meaning of skip differs between Caller and [Callers].) The return values report the program counter, file name, and line number within the file of the corresponding call. The boolean ok is false if it was not possible to recover the information.
Callers fills the slice pc with the return program counters of function invocations on the calling goroutine's stack. The argument skip is the number of stack frames to skip before recording in pc, with 0 identifying the frame for Callers itself and 1 identifying the caller of Callers. 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 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 returned PCs, since these cannot account for inlining or return program counter adjustment.
CallersFrames takes a slice of PC values returned by [Callers] and prepares to return function/file/line information. Do not change the slice until you are done with the [Frames].
CPUProfile panics. It formerly provided raw access to chunks of a pprof-format profile generated by the runtime. The details of generating that format have changed, so this functionality has been removed. Deprecated: Use the [runtime/pprof] package, or the handlers in the [net/http/pprof] package, or the [testing] package's -test.cpuprofile flag instead.
FuncForPC returns a *[Func] describing the function that contains the given program counter address, or else nil. If pc represents multiple functions because of inlining, it returns the *Func describing the innermost function, but with an entry of the outermost function.
GC runs a garbage collection and blocks the caller until the garbage collection is complete. It may also block the entire program.
Goexit terminates the goroutine that calls it. No other goroutine is affected. Goexit runs all deferred calls before terminating the goroutine. Because Goexit is not a panic, any recover calls in those deferred functions will return nil. Calling Goexit from the main goroutine terminates that goroutine without func main returning. Since func main has not returned, the program continues execution of other goroutines. If all other goroutines exit, the program crashes.
GOMAXPROCS sets the maximum number of CPUs that can be executing simultaneously and returns the previous setting. It defaults to the value of [runtime.NumCPU]. If n < 1, it does not change the current setting. This call will go away when the scheduler improves.
GOROOT returns the root of the Go tree. It uses the GOROOT environment variable, if set at process start, or else the root used during the Go build.
GoroutineProfile returns n, the number of records in the active goroutine stack profile. If len(p) >= n, GoroutineProfile copies the profile into p and returns n, true. If len(p) < n, GoroutineProfile does not change p and returns n, false. Most clients should use the [runtime/pprof] package instead of calling GoroutineProfile directly.
Gosched yields the processor, allowing other goroutines to run. It does not suspend the current goroutine, so execution resumes automatically.
KeepAlive marks its argument as currently reachable. This ensures that the object is not freed, and its finalizer is not run, before the point in the program where KeepAlive is called. A very simplified example showing where KeepAlive is required: type File struct { d int } d, err := syscall.Open("/file/path", syscall.O_RDONLY, 0) // ... do something if err != nil ... p := &File{d} runtime.SetFinalizer(p, func(p *File) { syscall.Close(p.d) }) var buf [10]byte n, err := syscall.Read(p.d, buf[:]) // Ensure p is not finalized until Read returns. runtime.KeepAlive(p) // No more uses of p after this point. Without the KeepAlive call, the finalizer could run at the start of [syscall.Read], closing the file descriptor before syscall.Read makes the actual system call. Note: KeepAlive should only be used to prevent finalizers from running prematurely. In particular, when used with [unsafe.Pointer], the rules for valid uses of unsafe.Pointer still apply.
LockOSThread wires the calling goroutine to its current operating system thread. The calling goroutine will always execute in that thread, and no other goroutine will execute in it, until the calling goroutine has made as many calls to [UnlockOSThread] as to LockOSThread. If the calling goroutine exits without unlocking the thread, the thread will be terminated. All init functions are run on the startup thread. Calling LockOSThread from an init function will cause the main function to be invoked on that thread. A goroutine should call LockOSThread before calling OS services or non-Go library functions that depend on per-thread state.
MemProfile returns a profile of memory allocated and freed per allocation site. MemProfile returns n, the number of records in the current memory profile. If len(p) >= n, MemProfile copies the profile into p and returns n, true. If len(p) < n, MemProfile does not change p and returns n, false. If inuseZero is true, the profile includes allocation records where r.AllocBytes > 0 but r.AllocBytes == r.FreeBytes. These are sites where memory was allocated, but it has all been released back to the runtime. The returned profile may be up to two garbage collection cycles old. This is to avoid skewing the profile toward allocations; because allocations happen in real time but frees are delayed until the garbage collector performs sweeping, the profile only accounts for allocations that have had a chance to be freed by the garbage collector. Most clients should use the runtime/pprof package or the testing package's -test.memprofile flag instead of calling MemProfile directly.
MutexProfile returns n, the number of records in the current mutex profile. If len(p) >= n, MutexProfile copies the profile into p and returns n, true. Otherwise, MutexProfile does not change p, and returns n, false. Most clients should use the [runtime/pprof] package instead of calling MutexProfile directly.
NumCgoCall returns the number of cgo calls made by the current process.
NumCPU returns the number of logical CPUs usable by the current process. The set of available CPUs is checked by querying the operating system at process startup. Changes to operating system CPU allocation after process startup are not reflected.
NumGoroutine returns the number of goroutines that currently exist.
ReadMemStats populates m with memory allocator statistics. The returned memory allocator statistics are up to date as of the call to ReadMemStats. This is in contrast with a heap profile, which is a snapshot as of the most recently completed garbage collection cycle.
ReadTrace returns the next chunk of binary tracing data, blocking until data is available. If tracing is turned off and all the data accumulated while it was on has been returned, ReadTrace returns nil. The caller must copy the returned data before calling ReadTrace again. ReadTrace must be called from one goroutine at a time.
SetBlockProfileRate controls the fraction of goroutine blocking events that are reported in the blocking profile. The profiler aims to sample an average of one blocking event per rate nanoseconds spent blocked. To include every blocking event in the profile, pass rate = 1. To turn off profiling entirely, pass rate <= 0.
SetCgoTraceback records three C functions to use to gather traceback information from C code and to convert that traceback information into symbolic information. These are used when printing stack traces for a program that uses cgo. The traceback and context functions may be called from a signal handler, and must therefore use only async-signal safe functions. The symbolizer function may be called while the program is crashing, and so must be cautious about using memory. None of the functions may call back into Go. The context function will be called with a single argument, a pointer to a struct: struct { Context uintptr } In C syntax, this struct will be struct { uintptr_t Context; }; If the Context field is 0, the context function is being called to record the current traceback context. It should record in the Context field whatever information is needed about the current point of execution to later produce a stack trace, probably the stack pointer and PC. In this case the context function will be called from C code. If the Context field is not 0, then it is a value returned by a previous call to the context function. This case is called when the context is no longer needed; that is, when the Go code is returning to its C code caller. This permits the context function to release any associated resources. While it would be correct for the context function to record a complete a stack trace whenever it is called, and simply copy that out in the traceback function, in a typical program the context function will be called many times without ever recording a traceback for that context. Recording a complete stack trace in a call to the context function is likely to be inefficient. The traceback function will be called with a single argument, a pointer to a struct: struct { Context uintptr SigContext uintptr Buf *uintptr Max uintptr } In C syntax, this struct will be struct { uintptr_t Context; uintptr_t SigContext; uintptr_t* Buf; uintptr_t Max; }; The Context field will be zero to gather a traceback from the current program execution point. In this case, the traceback function will be called from C code. Otherwise Context will be a value previously returned by a call to the context function. The traceback function should gather a stack trace from that saved point in the program execution. The traceback function may be called from an execution thread other than the one that recorded the context, but only when the context is known to be valid and unchanging. The traceback function may also be called deeper in the call stack on the same thread that recorded the context. The traceback function may be called multiple times with the same Context value; it will usually be appropriate to cache the result, if possible, the first time this is called for a specific context value. If the traceback function is called from a signal handler on a Unix system, SigContext will be the signal context argument passed to the signal handler (a C ucontext_t* cast to uintptr_t). This may be used to start tracing at the point where the signal occurred. If the traceback function is not called from a signal handler, SigContext will be zero. Buf is where the traceback information should be stored. It should be PC values, such that Buf[0] is the PC of the caller, Buf[1] is the PC of that function's caller, and so on. Max is the maximum number of entries to store. The function should store a zero to indicate the top of the stack, or that the caller is on a different stack, presumably a Go stack. Unlike runtime.Callers, the PC values returned should, when passed to the symbolizer function, return the file/line of the call instruction. No additional subtraction is required or appropriate. On all platforms, the traceback function is invoked when a call from Go to C to Go requests a stack trace. On linux/amd64, linux/ppc64le, linux/arm64, and freebsd/amd64, the traceback function is also invoked when a signal is received by a thread that is executing a cgo call. The traceback function should not make assumptions about when it is called, as future versions of Go may make additional calls. The symbolizer function will be called with a single argument, a pointer to a struct: struct { PC uintptr // program counter to fetch information for File *byte // file name (NUL terminated) Lineno uintptr // line number Func *byte // function name (NUL terminated) Entry uintptr // function entry point More uintptr // set non-zero if more info for this PC Data uintptr // unused by runtime, available for function } In C syntax, this struct will be struct { uintptr_t PC; char* File; uintptr_t Lineno; char* Func; uintptr_t Entry; uintptr_t More; uintptr_t Data; }; The PC field will be a value returned by a call to the traceback function. The first time the function is called for a particular traceback, all the fields except PC will be 0. The function should fill in the other fields if possible, setting them to 0/nil if the information is not available. The Data field may be used to store any useful information across calls. The More field should be set to non-zero if there is more information for this PC, zero otherwise. If More is set non-zero, the function will be called again with the same PC, and may return different information (this is intended for use with inlined functions). If More is zero, the function will be called with the next PC value in the traceback. When the traceback is complete, the function will be called once more with PC set to zero; this may be used to free any information. Each call will leave the fields of the struct set to the same values they had upon return, except for the PC field when the More field is zero. The function must not keep a copy of the struct pointer between calls. When calling SetCgoTraceback, the version argument is the version number of the structs that the functions expect to receive. Currently this must be zero. The symbolizer function may be nil, in which case the results of the traceback function will be displayed as numbers. If the traceback function is nil, the symbolizer function will never be called. The context function may be nil, in which case the traceback function will only be called with the context field set to zero. If the context function is nil, then calls from Go to C to Go will not show a traceback for the C portion of the call stack. SetCgoTraceback should be called only once, ideally from an init function.
SetCPUProfileRate sets the CPU profiling rate to hz samples per second. If hz <= 0, SetCPUProfileRate turns off profiling. If the profiler is on, the rate cannot be changed without first turning it off. Most clients should use the [runtime/pprof] package or the [testing] package's -test.cpuprofile flag instead of calling SetCPUProfileRate directly.
SetFinalizer sets the finalizer associated with obj to the provided finalizer function. When the garbage collector finds an unreachable block with an associated finalizer, it clears the association and runs finalizer(obj) in a separate goroutine. This makes obj reachable again, but now without an associated finalizer. Assuming that SetFinalizer is not called again, the next time the garbage collector sees that obj is unreachable, it will free obj. SetFinalizer(obj, nil) clears any finalizer associated with obj. The argument obj must be a pointer to an object allocated by calling new, by taking the address of a composite literal, or by taking the address of a local variable. The argument finalizer must be a function that takes a single argument to which obj's type can be assigned, and can have arbitrary ignored return values. If either of these is not true, SetFinalizer may abort the program. Finalizers are run in dependency order: if A points at B, both have finalizers, and they are otherwise unreachable, only the finalizer for A runs; once A is freed, the finalizer for B can run. If a cyclic structure includes a block with a finalizer, that cycle is not guaranteed to be garbage collected and the finalizer is not guaranteed to run, because there is no ordering that respects the dependencies. The finalizer is scheduled to run at some arbitrary time after the program can no longer reach the object to which obj points. There is no guarantee that finalizers will run before a program exits, so typically they are useful only for releasing non-memory resources associated with an object during a long-running program. For example, an [os.File] object could use a finalizer to close the associated operating system file descriptor when a program discards an os.File without calling Close, but it would be a mistake to depend on a finalizer to flush an in-memory I/O buffer such as a [bufio.Writer], because the buffer would not be flushed at program exit. It is not guaranteed that a finalizer will run if the size of *obj is zero bytes, because it may share same address with other zero-size objects in memory. See https://go.dev/ref/spec#Size_and_alignment_guarantees. It is not guaranteed that a finalizer will run for objects allocated in initializers for package-level variables. Such objects may be linker-allocated, not heap-allocated. Note that because finalizers may execute arbitrarily far into the future after an object is no longer referenced, the runtime is allowed to perform a space-saving optimization that batches objects together in a single allocation slot. The finalizer for an unreferenced object in such an allocation may never run if it always exists in the same batch as a referenced object. Typically, this batching only happens for tiny (on the order of 16 bytes or less) and pointer-free objects. A finalizer may run as soon as an object becomes unreachable. In order to use finalizers correctly, the program must ensure that the object is reachable until it is no longer required. Objects stored in global variables, or that can be found by tracing pointers from a global variable, are reachable. For other objects, pass the object to a call of the [KeepAlive] function to mark the last point in the function where the object must be reachable. For example, if p points to a struct, such as os.File, that contains a file descriptor d, and p has a finalizer that closes that file descriptor, and if the last use of p in a function is a call to syscall.Write(p.d, buf, size), then p may be unreachable as soon as the program enters [syscall.Write]. The finalizer may run at that moment, closing p.d, causing syscall.Write to fail because it is writing to a closed file descriptor (or, worse, to an entirely different file descriptor opened by a different goroutine). To avoid this problem, call KeepAlive(p) after the call to syscall.Write. A single goroutine runs all finalizers for a program, sequentially. If a finalizer must run for a long time, it should do so by starting a new goroutine. In the terminology of the Go memory model, a call SetFinalizer(x, f) “synchronizes before” the finalization call f(x). However, there is no guarantee that KeepAlive(x) or any other use of x “synchronizes before” f(x), so in general a finalizer should use a mutex or other synchronization mechanism if it needs to access mutable state in x. For example, consider a finalizer that inspects a mutable field in x that is modified from time to time in the main program before x becomes unreachable and the finalizer is invoked. The modifications in the main program and the inspection in the finalizer need to use appropriate synchronization, such as mutexes or atomic updates, to avoid read-write races.
SetMutexProfileFraction controls the fraction of mutex contention events that are reported in the mutex profile. On average 1/rate events are reported. The previous rate is returned. To turn off profiling entirely, pass rate 0. To just read the current rate, pass rate < 0. (For n>1 the details of sampling may change.)
Stack formats a stack trace of the calling goroutine into buf and returns the number of bytes written to buf. If all is true, Stack formats stack traces of all other goroutines into buf after the trace for the current goroutine.
StartTrace enables tracing for the current process. While tracing, the data will be buffered and available via [ReadTrace]. StartTrace returns an error if tracing is already enabled. Most clients should use the [runtime/trace] package or the [testing] package's -test.trace flag instead of calling StartTrace directly.
StopTrace stops tracing, if it was previously enabled. StopTrace only returns after all the reads for the trace have completed.
ThreadCreateProfile returns n, the number of records in the thread creation profile. If len(p) >= n, ThreadCreateProfile copies the profile into p and returns n, true. If len(p) < n, ThreadCreateProfile does not change p and returns n, false. Most clients should use the runtime/pprof package instead of calling ThreadCreateProfile directly.
UnlockOSThread undoes an earlier call to LockOSThread. If this drops the number of active LockOSThread calls on the calling goroutine to zero, it unwires the calling goroutine from its fixed operating system thread. If there are no active LockOSThread calls, this is a no-op. Before calling UnlockOSThread, the caller must ensure that the OS thread is suitable for running other goroutines. If the caller made any permanent changes to the state of the thread that would affect other goroutines, it should not call this function and thus leave the goroutine locked to the OS thread until the goroutine (and hence the thread) exits.
Version returns the Go tree's version string. It is either the commit hash and date at the time of the build or, when possible, a release tag like "go1.3".
Package-Level Variables (only one)
MemProfileRate controls the fraction of memory allocations that are recorded and reported in the memory profile. The profiler aims to sample an average of one allocation per MemProfileRate bytes allocated. To include every allocated block in the profile, set MemProfileRate to 1. To turn off profiling entirely, set MemProfileRate to 0. The tools that process the memory profiles assume that the profile rate is constant across the lifetime of the program and equal to the current value. Programs that change the memory profiling rate should do so just once, as early as possible in the execution of the program (for example, at the beginning of main).
Package-Level Constants (total 3)
Compiler is the name of the compiler toolchain that built the running binary. Known toolchains are: gc Also known as cmd/compile. gccgo The gccgo front end, part of the GCC compiler suite.
GOARCH is the running program's architecture target: one of 386, amd64, arm, s390x, and so on.
GOOS is the running program's operating system target: one of darwin, freebsd, linux, and so on. To view possible combinations of GOOS and GOARCH, run "go tool dist list".