| // 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. |
| |
| /* |
| 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. |
| |
| 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. |
| |
| 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. |
| |
| 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. |
| |
| 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, 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 |
| runtime.GC() call and all phases are STW. |
| |
| 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 |
| |
| 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. |
| |
| 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. |
| |
| 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 net and net/http packages also refer to debugging variables in GODEBUG. |
| See the documentation for those packages for details. |
| |
| 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 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. |
| |
| 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. |
| */ |
| package runtime |
| |
| import "runtime/internal/sys" |
| |
| // Gosched yields the processor, allowing other goroutines to run. It does not |
| // suspend the current goroutine, so execution resumes automatically. |
| func Gosched() |
| |
| // 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 Caller(skip int) (pc uintptr, file string, line int, ok bool) |
| |
| // 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. |
| func Callers(skip int, pc []uintptr) int |
| |
| // SetFinalizer sets the finalizer associated with obj to the provided |
| // finalizer function. When the garbage collector finds an unreachable block |
| // with an associated finalizer, it clears the association and runs |
| // finalizer(obj) in a separate goroutine. This makes obj reachable again, |
| // but now without an associated finalizer. Assuming that SetFinalizer |
| // is not called again, the next time the garbage collector sees |
| // that obj is unreachable, it will free obj. |
| // |
| // SetFinalizer(obj, nil) clears any finalizer associated with obj. |
| // |
| // The argument obj must be a pointer to an object allocated by |
| // calling new or by taking the address of a composite literal. |
| // The argument finalizer must be a function that takes a single argument |
| // to which obj'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 obj is scheduled to run at some arbitrary time after |
| // obj 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 *obj 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 finalizer may run as soon as an object becomes unreachable. |
| // In order to use finalizers correctly, the program must ensure that |
| // the object is reachable until it is no longer required. |
| // Objects stored in global variables, or that can be found by tracing |
| // pointers from a global variable, are reachable. For other objects, |
| // pass the object to a call of the KeepAlive function to mark the |
| // last point in the function where the object must be reachable. |
| // |
| // For example, if p points to a struct that contains a file descriptor d, |
| // and p has a finalizer that closes that file descriptor, and if the last |
| // use of p in a function is a call to syscall.Write(p.d, buf, size), then |
| // p may be unreachable as soon as the program enters syscall.Write. The |
| // finalizer may run at that moment, closing p.d, causing syscall.Write |
| // to fail because it is writing to a closed file descriptor (or, worse, |
| // to an entirely different file descriptor opened by a different goroutine). |
| // To avoid this problem, call runtime.KeepAlive(p) after the call to |
| // syscall.Write. |
| // |
| // 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 SetFinalizer(obj interface{}, finalizer interface{}) |
| |
| // KeepAlive marks its argument as currently reachable. |
| // This ensures that the object is not freed, and its finalizer is not run, |
| // before the point in the program where KeepAlive is called. |
| // |
| // A very simplified example showing where KeepAlive is required: |
| // type File struct { d int } |
| // d, err := syscall.Open("/file/path", syscall.O_RDONLY, 0) |
| // // ... do something if err != nil ... |
| // p := &File{d} |
| // runtime.SetFinalizer(p, func(p *File) { syscall.Close(p.d) }) |
| // var buf [10]byte |
| // n, err := syscall.Read(p.d, buf[:]) |
| // // Ensure p is not finalized until Read returns. |
| // runtime.KeepAlive(p) |
| // // No more uses of p after this point. |
| // |
| // Without the KeepAlive call, the finalizer could run at the start of |
| // syscall.Read, closing the file descriptor before syscall.Read makes |
| // the actual system call. |
| func KeepAlive(interface{}) |
| |
| // 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 GOROOT() string { |
| s := gogetenv("GOROOT") |
| if s != "" { |
| return s |
| } |
| return sys.DefaultGoroot |
| } |
| |
| // Version returns the Go tree's version string. |
| // It is either the commit hash and date at the time of the build or, |
| // when possible, a release tag like "go1.3". |
| func Version() string { |
| return sys.TheVersion |
| } |
| |
| // GOOS is the running program's operating system target: |
| // one of darwin, freebsd, linux, and so on. |
| const GOOS string = sys.GOOS |
| |
| // GOARCH is the running program's architecture target: |
| // 386, amd64, arm, or s390x. |
| const GOARCH string = sys.GOARCH |
| |
| // GCCGOTOOLDIR is the Tool Dir for the gccgo build |
| const GCCGOTOOLDIR string = sys.GccgoToolDir |