package runtime · Go 標準庫中文參考

# package runtime `import "runtime"` runtime包提供和go運行時環境的互操作，如控制go程的函數。它也包括用于reflect包的低層次類型信息；參見reflect報的文檔獲取運行時類型系統的可編程接口。 ### Environment Variables 下面的環境變量（$name或%name%，這依賴于主機的操作系統）控制go程序的運行時行為。它們的含義和用法可能在各發行版之間改變。環境變量GOGC設置最初的垃圾收集目標百分比。當新申請的數據和前次垃圾收集剩下的存活數據的比率達到該百分比時，就會觸發垃圾收集。默認GOGC=100。設置GOGC=off?會完全關閉垃圾收集。runtime/debug包的SetGCPercent函數允許在運行時修改該百分比。參見[http://golang.org/pkg/runtime/debug/#SetGCPercent](http://golang.org/pkg/runtime/debug/#SetGCPercent) 環境變量GODEBUG控制運行時的debug輸出。GODEBUG的值是逗號分隔的name=val對。支持的name如下： ``` allocfreetrace: 設置其為1，會導致每次分配都會被記錄剖面，會記錄每一個對象的分配、釋放及其堆棧蹤跡。 efence: 設置其為1，會導致分配器運行模式為：每個對象申請在獨立的頁和地址，且永不循環利用。 gctrace: 設置其為1，會導致垃圾收集器每次收集都向標準錯誤輸出寫入單行的數據，概述收集的總內存的大小和暫停的總時間長度。設置其為2，會寫入同樣的概述，但也會寫入每次收集的兩個數據。 gcdead: 設置其為1，會導致垃圾收集器摧毀任何它認為已經死掉的執行堆棧。 schedtrace: 設置其為X，會導致調度程序每隔X毫秒輸出單行信息到標準錯誤輸出，概述調度狀態。 scheddetail: 設置schedtrace為X并設置其為1，會導致調度程序每隔X毫秒輸出詳細的多行信息，描述調度、進程、線程和go程的狀態。 ``` 環境變量GOMAXPROCS限制可以同時運行用戶層次的go代碼的操作系統進程數。沒有對代表go代碼的、可以在系統調用中阻塞的go程數的限制；那些阻塞的go程不與GOMAXPROCS限制沖突。本包的GOMAXPROCS函數可以查詢和修改該限制。環境變量GOTRACEBACK控制當go程序因為不能恢復的panic或不期望的運行時情況失敗時的輸出。失敗的程序默認會打印所有現存go程的堆棧蹤跡（省略運行時系統中的函數），然后以狀態碼2退出。如果GOTRACEBACK為0，會完全忽略所有go程的堆棧蹤跡。如果GOTRACEBACK為1，會采用默認行為。如果GOTRACEBACK為2，會打印所有現存go程包括運行時函數的堆棧蹤跡。如果GOTRACEBACK為crash，會打印所有現存go程包括運行時函數的堆棧蹤跡，并且如果可能會采用操作系統特定的方式崩潰，而不是退出。例如，在Unix系統里，程序會釋放SIGABRT信號以觸發核心信息轉儲。環境變量GOARCH、GOOS、GOPATH和GOROOT構成完整的go環境變量集合。它們影響go程序的構建（參見[http://golang.org/cmd/go](http://golang.org/cmd/go)?and[http://golang.org/pkg/go/build](http://golang.org/pkg/go/build)）。 GOARCH、GOOS和GOROOT在編譯時被記錄并可用本包的常量和函數獲取，但它們不會影響運行時環境。 ## Index * [Constants](#pkg-constants) * [Variables](#pkg-variables) * [type Error](#Error) * [type TypeAssertionError](#TypeAssertionError) * [func (e \*TypeAssertionError) Error() string](#TypeAssertionError.Error) * [func (\*TypeAssertionError) RuntimeError()](#TypeAssertionError.RuntimeError) * [func GOROOT() string](#GOROOT) * [func Version() string](#Version) * [func NumCPU() int](#NumCPU) * [func GOMAXPROCS(n int) int](#GOMAXPROCS) * [func GC()](#GC) * [func SetFinalizer(x, f interface{})](#SetFinalizer) * [type MemStats](#MemStats) * [func ReadMemStats(m \*MemStats)](#ReadMemStats) * [type MemProfileRecord](#MemProfileRecord) * [func (r \*MemProfileRecord) InUseBytes() int64](#MemProfileRecord.InUseBytes) * [func (r \*MemProfileRecord) InUseObjects() int64](#MemProfileRecord.InUseObjects) * [func (r \*MemProfileRecord) Stack() []uintptr](#MemProfileRecord.Stack) * [func MemProfile(p []MemProfileRecord, inuseZero bool) (n int, ok bool)](#MemProfile) * [func SetCPUProfileRate(hz int)](#SetCPUProfileRate) * [func CPUProfile() []byte](#CPUProfile) * [func Breakpoint()](#Breakpoint) * [func Stack(buf []byte, all bool) int](#Stack) * [func Caller(skip int) (pc uintptr, file string, line int, ok bool)](#Caller) * [func Callers(skip int, pc []uintptr) int](#Callers) * [type StackRecord](#StackRecord) * [func (r \*StackRecord) Stack() []uintptr](#StackRecord.Stack) * [type Func](#Func) * [func FuncForPC(pc uintptr) \*Func](#FuncForPC) * [func (f \*Func) Entry() uintptr](#Func.Entry) * [func (f \*Func) FileLine(pc uintptr) (file string, line int)](#Func.FileLine) * [func (f \*Func) Name() string](#Func.Name) * [func NumCgoCall() int64](#NumCgoCall) * [func NumGoroutine() int](#NumGoroutine) * [func Goexit()](#Goexit) * [func Gosched()](#Gosched) * [func GoroutineProfile(p []StackRecord) (n int, ok bool)](#GoroutineProfile) * [func LockOSThread()](#LockOSThread) * [func UnlockOSThread()](#UnlockOSThread) * [func ThreadCreateProfile(p []StackRecord) (n int, ok bool)](#ThreadCreateProfile) * [type BlockProfileRecord](#BlockProfileRecord) * [func SetBlockProfileRate(rate int)](#SetBlockProfileRate) * [func BlockProfile(p []BlockProfileRecord) (n int, ok bool)](#BlockProfile) ## Constants ``` const Compiler = "gc" ``` Compiler是編譯工具鏈的名字，工具鏈會構建可執行的二進制文件。已知的工具鏈是： ``` gc The 5g/6g/8g compiler suite at code.google.com/p/go. gccgo The gccgo front end, part of the GCC compiler suite. ``` ``` const GOARCH string = theGoarch ``` GOARCH是可執行程序的目標處理器架構（將要在該架構的機器上執行）：386、amd64或arm。 ``` const GOOS string = theGoos ``` GOOS是可執行程序的目標操作系統（將要在該操作系統的機器上執行）：darwin、freebsd、linux等。 ## Variables ``` var MemProfileRate int = 512 * 1024 ``` MemProfileRate控制會在內存profile里記錄和報告的內存分配采樣頻率。內存profile記錄器平均每分配MemProfileRate字節進行一次分配采樣。要在profile里包含每一個申請的塊，可以將MemProfileRate設為1。要完全關閉profile的記錄，設置本變量為0。處理內存profile的工具假設profile記錄速度在整個程序的生命期是固定的，并等于當前值。修改內存profile的程序應該只進行一次，且盡可能早的修改（例如，在main函數的開始處）。 ## type [Error](https://github.com/golang/go/blob/master/src/runtime/error.go#L8 "View Source") ``` type Error interface { error // RuntimeError是一個無操作的函數，僅用于區別運行時錯誤和普通錯誤。 // 具有RuntimeError方法的錯誤類型就是運行時錯誤類型。 RuntimeError() } ``` Error接口用來識別運行時錯誤。 ## type [TypeAssertionError](https://github.com/golang/go/blob/master/src/runtime/error.go#L19 "View Source") ``` type TypeAssertionError struct { // 內含隱藏或非導出字段 } ``` TypeAssertionError表示一次失敗的類型斷言。 ### func (\*TypeAssertionError) [Error](https://github.com/golang/go/blob/master/src/runtime/error.go#L28 "View Source") ``` func (e *TypeAssertionError) Error() string ``` ### func (\*TypeAssertionError) [RuntimeError](https://github.com/golang/go/blob/master/src/runtime/error.go#L26 "View Source") ``` func (*TypeAssertionError) RuntimeError() ``` ## func [GOROOT](https://github.com/golang/go/blob/master/src/runtime/extern.go#L184 "View Source") ``` func GOROOT() string ``` GOROOT返回Go的根目錄。如果存在GOROOT環境變量，返回該變量的值；否則，返回創建Go時的根目錄。 ## func [Version](https://github.com/golang/go/blob/master/src/runtime/extern.go#L195 "View Source") ``` func Version() string ``` 返回Go的版本字符串。它要么是遞交的hash和創建時的日期；要么是發行標簽如"go1.3"。 ## func [NumCPU](https://github.com/golang/go/blob/master/src/runtime/debug.go#L27 "View Source") ``` func NumCPU() int ``` NumCPU返回本地機器的邏輯CPU個數。 ## func [GOMAXPROCS](https://github.com/golang/go/blob/master/src/runtime/debug.go#L24 "View Source") ``` func GOMAXPROCS(n int) int ``` GOMAXPROCS設置可同時執行的最大CPU數，并返回先前的設置。?若?n < 1，它就不會更改當前設置。本地機器的邏輯CPU數可通過?NumCPU?查詢。本函數在調度程序優化后會去掉。 ## func [SetCPUProfileRate](https://github.com/golang/go/blob/master/src/runtime/debug.go#L141 "View Source") ``` func SetCPUProfileRate(hz int) ``` SetCPUProfileRate設置CPU profile記錄的速率為平均每秒hz次。如果hz<=0，SetCPUProfileRate會關閉profile的記錄。如果記錄器在執行，該速率必須在關閉之后才能修改。絕大多數使用者應使用runtime/pprof包或testing包的-test.cpuprofile選項而非直接使用SetCPUProfileRate。 ## func [CPUProfile](https://github.com/golang/go/blob/master/src/runtime/debug.go#L132 "View Source") ``` func CPUProfile() []byte ``` CPUProfile返回二進制CPU profile堆棧跟蹤數據的下一個chunk，函數會阻塞直到該數據可用。?如果profile的記錄被關閉，且在記錄器開著的時候積累的profile數據都被返回了，CPUProfile會返回nil。調用者在再次調用本函數之前應先保存返回的數據。絕大多數使用者應使用?runtime/pprof包或testing包的-test.cpuprofile選項而非直接使用?CPUProfile。 ## func [GC](https://github.com/golang/go/blob/master/src/runtime/mem.go#L75 "View Source") ``` func GC() ``` GC執行一次垃圾回收。 ## func [SetFinalizer](https://github.com/golang/go/blob/master/src/runtime/extern.go#L177 "View Source") ``` func SetFinalizer(x, f interface{}) ``` SetFinalizer將x的終止器設置為f。當垃圾收集器發現一個不能接觸的（即引用計數為零，程序中不能再直接或間接訪問該對象）具有終止器的塊時，它會清理該關聯（對象到終止器）并在獨立go程調用f(x)。這使x再次可以接觸，但沒有了綁定的終止器。如果SetFinalizer沒有被再次調用，下一次垃圾收集器將視x為不可接觸的，并釋放x。 SetFinalizer(x, nil)會清理任何綁定到x的終止器。參數x必須是一個指向通過new申請的對象的指針，或者通過對復合字面值取址得到的指針。參數f必須是一個函數，它接受單個可以直接用x類型值賦值的參數，也可以有任意個被忽略的返回值。如果這兩條任一條不被滿足，本函數就會中斷程序。終止器會按依賴順序執行：如果A指向B，兩者都有終止器，且它們無法從其它方面接觸，只有A的終止器執行；A被釋放后，B的終止器就可以執行。如果一個循環結構包含一個具有終止器的塊，該循環不能保證會被當垃圾收集，終止器也不能保證會執行；因為沒有尊重依賴關系的順序。 x的終止器會在x變為不可接觸之后的任意時間被調度執行。不保證終止器會在程序退出前執行，因此一般終止器只用于在長期運行的程序中釋放關聯到某對象的非內存資源。例如，當一個程序丟棄一個os.File對象時沒有調用其Close方法，該os.File對象可以使用終止器去關閉對應的操作系統文件描述符。但依靠終止器去刷新內存中的I/O緩沖如bufio.Writer是錯誤的，因為緩沖不會在程序退出時被刷新。如果\*x的大小為0字節，不保證終止器會執行。一個程序會有單獨一個go程順序執行所有的終止器。如果一個終止器必須運行較長時間，它應該在內部另開go程執行該任務。 ## type [MemStats](https://github.com/golang/go/blob/master/src/runtime/mem.go#L13 "View Source") ``` type MemStats struct { // 一般統計 Alloc uint64 // 已申請且仍在使用的字節數 TotalAlloc uint64 // 已申請的總字節數（已釋放的部分也算在內） Sys uint64 // 從系統中獲取的字節數（下面XxxSys之和） Lookups uint64 // 指針查找的次數 Mallocs uint64 // 申請內存的次數 Frees uint64 // 釋放內存的次數 // 主分配堆統計 HeapAlloc uint64 // 已申請且仍在使用的字節數 HeapSys uint64 // 從系統中獲取的字節數 HeapIdle uint64 // 閑置span中的字節數 HeapInuse uint64 // 非閑置span中的字節數 HeapReleased uint64 // 釋放到系統的字節數 HeapObjects uint64 // 已分配對象的總個數 // L低層次、大小固定的結構體分配器統計，Inuse為正在使用的字節數，Sys為從系統獲取的字節數 StackInuse uint64 // 引導程序的堆棧 StackSys uint64 MSpanInuse uint64 // mspan結構體 MSpanSys uint64 MCacheInuse uint64 // mcache結構體 MCacheSys uint64 BuckHashSys uint64 // profile桶散列表 GCSys uint64 // GC元數據 OtherSys uint64 // 其他系統申請 // 垃圾收集器統計 NextGC uint64 // 會在HeapAlloc字段到達該值（字節數）時運行下次GC LastGC uint64 // 上次運行的絕對時間（納秒） PauseTotalNs uint64 PauseNs [256]uint64 // 近期GC暫停時間的循環緩沖，最近一次在[(NumGC+255)%256] NumGC uint32 EnableGC bool DebugGC bool // 每次申請的字節數的統計，61是C代碼中的尺寸分級數 BySize [61]struct { Size uint32 Mallocs uint64 Frees uint64 } } ``` MemStats記錄內存申請和分配的統計信息。 ## func [ReadMemStats](https://github.com/golang/go/blob/master/src/runtime/mem.go#L72 "View Source") ``` func ReadMemStats(m *MemStats) ``` ReadMemStats將內存申請和分配的統計信息填寫進m。 ## type [MemProfileRecord](https://github.com/golang/go/blob/master/src/runtime/debug.go#L53 "View Source") ``` type MemProfileRecord struct { AllocBytes, FreeBytes int64 // 申請和釋放的字節數 AllocObjects, FreeObjects int64 // 申請和釋放的對象數 Stack0 [32]uintptr // 該記錄的調用棧蹤跡，以第一個零值成員截止 } ``` MemProfileRecord用于描述某個調用棧序列申請和釋放的活動對象等信息。 ### func (\*MemProfileRecord) [InUseBytes](https://github.com/golang/go/blob/master/src/runtime/debug.go#L60 "View Source") ``` func (r *MemProfileRecord) InUseBytes() int64 ``` InUseBytes返回正在使用的字節數（AllocBytes – FreeBytes） ### func (\*MemProfileRecord) [InUseObjects](https://github.com/golang/go/blob/master/src/runtime/debug.go#L63 "View Source") ``` func (r *MemProfileRecord) InUseObjects() int64 ``` InUseObjects返回正在使用的對象數（AllocObjects - FreeObjects） ### func (\*MemProfileRecord) [Stack](https://github.com/golang/go/blob/master/src/runtime/debug.go#L69 "View Source") ``` func (r *MemProfileRecord) Stack() []uintptr ``` Stack返回關聯至此記錄的調用棧蹤跡，即r.Stack0的前綴。 ## func [MemProfile](https://github.com/golang/go/blob/master/src/runtime/debug.go#L90 "View Source") ``` func MemProfile(p []MemProfileRecord, inuseZero bool) (n int, ok bool) ``` MemProfile返回當前內存profile中的記錄數n。若len(p)>=n，MemProfile會將此分析報告復制到p中并返回(n, true)；如果len(p)<n，MemProfile則不會更改p，而只返回(n, false)。如果inuseZero為真，該profile就會包含無效分配記錄（其中r.AllocBytes>0，而r.AllocBytes==r.FreeBytes。這些內存都是被申請后又釋放回運行時環境的）。大多數調用者應當使用runtime/pprof包或testing包的-test.memprofile標記，而非直接調用MemProfile。 ## func [Breakpoint](https://github.com/golang/go/blob/master/src/runtime/debug.go#L8 "View Source") ``` func Breakpoint() ``` Breakpoint執行一個斷點陷阱。 ## func [Stack](https://github.com/golang/go/blob/master/src/runtime/debug.go#L172 "View Source") ``` func Stack(buf []byte, all bool) int ``` Stack將調用其的go程的調用棧蹤跡格式化后寫入到buf中并返回寫入的字節數。若all為true，函數會在寫入當前go程的蹤跡信息后，將其它所有go程的調用棧蹤跡都格式化寫入到buf中。 ## func [Caller](https://github.com/golang/go/blob/master/src/runtime/extern.go#L95 "View Source") ``` func Caller(skip int) (pc uintptr, file string, line int, ok bool) ``` Caller報告當前go程調用棧所執行的函數的文件和行號信息。實參skip為上溯的棧幀數，0表示Caller的調用者（Caller所在的調用棧）。（由于歷史原因，skip的意思在Caller和Callers中并不相同。）函數的返回值為調用棧標識符、文件名、該調用在文件中的行號。如果無法獲得信息，ok會被設為false。 ## func [Callers](https://github.com/golang/go/blob/master/src/runtime/extern.go#L102 "View Source") ``` func Callers(skip int, pc []uintptr) int ``` 函數把當前go程調用棧上的調用棧標識符填入切片pc中，返回寫入到pc中的項數。實參skip為開始在pc中記錄之前所要跳過的棧幀數，0表示Callers自身的調用棧，1表示Callers所在的調用棧。返回寫入p的項數。 ## type [StackRecord](https://github.com/golang/go/blob/master/src/runtime/debug.go#L93 "View Source") ``` type StackRecord struct { Stack0 [32]uintptr // 該記錄的調用棧蹤跡，以第一個零值成員截止 } ``` StackRecord描述單條調用棧。 ### func (\*StackRecord) [Stack](https://github.com/golang/go/blob/master/src/runtime/debug.go#L99 "View Source") ``` func (r *StackRecord) Stack() []uintptr ``` Stack返回與記錄相關聯的調用棧蹤跡，即r.Stack0的前綴。 ## type [Func](https://github.com/golang/go/blob/master/src/runtime/extern.go#L104 "View Source") ``` type Func struct { // 內含隱藏或非導出字段 } ``` ### func [FuncForPC](https://github.com/golang/go/blob/master/src/runtime/extern.go#L110 "View Source") ``` func FuncForPC(pc uintptr) *Func ``` FuncForPC返回一個表示調用棧標識符pc對應的調用棧的\*Func；如果該調用棧標識符沒有對應的調用棧，函數會返回nil。每一個調用棧必然是對某個函數的調用。 ### func (\*Func) [Name](https://github.com/golang/go/blob/master/src/runtime/extern.go#L113 "View Source") ``` func (f *Func) Name() string ``` Name返回該調用棧所調用的函數的名字。 ### func (\*Func) [FileLine](https://github.com/golang/go/blob/master/src/runtime/extern.go#L126 "View Source") ``` func (f *Func) FileLine(pc uintptr) (file string, line int) ``` FileLine返回該調用棧所調用的函數的源代碼文件名和行號。如果pc不是f內的調用棧標識符，結果是不精確的。 ### func (\*Func) [Entry](https://github.com/golang/go/blob/master/src/runtime/extern.go#L118 "View Source") ``` func (f *Func) Entry() uintptr ``` Entry返回該調用棧的調用棧標識符。 ## func [NumCgoCall](https://github.com/golang/go/blob/master/src/runtime/debug.go#L30 "View Source") ``` func NumCgoCall() int64 ``` NumCgoCall返回當前進程執行的cgo調用次數。 ## func [NumGoroutine](https://github.com/golang/go/blob/master/src/runtime/debug.go#L33 "View Source") ``` func NumGoroutine() int ``` NumGoroutine返回當前存在的Go程數。 ## func [Goexit](https://github.com/golang/go/blob/master/src/runtime/extern.go#L87 "View Source") ``` func Goexit() ``` Goexit終止調用它的go程。其它go程不會受影響。Goexit會在終止該go程前執行所有defer的函數。在程序的main go程調用本函數，會終結該go程，而不會讓main返回。因為main函數沒有返回，程序會繼續執行其它的go程。如果所有其它go程都退出了，程序就會崩潰。 ## func [Gosched](https://github.com/golang/go/blob/master/src/runtime/extern.go#L78 "View Source") ``` func Gosched() ``` Gosched使當前go程放棄處理器，以讓其它go程運行。它不會掛起當前go程，因此當前go程未來會恢復執行。 ## func [GoroutineProfile](https://github.com/golang/go/blob/master/src/runtime/debug.go#L122 "View Source") ``` func GoroutineProfile(p []StackRecord) (n int, ok bool) ``` GoroutineProfile返回活躍go程的堆棧profile中的記錄個數。若len(p) >= n，函數就會將profile中的記錄復制到p中并返回(n, true)。若len(p) < n，則不會修改p，而只返回(n, false)。絕大多數調用者應當使用runtime/pprof包，而非直接調用GoroutineProfile。 ## func [LockOSThread](https://github.com/golang/go/blob/master/src/runtime/debug.go#L13 "View Source") ``` func LockOSThread() ``` 將調用的go程綁定到它當前所在的操作系統線程。除非調用的go程退出或調用UnlockOSThread，否則它將總是在該線程中執行，而其它go程則不能進入該線程。 ## func [UnlockOSThread](https://github.com/golang/go/blob/master/src/runtime/debug.go#L17 "View Source") ``` func UnlockOSThread() ``` 將調用的go程解除和它綁定的操作系統線程。若調用的go程未調用LockOSThread，UnlockOSThread不做操作。 ## func [ThreadCreateProfile](https://github.com/golang/go/blob/master/src/runtime/debug.go#L114 "View Source") ``` func ThreadCreateProfile(p []StackRecord) (n int, ok bool) ``` 返回線程創建profile中的記錄個數。如果len(p)>=n，本函數就會將profile中的記錄復制到p中并返回(n, true)。若len(p)<n，則不會更改p，而只返回(n, false)。絕大多數使用者應當使用runtime/pprof包，而非直接調用ThreadCreateProfile。 ## type [BlockProfileRecord](https://github.com/golang/go/blob/master/src/runtime/debug.go#L153 "View Source") ``` type BlockProfileRecord struct { Count int64 Cycles int64 StackRecord } ``` BlockProfileRecord用于描述某個調用棧序列發生的阻塞事件的信息。 ## func [SetBlockProfileRate](https://github.com/golang/go/blob/master/src/runtime/debug.go#L149 "View Source") ``` func SetBlockProfileRate(rate int) ``` SetBlockProfileRate控制阻塞profile記錄go程阻塞事件的采樣頻率。對于一個阻塞事件，平均每阻塞rate納秒，阻塞profile記錄器就采集一份樣本。要在profile中包括每一個阻塞事件，需傳入rate=1；要完全關閉阻塞profile的記錄，需傳入rate<=0。 ## func [BlockProfile](https://github.com/golang/go/blob/master/src/runtime/debug.go#L166 "View Source") ``` func BlockProfile(p []BlockProfileRecord) (n int, ok bool) ``` BlockProfile返回當前阻塞profile中的記錄個數。如果len(p)>=n，本函數就會將此profile中的記錄復制到p中并返回(n, true)。如果len(p)<n，本函數則不會修改p，而只返回(n, false)。絕大多數使用者應當使用runtime/pprof包或testing包的-test.blockprofile標記，?而非直接調用?BlockProfile。