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 efence: setting efence=1 causes the allocator to run in a mode 31 where each object is allocated on a unique page and addresses are 32 never recycled. 33 34 gccheckmark: setting gccheckmark=1 enables verification of the 35 garbage collector's concurrent mark phase by performing a 36 second mark pass while the world is stopped. If the second 37 pass finds a reachable object that was not found by concurrent 38 mark, the garbage collector will panic. 39 40 gcpacertrace: setting gcpacertrace=1 causes the garbage collector to 41 print information about the internal state of the concurrent pacer. 42 43 gcshrinkstackoff: setting gcshrinkstackoff=1 disables moving goroutines 44 onto smaller stacks. In this mode, a goroutine's stack can only grow. 45 46 gcstackbarrieroff: setting gcstackbarrieroff=1 disables the use of stack barriers 47 that allow the garbage collector to avoid repeating a stack scan during the 48 mark termination phase. 49 50 gcstackbarrierall: setting gcstackbarrierall=1 installs stack barriers 51 in every stack frame, rather than in exponentially-spaced frames. 52 53 gcstoptheworld: setting gcstoptheworld=1 disables concurrent garbage collection, 54 making every garbage collection a stop-the-world event. Setting gcstoptheworld=2 55 also disables concurrent sweeping after the garbage collection finishes. 56 57 gctrace: setting gctrace=1 causes the garbage collector to emit a single line to standard 58 error at each collection, summarizing the amount of memory collected and the 59 length of the pause. Setting gctrace=2 emits the same summary but also 60 repeats each collection. The format of this line is subject to change. 61 Currently, it is: 62 gc # @#s #%: #+...+# ms clock, #+...+# ms cpu, #->#-># MB, # MB goal, # P 63 where the fields are as follows: 64 gc # the GC number, incremented at each GC 65 @#s time in seconds since program start 66 #% percentage of time spent in GC since program start 67 #+...+# wall-clock/CPU times for the phases of the GC 68 #->#-># MB heap size at GC start, at GC end, and live heap 69 # MB goal goal heap size 70 # P number of processors used 71 The phases are stop-the-world (STW) sweep termination, scan, 72 synchronize Ps, mark, and STW mark termination. The CPU times 73 for mark are broken down in to assist time (GC performed in 74 line with allocation), background GC time, and idle GC time. 75 If the line ends with "(forced)", this GC was forced by a 76 runtime.GC() call and all phases are STW. 77 78 memprofilerate: setting memprofilerate=X will update the value of runtime.MemProfileRate. 79 When set to 0 memory profiling is disabled. Refer to the description of 80 MemProfileRate for the default value. 81 82 invalidptr: defaults to invalidptr=1, causing the garbage collector and stack 83 copier to crash the program if an invalid pointer value (for example, 1) 84 is found in a pointer-typed location. Setting invalidptr=0 disables this check. 85 This should only be used as a temporary workaround to diagnose buggy code. 86 The real fix is to not store integers in pointer-typed locations. 87 88 sbrk: setting sbrk=1 replaces the memory allocator and garbage collector 89 with a trivial allocator that obtains memory from the operating system and 90 never reclaims any memory. 91 92 scavenge: scavenge=1 enables debugging mode of heap scavenger. 93 94 scheddetail: setting schedtrace=X and scheddetail=1 causes the scheduler to emit 95 detailed multiline info every X milliseconds, describing state of the scheduler, 96 processors, threads and goroutines. 97 98 schedtrace: setting schedtrace=X causes the scheduler to emit a single line to standard 99 error every X milliseconds, summarizing the scheduler state. 100 101 The GOMAXPROCS variable limits the number of operating system threads that 102 can execute user-level Go code simultaneously. There is no limit to the number of threads 103 that can be blocked in system calls on behalf of Go code; those do not count against 104 the GOMAXPROCS limit. This package's GOMAXPROCS function queries and changes 105 the limit. 106 107 The GOTRACEBACK variable controls the amount of output generated when a Go 108 program fails due to an unrecovered panic or an unexpected runtime condition. 109 By default, a failure prints a stack trace for every extant goroutine, eliding functions 110 internal to the run-time system, and then exits with exit code 2. 111 If GOTRACEBACK=0, the per-goroutine stack traces are omitted entirely. 112 If GOTRACEBACK=1, the default behavior is used. 113 If GOTRACEBACK=2, the per-goroutine stack traces include run-time functions. 114 If GOTRACEBACK=crash, the per-goroutine stack traces include run-time functions, 115 and if possible the program crashes in an operating-specific manner instead of 116 exiting. For example, on Unix systems, the program raises SIGABRT to trigger a 117 core dump. 118 119 The GOARCH, GOOS, GOPATH, and GOROOT environment variables complete 120 the set of Go environment variables. They influence the building of Go programs 121 (see https://golang.org/cmd/go and https://golang.org/pkg/go/build). 122 GOARCH, GOOS, and GOROOT are recorded at compile time and made available by 123 constants or functions in this package, but they do not influence the execution 124 of the run-time system. 125 */ 126 package runtime 127 128 // Caller reports file and line number information about function invocations on 129 // the calling goroutine's stack. The argument skip is the number of stack frames 130 // to ascend, with 0 identifying the caller of Caller. (For historical reasons the 131 // meaning of skip differs between Caller and Callers.) The return values report the 132 // program counter, file name, and line number within the file of the corresponding 133 // call. The boolean ok is false if it was not possible to recover the information. 134 func Caller(skip int) (pc uintptr, file string, line int, ok bool) { 135 // Ask for two PCs: the one we were asked for 136 // and what it called, so that we can see if it 137 // "called" sigpanic. 138 var rpc [2]uintptr 139 if callers(1+skip-1, rpc[:]) < 2 { 140 return 141 } 142 f := findfunc(rpc[1]) 143 if f == nil { 144 // TODO(rsc): Probably a bug? 145 // The C version said "have retpc at least" 146 // but actually returned pc=0. 147 ok = true 148 return 149 } 150 pc = rpc[1] 151 xpc := pc 152 g := findfunc(rpc[0]) 153 // All architectures turn faults into apparent calls to sigpanic. 154 // If we see a call to sigpanic, we do not back up the PC to find 155 // the line number of the call instruction, because there is no call. 156 if xpc > f.entry && (g == nil || g.entry != funcPC(sigpanic)) { 157 xpc-- 158 } 159 file, line32 := funcline(f, xpc) 160 line = int(line32) 161 ok = true 162 return 163 } 164 165 // Callers fills the slice pc with the return program counters of function invocations 166 // on the calling goroutine's stack. The argument skip is the number of stack frames 167 // to skip before recording in pc, with 0 identifying the frame for Callers itself and 168 // 1 identifying the caller of Callers. 169 // It returns the number of entries written to pc. 170 // 171 // Note that since each slice entry pc[i] is a return program counter, 172 // looking up the file and line for pc[i] (for example, using (*Func).FileLine) 173 // will return the file and line number of the instruction immediately 174 // following the call. 175 // To look up the file and line number of the call itself, use pc[i]-1. 176 // As an exception to this rule, if pc[i-1] corresponds to the function 177 // runtime.sigpanic, then pc[i] is the program counter of a faulting 178 // instruction and should be used without any subtraction. 179 func Callers(skip int, pc []uintptr) int { 180 // runtime.callers uses pc.array==nil as a signal 181 // to print a stack trace. Pick off 0-length pc here 182 // so that we don't let a nil pc slice get to it. 183 if len(pc) == 0 { 184 return 0 185 } 186 return callers(skip, pc) 187 } 188 189 // GOROOT returns the root of the Go tree. 190 // It uses the GOROOT environment variable, if set, 191 // or else the root used during the Go build. 192 func GOROOT() string { 193 s := gogetenv("GOROOT") 194 if s != "" { 195 return s 196 } 197 return defaultGoroot 198 } 199 200 // Version returns the Go tree's version string. 201 // It is either the commit hash and date at the time of the build or, 202 // when possible, a release tag like "go1.3". 203 func Version() string { 204 return theVersion 205 } 206 207 // GOOS is the running program's operating system target: 208 // one of darwin, freebsd, linux, and so on. 209 const GOOS string = theGoos 210 211 // GOARCH is the running program's architecture target: 212 // 386, amd64, or arm. 213 const GOARCH string = theGoarch 214
