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.
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. 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. gcstackbarrieroff: setting gcstackbarrieroff=1 disables the use of stack barriers that allow the garbage collector to avoid repeating a stack scan during the mark termination phase. gcstackbarrierall: setting gcstackbarrierall=1 installs stack barriers in every stack frame, rather than in exponentially-spaced frames. 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. Setting gctrace=2 emits the same summary but also repeats each collection. 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, scan, synchronize Ps, mark, and STW mark termination. The CPU times for mark 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 and all phases are STW. 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: defaults to invalidptr=1, causing 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. 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.
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 every extant goroutine, eliding functions internal to the run-time system, and then exits with exit code 2. If GOTRACEBACK=0, the per-goroutine stack traces are omitted entirely. If GOTRACEBACK=1, the default behavior is used. If GOTRACEBACK=2, the per-goroutine stack traces include run-time functions. If GOTRACEBACK=crash, the per-goroutine stack traces include run-time functions, and if possible the program crashes in an operating-specific manner instead of exiting. For example, on Unix systems, the program raises SIGABRT to trigger a core dump.
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
- Variables
- func BlockProfile(p []BlockProfileRecord) (n int, ok bool)
- func Breakpoint()
- func CPUProfile() []byte
- func Caller(skip int) (pc uintptr, file string, line int, ok bool)
- func Callers(skip int, pc []uintptr) int
- func GC()
- func GOMAXPROCS(n int) int
- func GOROOT() string
- func Goexit()
- func GoroutineProfile(p []StackRecord) (n int, ok bool)
- func Gosched()
- func LockOSThread()
- func MemProfile(p []MemProfileRecord, inuseZero bool) (n int, ok bool)
- func NumCPU() int
- func NumCgoCall() int64
- func NumGoroutine() int
- func ReadMemStats(m *MemStats)
- func ReadTrace() []byte
- func SetBlockProfileRate(rate int)
- func SetCPUProfileRate(hz int)
- func SetFinalizer(obj interface{}, finalizer interface{})
- func Stack(buf []byte, all bool) int
- func StartTrace() error
- func StopTrace()
- func ThreadCreateProfile(p []StackRecord) (n int, ok bool)
- func UnlockOSThread()
- func Version() string
- type BlockProfileRecord
- type Error
- type Func
- type MemProfileRecord
- type MemStats
- type StackRecord
- type TypeAssertionError
Constants ¶
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.
const GOARCH string = theGoarch
GOARCH is the running program's architecture target: 386, amd64, or arm.
const GOOS string = theGoos
GOOS is the running program's operating system target: one of darwin, freebsd, linux, and so on.
Variables ¶
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).
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 CPUProfile ¶
func CPUProfile() []byte
CPUProfile returns the next chunk of binary CPU profiling stack trace data, blocking until data is available. If profiling is turned off and all the profile data accumulated while it was on has been returned, CPUProfile returns nil. The caller must save the returned data before calling CPUProfile again.
Most clients should use the runtime/pprof package or the testing package's -test.cpuprofile flag instead of calling CPUProfile directly.
func Caller ¶
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 ¶
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.
Note that since each slice entry pc[i] is a return program counter, looking up the file and line for pc[i] (for example, using (*Func).FileLine) will return the file and line number of the instruction immediately following the call. To look up the file and line number of the call itself, use pc[i]-1. As an exception to this rule, if pc[i-1] corresponds to the function runtime.sigpanic, then pc[i] is the program counter of a faulting instruction and should be used without any subtraction.
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 ¶
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 ¶
func GOROOT() string
GOROOT returns the root of the Go tree. It uses the GOROOT environment variable, if set, or else the root used during the Go build.
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 panic, however, 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 ¶
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 yields the processor, allowing other goroutines to run. It does not suspend the current goroutine, so execution resumes automatically.
func LockOSThread ¶
func LockOSThread()
LockOSThread wires the calling goroutine to its current operating system thread. Until the calling goroutine exits or calls UnlockOSThread, it will always execute in that thread, and no other goroutine can.
func MemProfile ¶
func MemProfile(p []MemProfileRecord, inuseZero bool) (n int, ok bool)
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.
Most clients should use the runtime/pprof package or the testing package's -test.memprofile flag instead of calling MemProfile directly.
func NumCPU ¶
func NumCPU() int
NumCPU returns the number of logical CPUs usable by the current process.
func NumCgoCall ¶
func NumCgoCall() int64
NumCgoCall returns the number of cgo calls made by the current process.
func NumGoroutine ¶
func NumGoroutine() int
NumGoroutine returns the number of goroutines that currently exist.
func ReadMemStats ¶
func ReadMemStats(m *MemStats)
ReadMemStats populates m with memory allocator statistics.
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 SetFinalizer ¶
func SetFinalizer(obj interface{}, finalizer interface{})
SetFinalizer sets the finalizer associated with x to f. When the garbage collector finds an unreachable block with an associated finalizer, it clears the association and runs f(x) in a separate goroutine. This makes x reachable again, but now without an associated finalizer. Assuming that SetFinalizer is not called again, the next time the garbage collector sees that x is unreachable, it will free x.
SetFinalizer(x, nil) clears any finalizer associated with x.
The argument x must be a pointer to an object allocated by calling new or by taking the address of a composite literal. The argument f must be a function that takes a single argument to which x's type can be assigned, and can have arbitrary ignored return values. If either of these is not true, SetFinalizer aborts 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 x is scheduled to run at some arbitrary time after x 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 *x 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 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 Stack ¶
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 unwires the calling goroutine from its fixed operating system thread. If the calling goroutine has not called LockOSThread, UnlockOSThread is a no-op.
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 Func ¶
type Func struct {
// contains filtered or unexported fields
}
A Func represents a Go function in the running binary.
func FuncForPC ¶
FuncForPC returns a *Func describing the function that contains the given program counter address, or else nil.
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 {
// General statistics.
Alloc uint64 // bytes allocated and not yet freed
TotalAlloc uint64 // bytes allocated (even if freed)
Sys uint64 // bytes obtained from system (sum of XxxSys below)
Lookups uint64 // number of pointer lookups
Mallocs uint64 // number of mallocs
Frees uint64 // number of frees
// Main allocation heap statistics.
HeapAlloc uint64 // bytes allocated and not yet freed (same as Alloc above)
HeapSys uint64 // bytes obtained from system
HeapIdle uint64 // bytes in idle spans
HeapInuse uint64 // bytes in non-idle span
HeapReleased uint64 // bytes released to the OS
HeapObjects uint64 // total number of allocated objects
// Low-level fixed-size structure allocator statistics.
// Inuse is bytes used now.
// Sys is bytes obtained from system.
StackInuse uint64 // bytes used by stack allocator
StackSys uint64
MSpanInuse uint64 // mspan structures
MSpanSys uint64
MCacheInuse uint64 // mcache structures
MCacheSys uint64
BuckHashSys uint64 // profiling bucket hash table
GCSys uint64 // GC metadata
OtherSys uint64 // other system allocations
// Garbage collector statistics.
NextGC uint64 // next collection will happen when HeapAlloc ≥ this amount
LastGC uint64 // end time of last collection (nanoseconds since 1970)
PauseTotalNs uint64
PauseNs [256]uint64 // circular buffer of recent GC pause durations, most recent at [(NumGC+255)%256]
PauseEnd [256]uint64 // circular buffer of recent GC pause end times
NumGC uint32
GCCPUFraction float64 // fraction of CPU time used by GC
EnableGC bool
DebugGC bool
// Per-size allocation statistics.
// 61 is NumSizeClasses in the C code.
BySize [61]struct {
Size uint32
Mallocs uint64
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
¶
- alg.go
- arch1_amd64.go
- arch_amd64.go
- atomic_amd64x.go
- atomic_pointer.go
- cgo.go
- cgocall.go
- cgocallback.go
- chan.go
- compiler.go
- complex.go
- cpuprof.go
- cputicks.go
- debug.go
- defs_linux_amd64.go
- env_posix.go
- error.go
- extern.go
- hash64.go
- hashmap.go
- hashmap_fast.go
- heapdump.go
- iface.go
- lfstack.go
- lfstack_amd64.go
- lock_futex.go
- malloc.go
- mbarrier.go
- mbitmap.go
- mcache.go
- mcentral.go
- mem_linux.go
- mfinal.go
- mfixalloc.go
- mgc.go
- mgcmark.go
- mgcsweep.go
- mgcwork.go
- mheap.go
- mprof.go
- msize.go
- mstats.go
- netpoll.go
- netpoll_epoll.go
- os1_linux.go
- os2_linux.go
- os_linux.go
- panic.go
- panic1.go
- parfor.go
- print1.go
- print1_write.go
- proc.go
- proc1.go
- race0.go
- rdebug.go
- rune.go
- runtime.go
- runtime1.go
- runtime2.go
- select.go
- sema.go
- signal1_unix.go
- signal_amd64x.go
- signal_linux.go
- signal_linux_amd64.go
- signal_unix.go
- sigpanic_unix.go
- sigqueue.go
- slice.go
- softfloat64.go
- sqrt.go
- stack1.go
- stack2.go
- string.go
- string1.go
- stubs.go
- stubs2.go
- symtab.go
- sys_x86.go
- time.go
- trace.go
- traceback.go
- type.go
- typekind.go
- typekind1.go
- unaligned1.go
- vdso_linux_amd64.go
- wbfat.go
- zgoarch_amd64.go
- zgoos_linux.go
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. |
|
Package pprof writes runtime profiling data in the format expected by the pprof visualization tool.
|
Package pprof writes runtime profiling data in the format expected by the pprof visualization tool. |
|
Package race implements data race detection logic.
|
Package race implements data race detection logic. |
|
Go execution tracer.
|
Go execution tracer. |