version: 1.10

package runtime

import "runtime"

Overview

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. The
runtime/debug package’s SetGCPercent function allows changing this percentage at
run time. See https://golang.org/pkg/runtime/debug/#SetGCPercent.

The GODEBUG variable controls debugging variables within the runtime. It is a
comma-separated list of name=val pairs setting these named variables:

  1. allocfreetrace: setting allocfreetrace=1 causes every allocation to be
  2. profiled and a stack trace printed on each object's allocation and free.
  4. cgocheck: setting cgocheck=0 disables all checks for packages
  5. using cgo to incorrectly pass Go pointers to non-Go code.
  6. Setting cgocheck=1 (the default) enables relatively cheap
  7. checks that may miss some errors.  Setting cgocheck=2 enables
  8. expensive checks that should not miss any errors, but will
  9. cause your program to run slower.
  11. efence: setting efence=1 causes the allocator to run in a mode
  12. where each object is allocated on a unique page and addresses are
  13. never recycled.
  15. gccheckmark: setting gccheckmark=1 enables verification of the
  16. garbage collector's concurrent mark phase by performing a
  17. second mark pass while the world is stopped.  If the second
  18. pass finds a reachable object that was not found by concurrent
  19. mark, the garbage collector will panic.
  21. gcpacertrace: setting gcpacertrace=1 causes the garbage collector to
  22. print information about the internal state of the concurrent pacer.
  24. gcshrinkstackoff: setting gcshrinkstackoff=1 disables moving goroutines
  25. onto smaller stacks. In this mode, a goroutine's stack can only grow.
  27. gcrescanstacks: setting gcrescanstacks=1 enables stack
  28. re-scanning during the STW mark termination phase. This is
  29. helpful for debugging if objects are being prematurely
  30. garbage collected.
  32. gcstoptheworld: setting gcstoptheworld=1 disables concurrent garbage collection,
  33. making every garbage collection a stop-the-world event. Setting gcstoptheworld=2
  34. also disables concurrent sweeping after the garbage collection finishes.
  36. gctrace: setting gctrace=1 causes the garbage collector to emit a single line to standard
  37. error at each collection, summarizing the amount of memory collected and the
  38. length of the pause. Setting gctrace=2 emits the same summary but also
  39. repeats each collection. The format of this line is subject to change.
  40. Currently, it is:
  41.     gc # @#s #%: #+#+# ms clock, #+#/#/#+# ms cpu, #->#-># MB, # MB goal, # P
  42. where the fields are as follows:
  43.     gc #        the GC number, incremented at each GC
  44.     @#s         time in seconds since program start
  45.     #%          percentage of time spent in GC since program start
  46.     #+...+#     wall-clock/CPU times for the phases of the GC
  47.     #->#-># MB  heap size at GC start, at GC end, and live heap
  48.     # MB goal   goal heap size
  49.     # P         number of processors used
  50. The phases are stop-the-world (STW) sweep termination, concurrent
  51. mark and scan, and STW mark termination. The CPU times
  52. for mark/scan are broken down in to assist time (GC performed in
  53. line with allocation), background GC time, and idle GC time.
  54. If the line ends with "(forced)", this GC was forced by a
  55. runtime.GC() call.
  57. Setting gctrace to any value > 0 also causes the garbage collector
  58. to emit a summary when memory is released back to the system.
  59. This process of returning memory to the system is called scavenging.
  60. The format of this summary is subject to change.
  61. Currently it is:
  62.     scvg#: # MB released  printed only if non-zero
  63.     scvg#: inuse: # idle: # sys: # released: # consumed: # (MB)
  64. where the fields are as follows:
  65.     scvg#        the scavenge cycle number, incremented at each scavenge
  66.     inuse: #     MB used or partially used spans
  67.     idle: #      MB spans pending scavenging
  68.     sys: #       MB mapped from the system
  69.     released: #  MB released to the system
  70.     consumed: #  MB allocated from the system
  72. memprofilerate: setting memprofilerate=X will update the value of runtime.MemProfileRate.
  73. When set to 0 memory profiling is disabled.  Refer to the description of
  74. MemProfileRate for the default value.
  76. invalidptr: defaults to invalidptr=1, causing the garbage collector and stack
  77. copier to crash the program if an invalid pointer value (for example, 1)
  78. is found in a pointer-typed location. Setting invalidptr=0 disables this check.
  79. This should only be used as a temporary workaround to diagnose buggy code.
  80. The real fix is to not store integers in pointer-typed locations.
  82. sbrk: setting sbrk=1 replaces the memory allocator and garbage collector
  83. with a trivial allocator that obtains memory from the operating system and
  84. never reclaims any memory.
  86. scavenge: scavenge=1 enables debugging mode of heap scavenger.
  88. scheddetail: setting schedtrace=X and scheddetail=1 causes the scheduler to emit
  89. detailed multiline info every X milliseconds, describing state of the scheduler,
  90. processors, threads and goroutines.
  92. schedtrace: setting schedtrace=X causes the scheduler to emit a single line to standard
  93. error every X milliseconds, summarizing the scheduler state.

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 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 likesystem’’ 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. For historical reasons, the GOTRACEBACK settings 0, 1, and 2 are
synonyms for none, all, and system, respectively. The runtime/debug package’s
SetTraceback function allows increasing the amount of output at run time, but it
cannot reduce the amount below that specified by the environment variable. See
https://golang.org/pkg/runtime/debug/#SetTraceback.

The GOARCH, GOOS, GOPATH, and GOROOT environment variables complete the set of
Go environment variables. They influence the building of Go programs (see
https://golang.org/cmd/go and https://golang.org/pkg/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.

Index

Examples

Package files

alg.go atomic_pointer.go cgo.go cgo_mmap.go cgo_sigaction.go cgocall.go cgocallback.go cgocheck.go chan.go compiler.go complex.go cpuflags_amd64.go cpuprof.go cputicks.go debug.go defs_linux_amd64.go env_posix.go error.go extern.go fastlog2.go fastlog2table.go float.go hash64.go hashmap.go hashmap_fast.go heapdump.go iface.go lfstack.go lfstack_64bit.go lock_futex.go malloc.go mbarrier.go mbitmap.go mcache.go mcentral.go mem_linux.go mfinal.go mfixalloc.go mgc.go mgclarge.go mgcmark.go mgcsweep.go mgcsweepbuf.go mgcwork.go mheap.go mprof.go msan0.go msize.go mstats.go mwbbuf.go netpoll.go netpoll_epoll.go os_linux.go os_linux_generic.go panic.go plugin.go print.go proc.go profbuf.go proflabel.go race0.go rdebug.go relax_stub.go runtime.go runtime1.go runtime2.go rwmutex.go select.go sema.go signal_amd64x.go signal_linux_amd64.go signal_sighandler.go signal_unix.go sigqueue.go sigtab_linux_generic.go sizeclasses.go slice.go softfloat64.go sqrt.go stack.go string.go stubs.go stubs2.go stubs_asm.go stubs_linux.go symtab.go sys_nonppc64x.go sys_x86.go time.go timestub.go trace.go traceback.go type.go typekind.go unaligned1.go utf8.go vdso_linux.go vdso_linux_amd64.go write_err.go

Constants

  1. const Compiler = "gc"

Compiler is the name of the compiler toolchain that built the running binary.
Known toolchains are:

  1. gc      Also known as cmd/compile.
  2. gccgo   The gccgo front end, part of the GCC compiler suite.
  1. const GOARCH string = sys.GOARCH

GOARCH is the running program’s architecture target: one of 386, amd64, arm,
s390x, and so on.

  1. const GOOS string = sys.GOOS

GOOS is the running program’s operating system target: one of darwin, freebsd,
linux, and so on.

Variables

  1. var MemProfileRate int = 512 * 1024

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

func BlockProfile

  1. func BlockProfile(p []BlockProfileRecord) (n int, ok bool)

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.

func Breakpoint

  1. func Breakpoint()

Breakpoint executes a breakpoint trap.

func CPUProfile

  1. func CPUProfile() []byte

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.

func Caller

  1. func Caller(skip int) (pc uintptr, file string, line int, ok bool)

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.

func Callers

  1. func Callers(skip int, pc []uintptr) int

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.

func GC

  1. func GC()

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

func GOMAXPROCS

  1. func GOMAXPROCS(n int) int

GOMAXPROCS sets the maximum number of CPUs that can be executing simultaneously
and returns the previous setting. If n < 1, it does not change the current
setting. The number of logical CPUs on the local machine can be queried with
NumCPU. This call will go away when the scheduler improves.

func GOROOT

  1. func GOROOT() string

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.

func Goexit

  1. func Goexit()

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.

func GoroutineProfile

  1. func GoroutineProfile(p []StackRecord) (n int, ok bool)

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.

func Gosched

  1. func Gosched()

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

func KeepAlive

  1. func KeepAlive(x interface{})

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:

  1. type File struct { d int }
  2. d, err := syscall.Open("/file/path", syscall.O_RDONLY, 0)
  3. // ... do something if err != nil ...
  4. p := &File{d}
  5. runtime.SetFinalizer(p, func(p *File) { syscall.Close(p.d) })
  6. var buf [10]byte
  7. n, err := syscall.Read(p.d, buf[:])
  8. // Ensure p is not finalized until Read returns.
  9. runtime.KeepAlive(p)
  10. // 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.

func LockOSThread

  1. 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 to
UnlockOSThread as to LockOSThread. If the calling goroutine exits without
unlocking the thread, the thread will be terminated.

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

func MemProfile

  1. func MemProfile(p []MemProfileRecord, inuseZero bool) (n int, ok bool)

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.

func MutexProfile

  1. func MutexProfile(p []BlockProfileRecord) (n int, ok bool)

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.

func NumCPU

  1. 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 system at process
startup. Changes to operating system CPU allocation after process startup are
not reflected.

func NumCgoCall

  1. func NumCgoCall() int64

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

func NumGoroutine

  1. func NumGoroutine() int

NumGoroutine returns the number of goroutines that currently exist.

func ReadMemStats

  1. func ReadMemStats(m *MemStats)

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.

func ReadTrace

  1. func ReadTrace() []byte

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.

func SetBlockProfileRate

  1. func SetBlockProfileRate(rate int)

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.

func SetCPUProfileRate

  1. func SetCPUProfileRate(hz int)

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.

func SetCgoTraceback

  1. func SetCgoTraceback(version int, traceback, context, symbolizer unsafe.Pointer)

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:

  1. struct {
  2.     Context uintptr
  3. }

In C syntax, this struct will be

  1. struct {
  2.     uintptr_t Context;
  3. };

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:

  1. struct {
  2.     Context    uintptr
  3.     SigContext uintptr
  4.     Buf        *uintptr
  5.     Max        uintptr
  6. }

In C syntax, this struct will be

  1. struct {
  2.     uintptr_t  Context;
  3.     uintptr_t  SigContext;
  4.     uintptr_t* Buf;
  5.     uintptr_t  Max;
  6. };

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.

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

  1. struct {
  2.     PC      uintptr // program counter to fetch information for
  3.     File    *byte   // file name (NUL terminated)
  4.     Lineno  uintptr // line number
  5.     Func    *byte   // function name (NUL terminated)
  6.     Entry   uintptr // function entry point
  7.     More    uintptr // set non-zero if more info for this PC
  8.     Data    uintptr // unused by runtime, available for function
  9. }

In C syntax, this struct will be

  1. struct {
  2.     uintptr_t PC;
  3.     char*     File;
  4.     uintptr_t Lineno;
  5.     char*     Func;
  6.     uintptr_t Entry;
  7.     uintptr_t More;
  8.     uintptr_t Data;
  9. };

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.

func SetFinalizer

  1. func SetFinalizer(obj interface{}, finalizer interface{})

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 for obj is scheduled to run at some arbitrary time after obj
becomes unreachable. 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.

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.

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

func SetMutexProfileFraction

  1. func SetMutexProfileFraction(rate int) int

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 -1. (For n>1 the details of sampling may change.)

func Stack

  1. func Stack(buf []byte, all bool) int

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.

func StartTrace

  1. func StartTrace() error

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.

func StopTrace

  1. func StopTrace()

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

func ThreadCreateProfile

  1. func ThreadCreateProfile(p []StackRecord) (n int, ok bool)

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.

func UnlockOSThread

  1. func UnlockOSThread()

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.

func Version

  1. 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”.

type BlockProfileRecord

  1. type BlockProfileRecord struct {
  2.     Count  int64
  3.     Cycles int64
  4.     StackRecord
  5. }

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

type Error

  1. type Error interface {
  2.     error
  3.  
  4.     // RuntimeError is a no-op function but
  5.     // serves to distinguish types that are run time
  6.     // errors from ordinary errors: a type is a
  7.     // run time error if it has a RuntimeError method.
  8.     RuntimeError()
  9. }

The Error interface identifies a run time error.

type Frame

  1. type Frame struct {
  2.     // PC is the program counter for the location in this frame.
  3.     // For a frame that calls another frame, this will be the
  4.     // program counter of a call instruction. Because of inlining,
  5.     // multiple frames may have the same PC value, but different
  6.     // symbolic information.
  7.     PC uintptr
  8.  
  9.     // Func is the Func value of this call frame. This may be nil
  10.     // for non-Go code or fully inlined functions.
  11.     Func *Func
  12.  
  13.     // Function is the package path-qualified function name of
  14.     // this call frame. If non-empty, this string uniquely
  15.     // identifies a single function in the program.
  16.     // This may be the empty string if not known.
  17.     // If Func is not nil then Function == Func.Name().
  18.     Function string
  19.  
  20.     // File and Line are the file name and line number of the
  21.     // location in this frame. For non-leaf frames, this will be
  22.     // the location of a call. These may be the empty string and
  23.     // zero, respectively, if not known.
  24.     File string
  25.     Line int
  26.  
  27.     // Entry point program counter for the function; may be zero
  28.     // if not known. If Func is not nil then Entry ==
  29.     // Func.Entry().
  30.     Entry uintptr
  31. }

Frame is the information returned by Frames for each call frame.

type Frames

  1. type Frames struct {
  2.     // contains filtered or unexported fields
  3. }

Frames may be used to get function/file/line information for a slice of PC
values returned by Callers.


Example:

  1. c := func() {
  2.     // Ask runtime.Callers for up to 10 pcs, including runtime.Callers itself.
  3.     pc := make([]uintptr, 10)
  4.     n := runtime.Callers(0, pc)
  5.     if n == 0 {
  6.         // No pcs available. Stop now.
  7.         // This can happen if the first argument to runtime.Callers is large.
  8.         return
  9.     }
  11.     pc = pc[:n] // pass only valid pcs to runtime.CallersFrames
  12.     frames := runtime.CallersFrames(pc)
  14.     // Loop to get frames.
  15.     // A fixed number of pcs can expand to an indefinite number of Frames.
  16.     for {
  17.         frame, more := frames.Next()
  18.         // To keep this example's output stable
  19.         // even if there are changes in the testing package,
  20.         // stop unwinding when we leave package runtime.
  21.         if !strings.Contains(frame.File, "runtime/") {
  22.             break
  23.         }
  24.         fmt.Printf("- more:%v | %s\n", more, frame.Function)
  25.         if !more {
  26.             break
  27.         }
  28.     }
  29. }
  31. b := func() { c() }
  32. a := func() { b() }
  34. a()
  35. // Output:
  36. // - more:true | runtime.Callers
  37. // - more:true | runtime_test.ExampleFrames.func1
  38. // - more:true | runtime_test.ExampleFrames.func2
  39. // - more:true | runtime_test.ExampleFrames.func3
  40. // - more:true | runtime_test.ExampleFrames

func CallersFrames

  1. func CallersFrames(callers []uintptr) *Frames

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.

func (*Frames) Next

  1. func (ci *Frames) Next() (frame Frame, more bool)

Next returns frame information for the next caller. If more is false, there are
no more callers (the Frame value is valid).

type Func

  1. type Func struct {
  2.     // contains filtered or unexported fields
  3. }

A Func represents a Go function in the running binary.

func FuncForPC

  1. func FuncForPC(pc uintptr) *Func

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 outermost function.

func (*Func) Entry

  1. func (f *Func) Entry() uintptr

Entry returns the entry address of the function.

func (*Func) FileLine

  1. func (f *Func) FileLine(pc uintptr) (file string, line int)

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.

func (*Func) Name

  1. func (f *Func) Name() string

Name returns the name of the function.

type MemProfileRecord

  1. type MemProfileRecord struct {
  2.     AllocBytes, FreeBytes     int64       // number of bytes allocated, freed
  3.     AllocObjects, FreeObjects int64       // number of objects allocated, freed
  4.     Stack0                    [32]uintptr // stack trace for this record; ends at first 0 entry
  5. }

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

func (*MemProfileRecord) InUseBytes

  1. func (r *MemProfileRecord) InUseBytes() int64

InUseBytes returns the number of bytes in use (AllocBytes - FreeBytes).

func (*MemProfileRecord) InUseObjects

  1. func (r *MemProfileRecord) InUseObjects() int64

InUseObjects returns the number of objects in use (AllocObjects - FreeObjects).

func (*MemProfileRecord) Stack

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

Stack returns the stack trace associated with the record, a prefix of r.Stack0.

type MemStats

  1. type MemStats struct {
  2.  
  3.     // Alloc is bytes of allocated heap objects.
  4.     //
  5.     // This is the same as HeapAlloc (see below).
  6.     Alloc uint64
  7.  
  8.     // TotalAlloc is cumulative bytes allocated for heap objects.
  9.     //
  10.     // TotalAlloc increases as heap objects are allocated, but
  11.     // unlike Alloc and HeapAlloc, it does not decrease when
  12.     // objects are freed.
  13.     TotalAlloc uint64
  14.  
  15.     // Sys is the total bytes of memory obtained from the OS.
  16.     //
  17.     // Sys is the sum of the XSys fields below. Sys measures the
  18.     // virtual address space reserved by the Go runtime for the
  19.     // heap, stacks, and other internal data structures. It's
  20.     // likely that not all of the virtual address space is backed
  21.     // by physical memory at any given moment, though in general
  22.     // it all was at some point.
  23.     Sys uint64
  24.  
  25.     // Lookups is the number of pointer lookups performed by the
  26.     // runtime.
  27.     //
  28.     // This is primarily useful for debugging runtime internals.
  29.     Lookups uint64
  30.  
  31.     // Mallocs is the cumulative count of heap objects allocated.
  32.     // The number of live objects is Mallocs - Frees.
  33.     Mallocs uint64
  34.  
  35.     // Frees is the cumulative count of heap objects freed.
  36.     Frees uint64
  37.  
  38.     // HeapAlloc is bytes of allocated heap objects.
  39.     //
  40.     // "Allocated" heap objects include all reachable objects, as
  41.     // well as unreachable objects that the garbage collector has
  42.     // not yet freed. Specifically, HeapAlloc increases as heap
  43.     // objects are allocated and decreases as the heap is swept
  44.     // and unreachable objects are freed. Sweeping occurs
  45.     // incrementally between GC cycles, so these two processes
  46.     // occur simultaneously, and as a result HeapAlloc tends to
  47.     // change smoothly (in contrast with the sawtooth that is
  48.     // typical of stop-the-world garbage collectors).
  49.     HeapAlloc uint64
  50.  
  51.     // HeapSys is bytes of heap memory obtained from the OS.
  52.     //
  53.     // HeapSys measures the amount of virtual address space
  54.     // reserved for the heap. This includes virtual address space
  55.     // that has been reserved but not yet used, which consumes no
  56.     // physical memory, but tends to be small, as well as virtual
  57.     // address space for which the physical memory has been
  58.     // returned to the OS after it became unused (see HeapReleased
  59.     // for a measure of the latter).
  60.     //
  61.     // HeapSys estimates the largest size the heap has had.
  62.     HeapSys uint64
  63.  
  64.     // HeapIdle is bytes in idle (unused) spans.
  65.     //
  66.     // Idle spans have no objects in them. These spans could be
  67.     // (and may already have been) returned to the OS, or they can
  68.     // be reused for heap allocations, or they can be reused as
  69.     // stack memory.
  70.     //
  71.     // HeapIdle minus HeapReleased estimates the amount of memory
  72.     // that could be returned to the OS, but is being retained by
  73.     // the runtime so it can grow the heap without requesting more
  74.     // memory from the OS. If this difference is significantly
  75.     // larger than the heap size, it indicates there was a recent
  76.     // transient spike in live heap size.
  77.     HeapIdle uint64
  78.  
  79.     // HeapInuse is bytes in in-use spans.
  80.     //
  81.     // In-use spans have at least one object in them. These spans
  82.     // can only be used for other objects of roughly the same
  83.     // size.
  84.     //
  85.     // HeapInuse minus HeapAlloc estimates the amount of memory
  86.     // that has been dedicated to particular size classes, but is
  87.     // not currently being used. This is an upper bound on
  88.     // fragmentation, but in general this memory can be reused
  89.     // efficiently.
  90.     HeapInuse uint64
  91.  
  92.     // HeapReleased is bytes of physical memory returned to the OS.
  93.     //
  94.     // This counts heap memory from idle spans that was returned
  95.     // to the OS and has not yet been reacquired for the heap.
  96.     HeapReleased uint64
  97.  
  98.     // HeapObjects is the number of allocated heap objects.
  99.     //
  100.     // Like HeapAlloc, this increases as objects are allocated and
  101.     // decreases as the heap is swept and unreachable objects are
  102.     // freed.
  103.     HeapObjects uint64
  104.  
  105.     // StackInuse is bytes in stack spans.
  106.     //
  107.     // In-use stack spans have at least one stack in them. These
  108.     // spans can only be used for other stacks of the same size.
  109.     //
  110.     // There is no StackIdle because unused stack spans are
  111.     // returned to the heap (and hence counted toward HeapIdle).
  112.     StackInuse uint64
  113.  
  114.     // StackSys is bytes of stack memory obtained from the OS.
  115.     //
  116.     // StackSys is StackInuse, plus any memory obtained directly
  117.     // from the OS for OS thread stacks (which should be minimal).
  118.     StackSys uint64
  119.  
  120.     // MSpanInuse is bytes of allocated mspan structures.
  121.     MSpanInuse uint64
  122.  
  123.     // MSpanSys is bytes of memory obtained from the OS for mspan
  124.     // structures.
  125.     MSpanSys uint64
  126.  
  127.     // MCacheInuse is bytes of allocated mcache structures.
  128.     MCacheInuse uint64
  129.  
  130.     // MCacheSys is bytes of memory obtained from the OS for
  131.     // mcache structures.
  132.     MCacheSys uint64
  133.  
  134.     // BuckHashSys is bytes of memory in profiling bucket hash tables.
  135.     BuckHashSys uint64
  136.  
  137.     // GCSys is bytes of memory in garbage collection metadata.
  138.     GCSys uint64
  139.  
  140.     // OtherSys is bytes of memory in miscellaneous off-heap
  141.     // runtime allocations.
  142.     OtherSys uint64
  143.  
  144.     // NextGC is the target heap size of the next GC cycle.
  145.     //
  146.     // The garbage collector's goal is to keep HeapAlloc ≤ NextGC.
  147.     // At the end of each GC cycle, the target for the next cycle
  148.     // is computed based on the amount of reachable data and the
  149.     // value of GOGC.
  150.     NextGC uint64
  151.  
  152.     // LastGC is the time the last garbage collection finished, as
  153.     // nanoseconds since 1970 (the UNIX epoch).
  154.     LastGC uint64
  155.  
  156.     // PauseTotalNs is the cumulative nanoseconds in GC
  157.     // stop-the-world pauses since the program started.
  158.     //
  159.     // During a stop-the-world pause, all goroutines are paused
  160.     // and only the garbage collector can run.
  161.     PauseTotalNs uint64
  162.  
  163.     // PauseNs is a circular buffer of recent GC stop-the-world
  164.     // pause times in nanoseconds.
  165.     //
  166.     // The most recent pause is at PauseNs[(NumGC+255)%256]. In
  167.     // general, PauseNs[N%256] records the time paused in the most
  168.     // recent N%256th GC cycle. There may be multiple pauses per
  169.     // GC cycle; this is the sum of all pauses during a cycle.
  170.     PauseNs [256]uint64
  171.  
  172.     // PauseEnd is a circular buffer of recent GC pause end times,
  173.     // as nanoseconds since 1970 (the UNIX epoch).
  174.     //
  175.     // This buffer is filled the same way as PauseNs. There may be
  176.     // multiple pauses per GC cycle; this records the end of the
  177.     // last pause in a cycle.
  178.     PauseEnd [256]uint64
  179.  
  180.     // NumGC is the number of completed GC cycles.
  181.     NumGC uint32
  182.  
  183.     // NumForcedGC is the number of GC cycles that were forced by
  184.     // the application calling the GC function.
  185.     NumForcedGC uint32
  186.  
  187.     // GCCPUFraction is the fraction of this program's available
  188.     // CPU time used by the GC since the program started.
  189.     //
  190.     // GCCPUFraction is expressed as a number between 0 and 1,
  191.     // where 0 means GC has consumed none of this program's CPU. A
  192.     // program's available CPU time is defined as the integral of
  193.     // GOMAXPROCS since the program started. That is, if
  194.     // GOMAXPROCS is 2 and a program has been running for 10
  195.     // seconds, its "available CPU" is 20 seconds. GCCPUFraction
  196.     // does not include CPU time used for write barrier activity.
  197.     //
  198.     // This is the same as the fraction of CPU reported by
  199.     // GODEBUG=gctrace=1.
  200.     GCCPUFraction float64
  201.  
  202.     // EnableGC indicates that GC is enabled. It is always true,
  203.     // even if GOGC=off.
  204.     EnableGC bool
  205.  
  206.     // DebugGC is currently unused.
  207.     DebugGC bool
  208.  
  209.     // BySize reports per-size class allocation statistics.
  210.     //
  211.     // BySize[N] gives statistics for allocations of size S where
  212.     // BySize[N-1].Size < S ≤ BySize[N].Size.
  213.     //
  214.     // This does not report allocations larger than BySize[60].Size.
  215.     BySize [61]struct {
  216.         // Size is the maximum byte size of an object in this
  217.         // size class.
  218.         Size uint32
  219.  
  220.         // Mallocs is the cumulative count of heap objects
  221.         // allocated in this size class. The cumulative bytes
  222.         // of allocation is Size*Mallocs. The number of live
  223.         // objects in this size class is Mallocs - Frees.
  224.         Mallocs uint64
  225.  
  226.         // Frees is the cumulative count of heap objects freed
  227.         // in this size class.
  228.         Frees uint64
  229.     }
  230. }

A MemStats records statistics about the memory allocator.

type StackRecord

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

A StackRecord describes a single execution stack.

func (*StackRecord) Stack

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

Stack returns the stack trace associated with the record, a prefix of r.Stack0.

type TypeAssertionError

  1. type TypeAssertionError struct {
  2.     // contains filtered or unexported fields
  3. }

A TypeAssertionError explains a failed type assertion.

func (*TypeAssertionError) Error

  1. func (e *TypeAssertionError) Error() string

func (*TypeAssertionError) RuntimeError

  1. func (*TypeAssertionError) RuntimeError()

Subdirectories