runtime

package
v0.0.0-...-d433f40 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 21, 2022 License: MIT Imports: 6 Imported by: 0

README

Go 运行时编程

本文可能会过时。 它旨在阐明不同于常规 Go 编程的 Go 运行时编程，并侧重于一般概念而非特定接口的详细信息。

调度器结构

调度器管理了三种不同类型的资源分布在运行时中：G, M, P。 即便你进行不涉及调度器的相关工作，理解它们仍然很重要。

Gs, Ms, Ps

"G" 是 goroutine 的缩写。由 g 类型表示。当 goroutine 退出时，g 被归还到有效的 g 池， 能够被后续 goroutine 使用。

"M" 代表一个能够执行用户 Go 代码、运行时代码、系统调用或处于空闲状态的 OS thread。 由类型 m 表示。因为任意多个线程可以同时阻塞在系统调用上，因此同一时刻可以包含任意多个 M。

"P" 则表示执行 Go 代码所需的资源，例如调度器和内存分配器状态。由 p 类型表示,且最多只有 GOMAXPROCS 个。 P 可以理解一个 OS 调度器中的 CPU，p 类型的内容类似于每个 CPU 的状态。是一个可以为了效率 而存放不同状态的地方，同时还不需要每个线程或者每个 goroutine 对应一个 P。

调度器的任务是匹配一个 G（要执行的代码）一个 M（在哪儿执行）和一个 P（执行代码的资源和权利）。 当 M 停止执行用户 Go 代码时，例如进入系统调用，它会将其对应的 P 返回给空闲 P 池。 而为了恢复执行用户的 Go 代码，例如从一个系统调用返回时，必须从空闲池中获取一个有效的 P。

所有的 g, m 和 p 对象均在堆上分配，且从不释放。因此他们的内存保持 type stable。 因此，运行时可以在调度器内避免 write barrier。

用户栈与系统栈

每个非 dead 状态的 G 均被关联到用户栈上，即用户 Go 代码执行的地方。用户栈初始大小很小（例如 2K）， 然后动态的增加或减少。

每个 M 均对应一个关联的系统栈（也成为 M 的 g0 栈，因为其作为一个 stub G 来实现）。在 Unix 平台上， 则称为信号栈（也称之为 M 的 gsignal 栈）。系统和信号栈无法扩展，但已经大到足够运行运行时和 cgo 代码（一个纯 Go 二进制文件有 8K；而 cgo 二进制文件则有系统分配）。

运行时代码经常会临时通过 systemstack, mcall 或 asmcgocall 切换到系统栈以执行那些无法扩展用户栈、 或切换用户 goroutine 的不可抢占式任务。运行在系统栈上的代码是隐式不可抢占的、且不会被垃圾回收检测。 当运行在系统栈上时，当前用户栈没有被用于执行代码。

getg() 与 getg().m.curg

为获取当前用户 g，可以使用 getg().m.curg。

getg() 单独返回当前 g。但当执行在系统或信号栈时，会返回当前 M 的 g0 或 gsignal。 这通常可能不是你想要的。

为判断你是运行在用户栈还是系统栈，可以使用：getg() == getg().m.curg

错误处理与报告

通常使用 panic 的来自用户代码的错误能够被合理的恢复。然而某些情况下 panic 会导致一个立即致命错误， 例如在系统栈上的调用或在 mallocgc 执行阶段的调用。

大部分运行时错误无法恢复。对于这些错误，请使用 throw，它能够将被终止整个过程的中间状态全部回溯出来。 一般情况下，throw 需要传递一个 string 常量在危险情况下避免内存分配。按照惯例，在 throw 前会使用 print 或 println 输出额外信息，并冠以 "runtime:" 的前缀。

若需调试运行时错误，可以设置 GOTRACEBACK=system 或 GOTRACEBACK=crash。

同步

运行时有多种同步机制。它们根据与 goroutine 调度器或者 OS 调度器的交互不同而有着不同的语义。

最简单的是 mutex，使用 lock 和 unlock 进行操作。用于在短时间内共享结构体。 在 mutex 上阻塞会直接阻塞 M，且不会与 Go 调度器进行交互。这也就意味着它能在运行时最底层是安全的， 且同时阻止了任何与之关联的 G 和 P 被重新调度。rwmutex 也类似。

为进行一次性通知，可以使用 note。它提供了 notesleep 和 notewakeup。 与传统的 UNIX sleep/wakeup 不同，note 是无竞争的。 因此notesleep 会在 notewakeup 发生时立即返回。一个 note 能够在使用 noteclear 后被重置， 并且必须不能与 sleep 或 wakeup 产生竞争。类似于 mutex，阻塞在 note 上会阻塞 M。 然而有很多不同的方式可以在 note 上进行休眠：notesleep 会阻止关联的 G 和 P 被重新调度， 而 notetsleepg 的行为类似于阻止系统调用、运行 P 被复用从而运行另一个 G。 这种方式仍然比直接 阻塞一个 G 效率低，因为它还消耗了一个 M。

为直接与 goroutine 调度器进行交互，可以使用 gopark、goready。 gopark 停摆了一个当前的 goroutine，并将其放入 waiting 状态，并将其从调度器运行队列中移除， 再进一步将其他 goroutine 在当前 M/P 上进行调度。而 goready 会将一个停摆的 goroutine 标回 tunable 状态，并加入运行队列中。

总结：

阻塞
接口GMP
(rw)mutex是是是
note是是是/否
park是否否

原子操作

运行时拥有自己的原子操作包，位于 runtime/internal/atomic。其对应于 sync/atomic，但处于历史原因函数具有不同的名字以及一些额外的运行时所需的函数。

一般来说，我们都仔细考虑了在运行始终使用这些原子操作，并尽可能避免了不必要的原子操作。如果某个时候访问一个某些时候会被其他同步机制保护的变量，那么访问已经受保护的内容通常不需要成为原子操作，原因如下：

  1. 在适当的时候使用非原子或原子操作访问会使代码更明确。对于变量的原子访问意味着其他地方可能同时访问该变量。
  2. 非原子访问能够自动进行竞争检查。运行时目前并没有竞争检查器，但未来可能会有。运行竞争检查器来检查你非原子访问的假设时，原子访问会破坏竞争检查器。
  3. 非原子访问能够提升性能。

当然，对一个共享变量进行任何非原子访问需要解释为什么该访问是受到保护的。

混合原子访问和费原子访问的常见模式为：

  • 读通过写锁进行的变量，在锁区域内，读不需要原子操作，而写是需要的。在锁定区外，读是需要原子操作的。

  • 读取仅发生在 STW 期间（Stop-The-World）。在 STW 期间不会发生写入 STW，即不需要原子操作。

换句话说，Go 内存模型的建议是：『不要太聪明』。运行时的性能很重要，但它的健壮性更重要。

非托管内存

通常，运行时尝试使用常规堆分配。然而，在某些情况下，运行时必须非托管内存中分配垃圾回收堆之外的对象。如果对象是内存管理器的一部分，或者必须在调用者可能没有 P 的情况下分他们，则这些分配和回收是有必要的。

分配非托管内存有三种机制：

  • sysAlloc 直接从 OS 获取内存。这会是系统页大小的整数倍，但也可以使用 sysFree 进行释放。

  • persistentalloc 将多个较小的分配组合到一个 sysAlloc 中避免碎片。但没有办法释放 persistentalloc 对象（所以叫这个名字）。

  • fixalloc 是一个 SLAB 样式的分配器，用于分配固定大小的对象。fixalloced 对象可以被释放，但是这个内存只能由同一个 fixalloc 池重用，所以它只能被重用于同一类型的对象。

一般来说，使用其中任何一个分配的类型应标记为 //go:notinheap （见下文）。

在非托管内存中分配对象不得包含堆指针，除非遵循下列原则：

  1. 任何来自非托管内存的指向堆的指针必须为垃圾回收的 root。具体而言，所有指针必须要么能够被一个全局变量访问到，要么能够在 runtime.markroot 中添加为显式垃圾回收的 root。
  2. 如果内存被重用，那么堆指针必须进行在他们作为 GC root 可见前进行零初始化。否则，GC 可能会回收已经过时的堆指针。请参考「零初始化与归零」

零初始化 v.s. 归零

运行时有两种类型的归零方式，具体取决于内存是否已经初始化为类型安全状态。

如果内存不是类型安全的状态，那么它可能包含「垃圾」，因为它刚刚被分配且被初始化以供第一次使用，因此它必须使用 memclrNoHeapPointers 或非指针写进行零初始化。这不会执行 write barrier。

如果内存已经处于类型安全状态，并且只设置为零值，则必须使用常规写，通过 typedmemclr 或 memclrHasPointers 完成。这会执行 write barrier。

运行时独占的编译标志

除了 "go doc compile" 文档中说明的 "//go:" 标志外，编译器还未运行时支持了额外的标志。

go:systemstack

go:systemstack 表示函数必须在系统堆栈上运行。由特殊的函数序言（function prologue，指汇编程序函数开头的几行代码，通常是寄存器准备）进行动态检查。

go:nowritebarrier

如果函数包含 write barrier，则 go:nowritebarrier 触发一个编译器错误（它不会抑制 write barrier 的产生，只是一个断言）。

你通常希望 go:nowritebarrierrec。go:nowritebarrier 主要适用于没有 write barrier 会更好的情况，但没有要求正确性。

go:nowritebarrierrec 和 go:yeswritebarrierrec

如果声明的函数或任何它递归调用的函数甚至于 go:yeswritebarrierrec 包含 write barrier，则 go:nowritebarrierrec 触发编译器错误。

逻辑上，编译器为每个函数调用补充 go:nowritebarrierrec 且当遭遇包含 write barrier 函数的时候产生一个错误。这种补充在 go:yeswritebarrierrec 函数上停止。

go:nowritebarrierrec 用于防止 write barrier 实现中的无限循环。

两个标志都在调度器中使用。write barrier 需要一个活跃的 P （getg().m.p != nil）且调度器代码通常在没有活跃 P 的情况下运行。在这种情况下，go:nowritebarrierrec 用于释放 P 的函数上，或者可以在没有 P 的情况下运行。而且go:nowritebarrierrec 还被用于当代码重新要求一个活跃的 P 时。由于这些都是函数级标注，因此释放或获取 P 的代码可能需要分为两个函数。

这两个指令都在调度程序中使用。 write barrier 需要一个活跃的P（ getg().mp != nil）并且调度程序代码通常在没有活动 P 的情况下运行。在这种情况下，go:nowritebarrierrec 用于释放P的函数或者可以在没有P的情况下运行并且去 ：当代码重新获取活动P时使用 go:yeswritebarrierrec。由于这些是功能级注释，因此释放或获取P的代码可能需要分为两个函数。

go:notinheap

go:notinheap 适用于类型声明。它表明一种不能从 GC 堆中分配的类型。具体来说，指向此类型必须让 runtime.inheap 检查失败。类型可能是用于全局变量，堆栈变量或用于对象非托管内存（例如使用 sysAlloc 分配、persistentalloc、fixalloc 或手动管理的范围）。特别的：

  1. new(T), make([]T), append([]T, ...) 以及 T 的隐式堆分配是不允许的（尽管运行时中无论如何都是不允许隐式分配的）。

  2. 指向常规类型（ unsafe.Pointer 除外）的指针不能转换为指向 go:notinheap 类型，即使他们有相同的基础类型。

  3. 任何包含 go:notinheap 类型的类型本身也是 go:notinheap 的。结构和数组中如果元素是 go:notinheap 的则自生也是。go:notinheap 类型的 map 和 channel 是不允许的。为使所有事情都变得显式，任何隐式 go:notinheap 类型的声明必须显式的声明 go:notinheap。

  4. 指向 go:notinheap 类型的指针上的 write barrier 可以省略。

最后一点是 go:notinheap 真正的好处。运行时会使用它作为低级别内部结构使用来在内存分配器和调度器中避免非法或简单低效的内存屏障。这种机制相当安全且没有牺牲运行时代码的可读性。

许可

本文译者系 changkun，译文许可：

© 2018-2020 The golang.design Initiative Authors. Licensed under CC-BY-NC-ND 4.0.

Documentation

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. Package runtime 包含与 Go 的运行时系统交互的操作， 比如控制 goroutines 的功能。 它还包括低级类型信息 reflect 包使用； 请参阅 reflect 可编程的文档运行时类型系统的接口。

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: 

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.

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.  Setting cgocheck=2 enables
expensive checks that should not miss any errors, but will
cause your program to run slower.

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.
Currently, it is:
	gc # @#s #%: #+#+# ms clock, #+#/#/#+# ms cpu, #->#-># MB, # MB goal, # 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
	# MB goal   goal heap size
	# P         number of processors used
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.

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.

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.

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.

scavenge: scavenge=1 enables debugging mode of heap scavenger.

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, # KiB total, #% util
where the fields are as follows:
	scav #       the scavenge cycle number
	# KiB work   the amount of memory returned to the OS since the last line
	# KiB total  the total amount of memory returned to the OS
	#% util      the fraction of all unscavenged 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.

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, net/http, and crypto/tls 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 https://golang.org/doc/articles/race_detector.html 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. 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

Constants

View Source 
const Compiler = "gc"

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.
View Source 
const GOARCH string = sys.GOARCH

GOARCH is the running program's architecture target: one of 386, amd64, arm, s390x, and so on. GOARCH 是正在运行的程序的架构目标： 386，amd64，arm，s390x 之一，等等。

View Source 
const GOOS string = sys.GOOS

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". GOOS 是正在运行的程序的操作系统目标： darwin，freebsd，linux 等之一。 查看所有 GOOS 和 GOARCH 的组合，请运行 "go tool dist list"

Variables

View Source 
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). MemProfileRate 控制在内存配置文件中记录和报告的内存分配比例。 分析器旨在为每个分配的 MemProfileRate 字节平均分配一个分配。 要在配置文件中包含每个已分配的块，请将 MemProfileRate 设置为1。 要完全关闭分析，请将 MemProfileRate 设置为 0。 处理内存配置文件的工具假设配置文件速率在程序的整个生命周期内保持不变，并且等于当前值。 更改内存分析速率的程序应该尽可能早地执行一次程序（例如，在 main 的开头）。

Functions

func BlockProfile 

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 

func Breakpoint()

Breakpoint executes a breakpoint trap.

func CPUProfile deprecated 

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 

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. Caller 在调用 goroutine 的堆栈上报告有关函数调用的文件和行号信息。 参数 skip 是要提升的堆栈帧数，0 表示调用者的调用者。 （由于历史原因，Caller 和 Callers 之间 skip 的含义不同。）返回值报告相应调用文件中的程序计数器， 文件名和行号。如果无法恢复信息，则布尔值 ok 为 false。

func Callers 

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. Callers 使用调用 goroutine 栈上的函数调用的返回程序计数器数组 pc。 参数 skip 是在 pc 中记录之前要跳过的堆栈帧数，0 表示 Callers 本身的帧，1 表示 Callers 的调用者。 它返回写入 pc 的条目数。

要将这些PC转换为符号信息（如函数名称和行号），请使用 CallersFrames。 CallersFrames 考虑内联函数并将返回程序计数器调整为调用程序计数器。 不鼓励迭代返回的 PC 片，就像在任何返回的 PC 上使用 FuncForPC 一样， 因为这些不能解释内联或返回程序计数器调整。

func GC 

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 

func GOMAXPROCS(n int) int

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. GOMAXPROCS 设置能够同时执行线程的最大 CPU 数，并返回原先的设定。 如果 n < 1，则他不会进行任何修改。 机器上的逻辑 CPU 的个数可以从 NumCPU 调用上获取。 该调用会在调度器进行改进后被移除。

func GOROOT 

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. GOROOT 返回 Go 树的根。 它使用了 GOROOT 环境变量，如果在进程启动时设置，或者在Go构建期间使用的根。

func Goexit 

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. Goexit 终止调用它的 goroutine。 没有其他 goroutine 受到影响。 Goexit 在终止 goroutine 之前运行所有延迟调用。 因为 Goexit 不是 panic，那些 defer 函数中的任何恢复调用都将返回 nil。 从主 goroutine 调用 Goexit 终止了 goroutine 没有 func main 返回。 由于 func main 还没有返回， 该程序继续执行其他 goroutines。 如果所有其他 goroutine 退出，程序崩溃。

func GoroutineProfile 

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 

func Gosched()

Gosched 会让出当前的 P，并允许其他 goroutine 运行。它不会推迟当前的 goroutine，因此执行会被自动恢复

func KeepAlive 

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: 

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. KeepAlive 将其参数标记为当前可达。 这保证了对象在调用 KeepAlive 之前不会被释放，且它的 finalizer 不会运行，

一个非常简单的例子展示了什么情况下需要 KeepAlive： 

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[:])
// 确保 Read 返回前 p 不会被 finalize
runtime.KeepAlive(p)
// 在此之后不再使用 p

若没有调用 KeepAlive，则 finalizer 会在 syscall.Read 之前运行，在 syscall.Read 之前关闭文件描述符

func LockOSThread 

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.

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.

func MemProfile 

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 

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 

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. NumCPU 返回用于并发处理的逻辑 CPU 的数量

有效的 CPU 集合是在启动阶段从操作系统查询得来。启动后的系统 CPU 分配不会表现出来。

func NumCgoCall 

func NumCgoCall() int64

NumCgoCall returns the number of cgo calls made by the current process. NumCgoCall 返回了当前进程产生的 cgo 调用的数量

func NumGoroutine 

func NumGoroutine() int

NumGoroutine returns the number of goroutines that currently exist. NumGoroutine 返回当前存在的 goroutine 的数量

func ReadMemStats 

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. ReadMemStats 使用内存分配器统计信息填充 m。

返回的内存分配器统计信息是最新的调用 ReadMemStats。这与堆配置文件形成对比， 这是最近完成的垃圾的快照收集周期。

func ReadTrace 

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 

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 

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 

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: 

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

func SetFinalizer 

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

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, 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 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 

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

func Stack 

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 

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 

func StopTrace()

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

func ThreadCreateProfile 

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 

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 

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". Version 返回 Go 树的版本字符串。 它是构建时的提交散列和日期，或者，在可能的情况下，发布标签如 "go1.3"。

Types

type BlockProfileRecord 

type BlockProfileRecord struct {
	Count  int64
	Cycles int64
	StackRecord
}

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

type Error 

type Error interface {
	error

	// 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.
	RuntimeError()
}

The Error interface identifies a run time error.

type Frame 

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.
	PC uintptr

	// 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().
	Function string

	// 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.
	File string
	Line int

	// Entry point program counter for the function; may be zero
	// if not known. If Func is not nil then Entry ==
	// Func.Entry().
	Entry uintptr
	// contains filtered or unexported fields
}

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

type Frames 

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

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

func CallersFrames 

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 

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 

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

A Func represents a Go function in the running binary.

func FuncForPC 

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 innermost function, but with an entry of the outermost function.

func (*Func) Entry 

func (f *Func) Entry() uintptr

Entry returns the entry address of the function.

func (*Func) FileLine 

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 

func (f *Func) Name() string

Name returns the name of the function.

type MemProfileRecord 

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

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

func (*MemProfileRecord) InUseBytes 

func (r *MemProfileRecord) InUseBytes() int64

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

func (*MemProfileRecord) InUseObjects 

func (r *MemProfileRecord) InUseObjects() int64

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

func (*MemProfileRecord) Stack 

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

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

type MemStats 

type MemStats struct {

	// Alloc is bytes of allocated heap objects.
	//
	// This is the same as HeapAlloc (see below).
	Alloc uint64

	// 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.
	TotalAlloc uint64

	// 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.
	Sys uint64

	// Lookups is the number of pointer lookups performed by the
	// runtime.
	//
	// This is primarily useful for debugging runtime internals.
	Lookups uint64

	// Mallocs is the cumulative count of heap objects allocated.
	// The number of live objects is Mallocs - Frees.
	Mallocs uint64

	// Frees is the cumulative count of heap objects freed.
	Frees uint64

	// 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).
	HeapAlloc uint64

	// 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.
	HeapSys uint64

	// 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.
	HeapIdle uint64

	// 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.
	HeapInuse uint64

	// 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.
	HeapReleased uint64

	// 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.
	HeapObjects uint64

	// 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).
	StackInuse uint64

	// 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 (which should be minimal).
	StackSys uint64

	// MSpanInuse is bytes of allocated mspan structures.
	MSpanInuse uint64

	// MSpanSys is bytes of memory obtained from the OS for mspan
	// structures.
	MSpanSys uint64

	// MCacheInuse is bytes of allocated mcache structures.
	MCacheInuse uint64

	// MCacheSys is bytes of memory obtained from the OS for
	// mcache structures.
	MCacheSys uint64

	// BuckHashSys is bytes of memory in profiling bucket hash tables.
	BuckHashSys uint64

	// GCSys is bytes of memory in garbage collection metadata.
	GCSys uint64

	// OtherSys is bytes of memory in miscellaneous off-heap
	// runtime allocations.
	OtherSys uint64

	// 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.
	NextGC uint64

	// LastGC is the time the last garbage collection finished, as
	// nanoseconds since 1970 (the UNIX epoch).
	LastGC uint64

	// 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.
	PauseTotalNs uint64

	// 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.
	NumGC uint32

	// NumForcedGC is the number of GC cycles that were forced by
	// the application calling the GC function.
	NumForcedGC uint32

	// 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.
	GCCPUFraction float64

	// EnableGC indicates that GC is enabled. It is always true,
	// even if GOGC=off.
	EnableGC bool

	// DebugGC is currently unused.
	DebugGC bool

	// 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.
		Size uint32

		// 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.
		Mallocs uint64

		// Frees is the cumulative count of heap objects freed
		// in this size class.
		Frees uint64
	}
}

A MemStats records statistics about the memory allocator.

type StackRecord 

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

A StackRecord describes a single execution stack.

func (*StackRecord) Stack 

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

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

type TypeAssertionError 

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

A TypeAssertionError explains a failed type assertion.

func (*TypeAssertionError) Error 

func (e *TypeAssertionError) Error() string

func (*TypeAssertionError) RuntimeError 

func (*TypeAssertionError) RuntimeError()

Source Files

View all Source files

Directories

Path Synopsis
Package cgo contains runtime support for code generated by the cgo tool.
 Package cgo contains runtime support for code generated by the cgo tool.
Package debug contains facilities for programs to debug themselves while they are running.
 Package debug contains facilities for programs to debug themselves while they are running.
internal
atomic
math
sys
package sys contains system- and configuration- and architecture-specific constants used by the runtime.
 package sys contains system- and configuration- and architecture-specific constants used by the runtime.
Package metrics provides a stable interface to access implementation-defined metrics exported by the Go runtime.
 Package metrics provides a stable interface to access implementation-defined metrics exported by the Go runtime.
Package race implements data race detection logic.
 Package race implements data race detection logic.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.