const Compiler = "gc"

const GOARCHstring =goarch.GOARCH

const GOOSstring =goos.GOOS

var MemProfileRateint = 512 * 1024

funcBlockProfile¶added ingo1.1

func BlockProfile(p []BlockProfileRecord) (nint, okbool)

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 theruntime/pprof package orthetesting package's -test.blockprofile flag insteadof calling BlockProfile directly.

funcBreakpoint¶

func Breakpoint()

Breakpoint executes a breakpoint trap.

funcCaller¶

func Caller(skipint) (pcuintptr, filestring, lineint, okbool)

Caller reports file and line number information about function invocations onthe calling goroutine's stack. The argument skip is the number of stack framesto ascend, with 0 identifying the caller of Caller. (For historical reasons themeaning of skip differs between Caller andCallers.) The return values reportthe program counter, the file name (using forward slashes as path separator, evenon Windows), and the line number within the file of the corresponding call.The boolean ok is false if it was not possible to recover the information.

funcCallers¶

func Callers(skipint, pc []uintptr)int

Callers fills the slice pc with the return program counters of function invocationson the calling goroutine's stack. The argument skip is the number of stack framesto skip before recording in pc, with 0 identifying the frame for Callers itself and1 identifying the caller of Callers.It returns the number of entries written to pc.

To translate these PCs into symbolic information such as functionnames and line numbers, useCallersFrames. CallersFrames accountsfor inlined functions and adjusts the return program counters intocall program counters. Iterating over the returned slice of PCsdirectly is discouraged, as is usingFuncForPC on any of thereturned PCs, since these cannot account for inlining or returnprogram counter adjustment.

funcGC¶

func GC()

GC runs a garbage collection and blocks the caller until thegarbage collection is complete. It may also block the entireprogram.

funcGOMAXPROCS¶

func GOMAXPROCS(nint)int

GOMAXPROCS sets the maximum number of CPUs that can be executingsimultaneously and returns the previous setting. If n < 1, it does not changethe current setting.

Default¶

If the GOMAXPROCS environment variable is set to a positive whole number,GOMAXPROCS defaults to that value.

Otherwise, the Go runtime selects an appropriate default value from a combination of

• the number of logical CPUs on the machine,
• the process’s CPU affinity mask,
• and, on Linux, the process’s average CPU throughput limit based on cgroup CPUquota, if any.

If GODEBUG=containermaxprocs=0 is set and GOMAXPROCS is not set by theenvironment variable, then GOMAXPROCS instead defaults to the value ofruntime.NumCPU. Note that GODEBUG=containermaxprocs=0 isdefault forlanguage version 1.24 and below.

Updates¶

The Go runtime periodically updates the default value based on changes tothe total logical CPU count, the CPU affinity mask, or cgroup quota. Settinga custom value with the GOMAXPROCS environment variable or by callingGOMAXPROCS disables automatic updates. The default value and automaticupdates can be restored by callingSetDefaultGOMAXPROCS.

If GODEBUG=updatemaxprocs=0 is set, the Go runtime does not performautomatic GOMAXPROCS updating. Note that GODEBUG=updatemaxprocs=0 isdefault for language version 1.24 and below.

Compatibility¶

Note that the default GOMAXPROCS behavior may change as the schedulerimproves, especially the implementation detail below.

Implementation details¶

When computing default GOMAXPROCS via cgroups, the Go runtime computes the"average CPU throughput limit" as the cgroup CPU quota / period. In cgroupv2, these values come from the cpu.max file. In cgroup v1, they come fromcpu.cfs_quota_us and cpu.cfs_period_us, respectively. In container runtimesthat allow configuring CPU limits, this value usually corresponds to the"CPU limit" option, not "CPU request".

The Go runtime typically selects the default GOMAXPROCS as the minimum ofthe logical CPU count, the CPU affinity mask count, or the cgroup CPUthroughput limit. However, it will never set GOMAXPROCS less than 2 unlessthe logical CPU count or CPU affinity mask count are below 2.

If the cgroup CPU throughput limit is not a whole number, the Go runtimerounds up to the next whole number.

GOMAXPROCS updates are performed up to once per second, or less if theapplication is idle.

funcGoexit¶

func Goexit()

Goexit terminates the goroutine that calls it. No other goroutine is affected.Goexit runs all deferred calls before terminating the goroutine. Because Goexitis not a panic, any recover calls in those deferred functions will return nil.

Calling Goexit from the main goroutine terminates that goroutinewithout func main returning. Since func main has not returned,the program continues execution of other goroutines.If all other goroutines exit, the program crashes.

It crashes if called from a thread not created by the Go runtime.

funcGoroutineProfile¶

func GoroutineProfile(p []StackRecord) (nint, okbool)

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 theruntime/pprof package insteadof calling GoroutineProfile directly.

funcGosched¶

func Gosched()

Gosched yields the processor, allowing other goroutines to run. It does notsuspend the current goroutine, so execution resumes automatically.

funcKeepAlive¶added ingo1.7

func KeepAlive(xany)

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]byten, 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 ofsyscall.Read, closing the file descriptor before syscall.Read makesthe actual system call.

Note: KeepAlive should only be used to prevent finalizers fromrunning prematurely. In particular, when used withunsafe.Pointer,the rules for valid uses of unsafe.Pointer still apply.

funcLockOSThread¶

func LockOSThread()

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 toUnlockOSThread 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 LockOSThreadfrom an init function will cause the main function to be invoked onthat thread.

A goroutine should call LockOSThread before calling OS services ornon-Go library functions that depend on per-thread state.

funcMemProfile¶

func MemProfile(p []MemProfileRecord, inuseZerobool) (nint, okbool)

MemProfile returns a profile of memory allocated and freed per allocationsite.

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 recordswhere r.AllocBytes > 0 but r.AllocBytes == r.FreeBytes.These are sites where memory was allocated, but it has allbeen 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; becauseallocations happen in real time but frees are delayed until the garbagecollector performs sweeping, the profile only accounts for allocationsthat have had a chance to be freed by the garbage collector.

Most clients should use the runtime/pprof package orthe testing package's -test.memprofile flag insteadof calling MemProfile directly.

funcMutexProfile¶added ingo1.8

func MutexProfile(p []BlockProfileRecord) (nint, okbool)

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 theruntime/pprof packageinstead of calling MutexProfile directly.

funcNumCPU¶

func NumCPU()int

NumCPU returns the number of logical CPUs usable by the current process.

The set of available CPUs is checked by querying the operating systemat process startup. Changes to operating system CPU allocation afterprocess startup are not reflected.

funcNumCgoCall¶

func NumCgoCall()int64

NumCgoCall returns the number of cgo calls made by the current process.

funcNumGoroutine¶

func NumGoroutine()int

NumGoroutine returns the number of goroutines that currently exist.

funcReadMemStats¶

func ReadMemStats(m *MemStats)

ReadMemStats populates m with memory allocator statistics.

The returned memory allocator statistics are up to date as of thecall to ReadMemStats. This is in contrast with a heap profile,which is a snapshot as of the most recently completed garbagecollection cycle.

funcReadTrace¶added ingo1.5

func ReadTrace() []byte

ReadTrace returns the next chunk of binary tracing data, blocking until datais available. If tracing is turned off and all the data accumulated while itwas on has been returned, ReadTrace returns nil. The caller must copy thereturned data before calling ReadTrace again.ReadTrace must be called from one goroutine at a time.

funcSetBlockProfileRate¶added ingo1.1

func SetBlockProfileRate(rateint)

SetBlockProfileRate controls the fraction of goroutine blocking eventsthat are reported in the blocking profile. The profiler aims to samplean 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.

funcSetCPUProfileRate¶

func SetCPUProfileRate(hzint)

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 theruntime/pprof package orthetesting package's -test.cpuprofile flag instead of callingSetCPUProfileRate directly.

funcSetCgoTraceback¶added ingo1.7

func SetCgoTraceback(versionint, traceback, context, symbolizerunsafe.Pointer)

SetCgoTraceback records three C functions to use to gathertraceback information from C code and to convert that tracebackinformation into symbolic information. These are used when printingstack traces for a program that uses cgo.

The traceback and context functions may be called from a signalhandler, and must therefore use only async-signal safe functions.The symbolizer function may be called while the program iscrashing, and so must be cautious about using memory. None of thefunctions may call back into Go.

The context function will be called with a single argument, apointer 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 torecord the current traceback context. It should record in theContext field whatever information is needed about the currentpoint of execution to later produce a stack trace, probably thestack pointer and PC. In this case the context function will becalled from C code.

If the Context field is not 0, then it is a value returned by aprevious call to the context function. This case is called when thecontext is no longer needed; that is, when the Go code is returningto its C code caller. This permits the context function to releaseany associated resources.

While it would be correct for the context function to record acomplete a stack trace whenever it is called, and simply copy thatout in the traceback function, in a typical program the contextfunction will be called many times without ever recording atraceback for that context. Recording a complete stack trace in acall to the context function is likely to be inefficient.

The traceback function will be called with a single argument, apointer to a struct:

struct {Context    uintptrSigContext uintptrBuf        *uintptrMax        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 thecurrent program execution point. In this case, the tracebackfunction will be called from C code.

Otherwise Context will be a value previously returned by a call tothe context function. The traceback function should gather a stacktrace from that saved point in the program execution. The tracebackfunction may be called from an execution thread other than the onethat recorded the context, but only when the context is known to bevalid and unchanging. The traceback function may also be calleddeeper in the call stack on the same thread that recorded thecontext. The traceback function may be called multiple times withthe same Context value; it will usually be appropriate to cache theresult, if possible, the first time this is called for a specificcontext value.

If the traceback function is called from a signal handler on a Unixsystem, SigContext will be the signal context argument passed tothe signal handler (a C ucontext_t* cast to uintptr_t). This may beused to start tracing at the point where the signal occurred. Ifthe traceback function is not called from a signal handler,SigContext will be zero.

Buf is where the traceback information should be stored. It shouldbe PC values, such that Buf[0] is the PC of the caller, Buf[1] isthe PC of that function's caller, and so on. Max is the maximumnumber of entries to store. The function should store a zero toindicate the top of the stack, or that the caller is on a differentstack, presumably a Go stack.

Unlike runtime.Callers, the PC values returned should, when passedto the symbolizer function, return the file/line of the callinstruction. No additional subtraction is required or appropriate.

On all platforms, the traceback function is invoked when a call fromGo to C to Go requests a stack trace. On linux/amd64, linux/ppc64le,linux/arm64, and freebsd/amd64, the traceback function is also invokedwhen a signal is received by a thread that is executing a cgo call.The traceback function should not make assumptions about when it iscalled, as future versions of Go may make additional calls.

The symbolizer function will be called with a single argument, apointer to a struct:

struct {PC      uintptr // program counter to fetch information forFile    *byte   // file name (NUL terminated)Lineno  uintptr // line numberFunc    *byte   // function name (NUL terminated)Entry   uintptr // function entry pointMore    uintptr // set non-zero if more info for this PCData    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 tracebackfunction.

The first time the function is called for a particular traceback,all the fields except PC will be 0. The function should fill in theother fields if possible, setting them to 0/nil if the informationis not available. The Data field may be used to store any usefulinformation across calls. The More field should be set to non-zeroif there is more information for this PC, zero otherwise. If Moreis set non-zero, the function will be called again with the samePC, and may return different information (this is intended for usewith inlined functions). If More is zero, the function will becalled with the next PC value in the traceback. When the tracebackis complete, the function will be called once more with PC set tozero; this may be used to free any information. Each call willleave the fields of the struct set to the same values they had uponreturn, except for the PC field when the More field is zero. Thefunction must not keep a copy of the struct pointer between calls.

When calling SetCgoTraceback, the version argument is the versionnumber 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 ofthe traceback function will be displayed as numbers. If thetraceback function is nil, the symbolizer function will never becalled. The context function may be nil, in which case thetraceback function will only be called with the context field setto zero. If the context function is nil, then calls from Go to Cto 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.

funcSetDefaultGOMAXPROCS¶added ingo1.25.0

func SetDefaultGOMAXPROCS()

SetDefaultGOMAXPROCS updates the GOMAXPROCS setting to the runtimedefault, as described byGOMAXPROCS, ignoring the GOMAXPROCSenvironment variable.

SetDefaultGOMAXPROCS can be used to enable the default automatic updatingGOMAXPROCS behavior if it has been disabled by the GOMAXPROCSenvironment variable or a prior call toGOMAXPROCS, or to force an immediateupdate if the caller is aware of a change to the total logical CPU count, CPUaffinity mask or cgroup quota.

funcSetFinalizer¶

func SetFinalizer(objany, finalizerany)

SetFinalizer sets the finalizer associated with obj to the providedfinalizer function. When the garbage collector finds an unreachable blockwith an associated finalizer, it clears the association and runsfinalizer(obj) in a separate goroutine. This makes obj reachable again,but now without an associated finalizer. Assuming that SetFinalizeris not called again, the next time the garbage collector seesthat obj is unreachable, it will free obj.

SetFinalizer(obj, nil) clears any finalizer associated with obj.

New Go code should consider usingAddCleanup instead, which is muchless error-prone than SetFinalizer.

The argument obj must be a pointer to an object allocated by callingnew, by taking the address of a composite literal, or by taking theaddress of a local variable.The argument finalizer must be a function that takes a single argumentto which obj's type can be assigned, and can have arbitrary ignored returnvalues. If either of these is not true, SetFinalizer may abort theprogram.

Finalizers are run in dependency order: if A points at B, both havefinalizers, and they are otherwise unreachable, only the finalizerfor A runs; once A is freed, the finalizer for B can run.If a cyclic structure includes a block with a finalizer, thatcycle is not guaranteed to be garbage collected and the finalizeris not guaranteed to run, because there is no ordering thatrespects the dependencies.

The finalizer is scheduled to run at some arbitrary time after theprogram 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 resourcesassociated with an object during a long-running program.For example, anos.File object could use a finalizer to close theassociated operating system file descriptor when a program discardsan os.File without calling Close, but it would be a mistaketo depend on a finalizer to flush an in-memory I/O buffer such as abufio.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 iszero bytes, because it may share same address with other zero-sizeobjects in memory. Seehttps://go.dev/ref/spec#Size_and_alignment_guarantees.

It is not guaranteed that a finalizer will run for objects allocatedin initializers for package-level variables. Such objects may belinker-allocated, not heap-allocated.

Note that because finalizers may execute arbitrarily far into the futureafter an object is no longer referenced, the runtime is allowed to performa space-saving optimization that batches objects together in a singleallocation slot. The finalizer for an unreferenced object in such anallocation may never run if it always exists in the same batch as areferenced 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 thatthe object is reachable until it is no longer required.Objects stored in global variables, or that can be found by tracingpointers from a global variable, are reachable. A function argument orreceiver may become unreachable at the last point where the functionmentions it. To make an unreachable object reachable, pass the objectto a call of theKeepAlive function to mark the last point in thefunction where the object must be reachable.

For example, if p points to a struct, such as os.File, that containsa file descriptor d, and p has a finalizer that closes that filedescriptor, and if the last use of p in a function is a call tosyscall.Write(p.d, buf, size), then p may be unreachable as soon asthe program enterssyscall.Write. The finalizer may run at that moment,closing p.d, causing syscall.Write to fail because it is writing toa closed file descriptor (or, worse, to an entirely differentfile 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 startinga new goroutine.

In the terminology of the Go memory model, a callSetFinalizer(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 mutexor other synchronization mechanism if it needs to access mutable state in x.For example, consider a finalizer that inspects a mutable field in xthat is modified from time to time in the main program before xbecomes unreachable and the finalizer is invoked.The modifications in the main program and the inspection in the finalizerneed to use appropriate synchronization, such as mutexes or atomic updates,to avoid read-write races.

funcSetMutexProfileFraction¶added ingo1.8

func SetMutexProfileFraction(rateint)int

SetMutexProfileFraction controls the fraction of mutex contention eventsthat are reported in the mutex profile. On average 1/rate events arereported. 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.)

funcStack¶

func Stack(buf []byte, allbool)int

Stack formats a stack trace of the calling goroutine into bufand returns the number of bytes written to buf.If all is true, Stack formats stack traces of all other goroutinesinto buf after the trace for the current goroutine.

funcStartTrace¶added ingo1.5

func StartTrace()error

StartTrace enables tracing for the current process.While tracing, the data will be buffered and available viaReadTrace.StartTrace returns an error if tracing is already enabled.Most clients should use theruntime/trace package or thetesting package's-test.trace flag instead of calling StartTrace directly.

funcStopTrace¶added ingo1.5

func StopTrace()

StopTrace stops tracing, if it was previously enabled.StopTrace only returns after all the reads for the trace have completed.

funcThreadCreateProfile¶

func ThreadCreateProfile(p []StackRecord) (nint, okbool)

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 insteadof calling ThreadCreateProfile directly.

funcUnlockOSThread¶

func UnlockOSThread()

UnlockOSThread undoes an earlier call to LockOSThread.If this drops the number of active LockOSThread calls on thecalling goroutine to zero, it unwires the calling goroutine fromits 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 OSthread is suitable for running other goroutines. If the caller madeany permanent changes to the state of the thread that would affectother goroutines, it should not call this function and thus leavethe goroutine locked to the OS thread until the goroutine (andhence the thread) exits.

funcVersion¶

func Version()string

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".

typeBlockProfileRecord¶added ingo1.1

type BlockProfileRecord struct {Countint64Cyclesint64StackRecord}

BlockProfileRecord describes blocking events originatedat a particular call sequence (stack trace).

typeCleanup¶added ingo1.24.0

type Cleanup struct {// contains filtered or unexported fields}

Cleanup is a handle to a cleanup call for a specific object.

func AddCleanup[T, Sany](ptr *T, cleanup func(S), arg S)Cleanup

package mainimport ("fmt""os""runtime")func main() {tempFile, err := os.CreateTemp(os.TempDir(), "file.*")if err != nil {fmt.Println("failed to create temp file:", err)return}ch := make(chan struct{})// Attach a cleanup function to the file object.runtime.AddCleanup(&tempFile, func(fileName string) {if err := os.Remove(fileName); err == nil {fmt.Println("temp file has been removed")}ch <- struct{}{}}, tempFile.Name())if err := tempFile.Close(); err != nil {fmt.Println("failed to close temp file:", err)return}// Run the garbage collector to reclaim unreachable objects// and enqueue their cleanup functions.runtime.GC()// Wait until cleanup function is done.<-ch}

Output:temp file has been removed

func (cCleanup) Stop()

typeError¶

type Error interface {error// RuntimeError is a no-op function but// serves to distinguish types that are runtime// errors from ordinary errors: a type is a// runtime error if it has a RuntimeError method.RuntimeError()}

Error identifies a runtime error used in panic.

The Go runtime triggers panics for a variety of cases, as described by theGo Language Spec, such as out-of-bounds slice/array access, close of nilchannels, type assertion failures, etc.

When these cases occur, the Go runtime panics with an error that implementsError. This can be useful when recovering from panics to distinguish betweencustom application panics and fundamental runtime panics.

Packages outside of the Go standard library should not implement Error.

typeFrame¶added ingo1.7

type Frame struct {// 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.PCuintptr// Func is the Func value of this call frame. This may be nil// for non-Go code or fully inlined functions.Func *Func// 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().Functionstring// 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. The file name uses// forward slashes, even on Windows.FilestringLineint// Entry point program counter for the function; may be zero// if not known. If Func is not nil then Entry ==// Func.Entry().Entryuintptr// contains filtered or unexported fields}

Frame is the information returned byFrames for each call frame.

typeFrames¶added ingo1.7

type Frames struct {// contains filtered or unexported fields}

Frames may be used to get function/file/line information for aslice of PC values returned byCallers.

package mainimport ("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.CallersFramesframes := 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()// Canonicalize function name and skip callers of this function// for predictable example output.// You probably don't need this in your own code.function := strings.ReplaceAll(frame.Function, "main.main", "runtime_test.ExampleFrames")fmt.Printf("- more:%v | %s\n", more, function)if function == "runtime_test.ExampleFrames" {break}// Check whether there are more frames to process after this one.if !more {break}}}b := func() { c() }a := func() { b() }a()}

Output:- more:true | runtime.Callers- more:true | runtime_test.ExampleFrames.func1- more:true | runtime_test.ExampleFrames.func2- more:true | runtime_test.ExampleFrames.func3- more:true | runtime_test.ExampleFrames

func CallersFrames(callers []uintptr) *Frames

func (ci *Frames) Next() (frameFrame, morebool)

typeFunc¶

type Func struct {// contains filtered or unexported fields}

A Func represents a Go function in the running binary.

func FuncForPC(pcuintptr) *Func

func (f *Func) Entry()uintptr

func (f *Func) FileLine(pcuintptr) (filestring, lineint)

func (f *Func) Name()string

typeMemProfileRecord¶

type MemProfileRecord struct {AllocBytes, FreeBytesint64// number of bytes allocated, freedAllocObjects, FreeObjectsint64// number of objects allocated, freedStack0                    [32]uintptr// stack trace for this record; ends at first 0 entry}

A MemProfileRecord describes the live objects allocatedby a particular call sequence (stack trace).

func (r *MemProfileRecord) InUseBytes()int64

func (r *MemProfileRecord) InUseObjects()int64

func (r *MemProfileRecord) Stack() []uintptr

typeMemStats¶

type MemStats struct {// Alloc is bytes of allocated heap objects.//// This is the same as HeapAlloc (see below).Allocuint64// 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.TotalAllocuint64// 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.Sysuint64// Lookups is the number of pointer lookups performed by the// runtime.//// This is primarily useful for debugging runtime internals.Lookupsuint64// Mallocs is the cumulative count of heap objects allocated.// The number of live objects is Mallocs - Frees.Mallocsuint64// Frees is the cumulative count of heap objects freed.Freesuint64// 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).HeapAllocuint64// 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.HeapSysuint64// 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.HeapIdleuint64// 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.HeapInuseuint64// 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.HeapReleaseduint64// 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.HeapObjectsuint64// 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).StackInuseuint64// 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.StackSysuint64// MSpanInuse is bytes of allocated mspan structures.MSpanInuseuint64// MSpanSys is bytes of memory obtained from the OS for mspan// structures.MSpanSysuint64// MCacheInuse is bytes of allocated mcache structures.MCacheInuseuint64// MCacheSys is bytes of memory obtained from the OS for// mcache structures.MCacheSysuint64// BuckHashSys is bytes of memory in profiling bucket hash tables.BuckHashSysuint64// GCSys is bytes of memory in garbage collection metadata.GCSysuint64// OtherSys is bytes of memory in miscellaneous off-heap// runtime allocations.OtherSysuint64// 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.NextGCuint64// LastGC is the time the last garbage collection finished, as// nanoseconds since 1970 (the UNIX epoch).LastGCuint64// 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.PauseTotalNsuint64// 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.PauseNs [256]uint64// 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.PauseEnd [256]uint64// NumGC is the number of completed GC cycles.NumGCuint32// NumForcedGC is the number of GC cycles that were forced by// the application calling the GC function.NumForcedGCuint32// 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.GCCPUFractionfloat64// EnableGC indicates that GC is enabled. It is always true,// even if GOGC=off.EnableGCbool// DebugGC is currently unused.DebugGCbool// 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.BySize [61]struct {// Size is the maximum byte size of an object in this// size class.Sizeuint32// Mallocs is the cumulative count of heap objects// allocated in this size class. The cumulative bytes// of allocation is Size*Mallocs. The number of live// objects in this size class is Mallocs - Frees.Mallocsuint64// Frees is the cumulative count of heap objects freed// in this size class.Freesuint64}}

A MemStats records statistics about the memory allocator.

typePanicNilError¶added ingo1.21.0

type PanicNilError struct {// contains filtered or unexported fields}

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.

func (*PanicNilError) Error()string

func (*PanicNilError) RuntimeError()

typePinner¶added ingo1.21.0

type Pinner struct {// contains filtered or unexported fields}

A Pinner is a set of Go objects each pinned to a fixed location in memory. ThePinner.Pin method pins one object, whilePinner.Unpin unpins all pinnedobjects. See their comments for more information.

func (p *Pinner) Pin(pointerany)

func (p *Pinner) Unpin()

typeStackRecord¶

type StackRecord struct {Stack0 [32]uintptr// stack trace for this record; ends at first 0 entry}

A StackRecord describes a single execution stack.

func (r *StackRecord) Stack() []uintptr

typeTypeAssertionError¶

type TypeAssertionError struct {// contains filtered or unexported fields}

A TypeAssertionError explains a failed type assertion.

func (e *TypeAssertionError) Error()string

func (*TypeAssertionError) RuntimeError()