2012-03-27 23:13:14 +00:00
|
|
|
// Copyright 2009 The Go Authors. All rights reserved.
|
|
|
|
// Use of this source code is governed by a BSD-style
|
|
|
|
// license that can be found in the LICENSE file.
|
|
|
|
|
|
|
|
/*
|
2014-09-21 17:33:12 +00:00
|
|
|
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
|
2017-04-10 11:32:00 +00:00
|
|
|
percentage at run time. See https://golang.org/pkg/runtime/debug/#SetGCPercent.
|
2014-09-21 17:33:12 +00:00
|
|
|
|
2017-04-10 11:32:00 +00:00
|
|
|
The GODEBUG variable controls debugging variables within the runtime.
|
|
|
|
It is a comma-separated list of name=val pairs setting these named variables:
|
2014-09-21 17:33:12 +00:00
|
|
|
|
2015-08-28 15:33:40 +00:00
|
|
|
allocfreetrace: setting allocfreetrace=1 causes every allocation to be
|
|
|
|
profiled and a stack trace printed on each object's allocation and free.
|
|
|
|
|
2017-04-10 11:32:00 +00:00
|
|
|
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.
|
|
|
|
|
2015-08-28 15:33:40 +00:00
|
|
|
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.
|
|
|
|
|
2017-04-10 11:32:00 +00:00
|
|
|
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.
|
|
|
|
|
2017-10-07 00:16:47 +00:00
|
|
|
gcrescanstacks: setting gcrescanstacks=1 enables stack
|
|
|
|
re-scanning during the STW mark termination phase. This is
|
|
|
|
helpful for debugging if objects are being prematurely
|
|
|
|
garbage collected.
|
|
|
|
|
2017-04-10 11:32:00 +00:00
|
|
|
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.
|
|
|
|
|
2014-09-21 17:33:12 +00:00
|
|
|
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
|
2017-04-10 11:32:00 +00:00
|
|
|
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, 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
|
2018-12-28 15:30:48 +00:00
|
|
|
runtime.GC() call.
|
2017-04-10 11:32:00 +00:00
|
|
|
|
2017-10-07 00:16:47 +00:00
|
|
|
Setting gctrace to any value > 0 also causes the garbage collector
|
|
|
|
to emit a summary when memory is released back to the system.
|
|
|
|
This process of returning memory to the system is called scavenging.
|
|
|
|
The format of this summary is subject to change.
|
|
|
|
Currently it is:
|
|
|
|
scvg#: # MB released printed only if non-zero
|
|
|
|
scvg#: inuse: # idle: # sys: # released: # consumed: # (MB)
|
|
|
|
where the fields are as follows:
|
|
|
|
scvg# the scavenge cycle number, incremented at each scavenge
|
|
|
|
inuse: # MB used or partially used spans
|
|
|
|
idle: # MB spans pending scavenging
|
|
|
|
sys: # MB mapped from the system
|
|
|
|
released: # MB released to the system
|
|
|
|
consumed: # MB allocated from the system
|
|
|
|
|
2017-04-10 11:32:00 +00:00
|
|
|
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.
|
2015-08-28 15:33:40 +00:00
|
|
|
|
|
|
|
memprofilerate: setting memprofilerate=X changes the setting for
|
|
|
|
runtime.MemProfileRate. Refer to the description of this variable for how
|
|
|
|
it is used and its default value.
|
2014-09-21 17:33:12 +00:00
|
|
|
|
2017-04-10 11:32:00 +00:00
|
|
|
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.
|
|
|
|
|
2014-09-21 17:33:12 +00:00
|
|
|
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.
|
|
|
|
|
2015-08-28 15:33:40 +00:00
|
|
|
schedtrace: setting schedtrace=X causes the scheduler to emit a single line to standard
|
|
|
|
error every X milliseconds, summarizing the scheduler state.
|
|
|
|
|
2017-04-10 11:32:00 +00:00
|
|
|
The net and net/http packages also refer to debugging variables in GODEBUG.
|
|
|
|
See the documentation for those packages for details.
|
|
|
|
|
2014-09-21 17:33:12 +00:00
|
|
|
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.
|
2017-04-10 11:32:00 +00:00
|
|
|
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.
|
2014-09-21 17:33:12 +00:00
|
|
|
|
|
|
|
The GOARCH, GOOS, GOPATH, and GOROOT environment variables complete
|
|
|
|
the set of Go environment variables. They influence the building of Go programs
|
2017-04-10 11:32:00 +00:00
|
|
|
(see https://golang.org/cmd/go and https://golang.org/pkg/go/build).
|
2014-09-21 17:33:12 +00:00
|
|
|
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.
|
2012-03-27 23:13:14 +00:00
|
|
|
*/
|
|
|
|
package runtime
|
|
|
|
|
2017-10-07 00:16:47 +00:00
|
|
|
import "runtime/internal/sys"
|
|
|
|
|
2012-03-27 23:13:14 +00:00
|
|
|
// Caller reports file and line number information about function invocations on
|
2017-10-07 00:16:47 +00:00
|
|
|
// the calling goroutine's stack. The argument skip is the number of stack frames
|
2014-09-21 17:33:12 +00:00
|
|
|
// 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
|
2012-03-27 23:13:14 +00:00
|
|
|
// program counter, file name, and line number within the file of the corresponding
|
2018-12-28 15:30:48 +00:00
|
|
|
// call. The boolean ok is false if it was not possible to recover the information.
|
2012-03-27 23:13:14 +00:00
|
|
|
func Caller(skip int) (pc uintptr, file string, line int, ok bool)
|
|
|
|
|
2017-10-07 00:16:47 +00:00
|
|
|
// 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
|
2014-09-21 17:33:12 +00:00
|
|
|
// to skip before recording in pc, with 0 identifying the frame for Callers itself and
|
|
|
|
// 1 identifying the caller of Callers.
|
2012-03-27 23:13:14 +00:00
|
|
|
// It returns the number of entries written to pc.
|
|
|
|
//
|
2018-12-28 15:30:48 +00:00
|
|
|
// To translate these PCs into symbolic information such as function
|
|
|
|
// names and line numbers, use CallersFrames. CallersFrames accounts
|
|
|
|
// for inlined functions and adjusts the return program counters into
|
|
|
|
// call program counters. Iterating over the returned slice of PCs
|
|
|
|
// directly is discouraged, as is using FuncForPC on any of the
|
|
|
|
// returned PCs, since these cannot account for inlining or return
|
|
|
|
// program counter adjustment.
|
|
|
|
func Callers(skip int, pc []uintptr) int
|
2012-03-27 23:13:14 +00:00
|
|
|
|
2018-12-28 15:30:48 +00:00
|
|
|
// GOROOT returns the root of the Go tree. It uses the
|
|
|
|
// GOROOT environment variable, if set at process start,
|
2012-03-27 23:13:14 +00:00
|
|
|
// or else the root used during the Go build.
|
|
|
|
func GOROOT() string {
|
2017-10-07 00:16:47 +00:00
|
|
|
s := gogetenv("GOROOT")
|
2012-03-27 23:13:14 +00:00
|
|
|
if s != "" {
|
|
|
|
return s
|
|
|
|
}
|
2017-10-07 00:16:47 +00:00
|
|
|
return sys.DefaultGoroot
|
2012-03-27 23:13:14 +00:00
|
|
|
}
|
|
|
|
|
|
|
|
// Version returns the Go tree's version string.
|
2015-08-28 15:33:40 +00:00
|
|
|
// It is either the commit hash and date at the time of the build or,
|
|
|
|
// when possible, a release tag like "go1.3".
|
2012-03-27 23:13:14 +00:00
|
|
|
func Version() string {
|
2017-10-07 00:16:47 +00:00
|
|
|
return sys.TheVersion
|
2012-03-27 23:13:14 +00:00
|
|
|
}
|
|
|
|
|
|
|
|
// GOOS is the running program's operating system target:
|
|
|
|
// one of darwin, freebsd, linux, and so on.
|
2017-10-07 00:16:47 +00:00
|
|
|
const GOOS string = sys.GOOS
|
2012-03-27 23:13:14 +00:00
|
|
|
|
|
|
|
// GOARCH is the running program's architecture target:
|
2018-12-28 15:30:48 +00:00
|
|
|
// one of 386, amd64, arm, s390x, and so on.
|
2017-10-07 00:16:47 +00:00
|
|
|
const GOARCH string = sys.GOARCH
|
2015-08-28 15:33:40 +00:00
|
|
|
|
|
|
|
// GCCGOTOOLDIR is the Tool Dir for the gccgo build
|
2017-10-07 00:16:47 +00:00
|
|
|
const GCCGOTOOLDIR string = sys.GccgoToolDir
|