1 // Copyright 2009 The Go Authors. All rights reserved. 2 // Use of this source code is governed by a BSD-style 3 // license that can be found in the LICENSE file. 4 5 /* 6 Package runtime contains operations that interact with Go's runtime system, 7 such as functions to control goroutines. It also includes the low-level type information 8 used by the reflect package; see reflect's documentation for the programmable 9 interface to the run-time type system. 10 11 Environment Variables 12 13 The following environment variables ($name or %name%, depending on the host 14 operating system) control the run-time behavior of Go programs. The meanings 15 and use may change from release to release. 16 17 The GOGC variable sets the initial garbage collection target percentage. 18 A collection is triggered when the ratio of freshly allocated data to live data 19 remaining after the previous collection reaches this percentage. The default 20 is GOGC=100. Setting GOGC=off disables the garbage collector entirely. 21 The runtime/debug package's SetGCPercent function allows changing this 22 percentage at run time. See https://golang.org/pkg/runtime/debug/#SetGCPercent. 23 24 The GODEBUG variable controls debugging variables within the runtime. 25 It is a comma-separated list of name=val pairs setting these named variables: 26 27 allocfreetrace: setting allocfreetrace=1 causes every allocation to be 28 profiled and a stack trace printed on each object's allocation and free. 29 30 cgocheck: setting cgocheck=0 disables all checks for packages 31 using cgo to incorrectly pass Go pointers to non-Go code. 32 Setting cgocheck=1 (the default) enables relatively cheap 33 checks that may miss some errors. Setting cgocheck=2 enables 34 expensive checks that should not miss any errors, but will 35 cause your program to run slower. 36 37 efence: setting efence=1 causes the allocator to run in a mode 38 where each object is allocated on a unique page and addresses are 39 never recycled. 40 41 gccheckmark: setting gccheckmark=1 enables verification of the 42 garbage collector's concurrent mark phase by performing a 43 second mark pass while the world is stopped. If the second 44 pass finds a reachable object that was not found by concurrent 45 mark, the garbage collector will panic. 46 47 gcpacertrace: setting gcpacertrace=1 causes the garbage collector to 48 print information about the internal state of the concurrent pacer. 49 50 gcshrinkstackoff: setting gcshrinkstackoff=1 disables moving goroutines 51 onto smaller stacks. In this mode, a goroutine's stack can only grow. 52 53 gcrescanstacks: setting gcrescanstacks=1 enables stack 54 re-scanning during the STW mark termination phase. This is 55 helpful for debugging if objects are being prematurely 56 garbage collected. 57 58 gcstoptheworld: setting gcstoptheworld=1 disables concurrent garbage collection, 59 making every garbage collection a stop-the-world event. Setting gcstoptheworld=2 60 also disables concurrent sweeping after the garbage collection finishes. 61 62 gctrace: setting gctrace=1 causes the garbage collector to emit a single line to standard 63 error at each collection, summarizing the amount of memory collected and the 64 length of the pause. Setting gctrace=2 emits the same summary but also 65 repeats each collection. The format of this line is subject to change. 66 Currently, it is: 67 gc # @#s #%: #+#+# ms clock, #+#/#/#+# ms cpu, #->#-># MB, # MB goal, # P 68 where the fields are as follows: 69 gc # the GC number, incremented at each GC 70 @#s time in seconds since program start 71 #% percentage of time spent in GC since program start 72 #+...+# wall-clock/CPU times for the phases of the GC 73 #->#-># MB heap size at GC start, at GC end, and live heap 74 # MB goal goal heap size 75 # P number of processors used 76 The phases are stop-the-world (STW) sweep termination, concurrent 77 mark and scan, and STW mark termination. The CPU times 78 for mark/scan are broken down in to assist time (GC performed in 79 line with allocation), background GC time, and idle GC time. 80 If the line ends with "(forced)", this GC was forced by a 81 runtime.GC() call. 82 83 Setting gctrace to any value > 0 also causes the garbage collector 84 to emit a summary when memory is released back to the system. 85 This process of returning memory to the system is called scavenging. 86 The format of this summary is subject to change. 87 Currently it is: 88 scvg#: # MB released printed only if non-zero 89 scvg#: inuse: # idle: # sys: # released: # consumed: # (MB) 90 where the fields are as follows: 91 scvg# the scavenge cycle number, incremented at each scavenge 92 inuse: # MB used or partially used spans 93 idle: # MB spans pending scavenging 94 sys: # MB mapped from the system 95 released: # MB released to the system 96 consumed: # MB allocated from the system 97 98 memprofilerate: setting memprofilerate=X will update the value of runtime.MemProfileRate. 99 When set to 0 memory profiling is disabled. Refer to the description of 100 MemProfileRate for the default value. 101 102 invalidptr: defaults to invalidptr=1, causing the garbage collector and stack 103 copier to crash the program if an invalid pointer value (for example, 1) 104 is found in a pointer-typed location. Setting invalidptr=0 disables this check. 105 This should only be used as a temporary workaround to diagnose buggy code. 106 The real fix is to not store integers in pointer-typed locations. 107 108 sbrk: setting sbrk=1 replaces the memory allocator and garbage collector 109 with a trivial allocator that obtains memory from the operating system and 110 never reclaims any memory. 111 112 scavenge: scavenge=1 enables debugging mode of heap scavenger. 113 114 scheddetail: setting schedtrace=X and scheddetail=1 causes the scheduler to emit 115 detailed multiline info every X milliseconds, describing state of the scheduler, 116 processors, threads and goroutines. 117 118 schedtrace: setting schedtrace=X causes the scheduler to emit a single line to standard 119 error every X milliseconds, summarizing the scheduler state. 120 121 The net and net/http packages also refer to debugging variables in GODEBUG. 122 See the documentation for those packages for details. 123 124 The GOMAXPROCS variable limits the number of operating system threads that 125 can execute user-level Go code simultaneously. There is no limit to the number of threads 126 that can be blocked in system calls on behalf of Go code; those do not count against 127 the GOMAXPROCS limit. This package's GOMAXPROCS function queries and changes 128 the limit. 129 130 The GOTRACEBACK variable controls the amount of output generated when a Go 131 program fails due to an unrecovered panic or an unexpected runtime condition. 132 By default, a failure prints a stack trace for the current goroutine, 133 eliding functions internal to the run-time system, and then exits with exit code 2. 134 The failure prints stack traces for all goroutines if there is no current goroutine 135 or the failure is internal to the run-time. 136 GOTRACEBACK=none omits the goroutine stack traces entirely. 137 GOTRACEBACK=single (the default) behaves as described above. 138 GOTRACEBACK=all adds stack traces for all user-created goroutines. 139 GOTRACEBACK=system is like ``all'' but adds stack frames for run-time functions 140 and shows goroutines created internally by the run-time. 141 GOTRACEBACK=crash is like ``system'' but crashes in an operating system-specific 142 manner instead of exiting. For example, on Unix systems, the crash raises 143 SIGABRT to trigger a core dump. 144 For historical reasons, the GOTRACEBACK settings 0, 1, and 2 are synonyms for 145 none, all, and system, respectively. 146 The runtime/debug package's SetTraceback function allows increasing the 147 amount of output at run time, but it cannot reduce the amount below that 148 specified by the environment variable. 149 See https://golang.org/pkg/runtime/debug/#SetTraceback. 150 151 The GOARCH, GOOS, GOPATH, and GOROOT environment variables complete 152 the set of Go environment variables. They influence the building of Go programs 153 (see https://golang.org/cmd/go and https://golang.org/pkg/go/build). 154 GOARCH, GOOS, and GOROOT are recorded at compile time and made available by 155 constants or functions in this package, but they do not influence the execution 156 of the run-time system. 157 */ 158 package runtime 159 160 import "runtime/internal/sys" 161 162 // Caller reports file and line number information about function invocations on 163 // the calling goroutine's stack. The argument skip is the number of stack frames 164 // to ascend, with 0 identifying the caller of Caller. (For historical reasons the 165 // meaning of skip differs between Caller and Callers.) The return values report the 166 // program counter, file name, and line number within the file of the corresponding 167 // call. The boolean ok is false if it was not possible to recover the information. 168 func Caller(skip int) (pc uintptr, file string, line int, ok bool) { 169 // Make room for three PCs: the one we were asked for, 170 // what it called, so that CallersFrames can see if it "called" 171 // sigpanic, and possibly a PC for skipPleaseUseCallersFrames. 172 var rpc [3]uintptr 173 if callers(1+skip-1, rpc[:]) < 2 { 174 return 175 } 176 var stackExpander stackExpander 177 callers := stackExpander.init(rpc[:]) 178 // We asked for one extra, so skip that one. If this is sigpanic, 179 // stepping over this frame will set up state in Frames so the 180 // next frame is correct. 181 callers, _, ok = stackExpander.next(callers, true) 182 if !ok { 183 return 184 } 185 _, frame, _ := stackExpander.next(callers, true) 186 pc = frame.PC 187 file = frame.File 188 line = frame.Line 189 return 190 } 191 192 // Callers fills the slice pc with the return program counters of function invocations 193 // on the calling goroutine's stack. The argument skip is the number of stack frames 194 // to skip before recording in pc, with 0 identifying the frame for Callers itself and 195 // 1 identifying the caller of Callers. 196 // It returns the number of entries written to pc. 197 // 198 // To translate these PCs into symbolic information such as function 199 // names and line numbers, use CallersFrames. CallersFrames accounts 200 // for inlined functions and adjusts the return program counters into 201 // call program counters. Iterating over the returned slice of PCs 202 // directly is discouraged, as is using FuncForPC on any of the 203 // returned PCs, since these cannot account for inlining or return 204 // program counter adjustment. 205 func Callers(skip int, pc []uintptr) int { 206 // runtime.callers uses pc.array==nil as a signal 207 // to print a stack trace. Pick off 0-length pc here 208 // so that we don't let a nil pc slice get to it. 209 if len(pc) == 0 { 210 return 0 211 } 212 return callers(skip, pc) 213 } 214 215 // GOROOT returns the root of the Go tree. It uses the 216 // GOROOT environment variable, if set at process start, 217 // or else the root used during the Go build. 218 func GOROOT() string { 219 s := gogetenv("GOROOT") 220 if s != "" { 221 return s 222 } 223 return sys.DefaultGoroot 224 } 225 226 // Version returns the Go tree's version string. 227 // It is either the commit hash and date at the time of the build or, 228 // when possible, a release tag like "go1.3". 229 func Version() string { 230 return sys.TheVersion 231 } 232 233 // GOOS is the running program's operating system target: 234 // one of darwin, freebsd, linux, and so on. 235 const GOOS string = sys.GOOS 236 237 // GOARCH is the running program's architecture target: 238 // one of 386, amd64, arm, s390x, and so on. 239 const GOARCH string = sys.GOARCH 240
