1 // Copyright 2013 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.
13 // GCStats collect information about recent garbage collections.
15 LastGC time.Time // time of last collection
16 NumGC int64 // number of garbage collections
17 PauseTotal time.Duration // total pause for all collections
18 Pause []time.Duration // pause history, most recent first
19 PauseEnd []time.Time // pause end times history, most recent first
20 PauseQuantiles []time.Duration
23 // ReadGCStats reads statistics about garbage collection into stats.
24 // The number of entries in the pause history is system-dependent;
25 // stats.Pause slice will be reused if large enough, reallocated otherwise.
26 // ReadGCStats may use the full capacity of the stats.Pause slice.
27 // If stats.PauseQuantiles is non-empty, ReadGCStats fills it with quantiles
28 // summarizing the distribution of pause time. For example, if
29 // len(stats.PauseQuantiles) is 5, it will be filled with the minimum,
30 // 25%, 50%, 75%, and maximum pause times.
31 func ReadGCStats(stats *GCStats) {
32 // Create a buffer with space for at least two copies of the
33 // pause history tracked by the runtime. One will be returned
34 // to the caller and the other will be used as transfer buffer
35 // for end times history and as a temporary buffer for
36 // computing quantiles.
37 const maxPause = len(((*runtime.MemStats)(nil)).PauseNs)
38 if cap(stats.Pause) < 2*maxPause+3 {
39 stats.Pause = make([]time.Duration, 2*maxPause+3)
42 // readGCStats fills in the pause and end times histories (up to
43 // maxPause entries) and then three more: Unix ns time of last GC,
44 // number of GC, and total pause time in nanoseconds. Here we
45 // depend on the fact that time.Duration's native unit is
46 // nanoseconds, so the pauses and the total pause time do not need
48 readGCStats(&stats.Pause)
49 n := len(stats.Pause) - 3
50 stats.LastGC = time.Unix(0, int64(stats.Pause[n]))
51 stats.NumGC = int64(stats.Pause[n+1])
52 stats.PauseTotal = stats.Pause[n+2]
53 n /= 2 // buffer holds pauses and end times
54 stats.Pause = stats.Pause[:n]
56 if cap(stats.PauseEnd) < maxPause {
57 stats.PauseEnd = make([]time.Time, 0, maxPause)
59 stats.PauseEnd = stats.PauseEnd[:0]
60 for _, ns := range stats.Pause[n : n+n] {
61 stats.PauseEnd = append(stats.PauseEnd, time.Unix(0, int64(ns)))
64 if len(stats.PauseQuantiles) > 0 {
66 for i := range stats.PauseQuantiles {
67 stats.PauseQuantiles[i] = 0
70 // There's room for a second copy of the data in stats.Pause.
71 // See the allocation at the top of the function.
72 sorted := stats.Pause[n : n+n]
73 copy(sorted, stats.Pause)
74 sort.Slice(sorted, func(i, j int) bool { return sorted[i] < sorted[j] })
75 nq := len(stats.PauseQuantiles) - 1
76 for i := 0; i < nq; i++ {
77 stats.PauseQuantiles[i] = sorted[len(sorted)*i/nq]
79 stats.PauseQuantiles[nq] = sorted[len(sorted)-1]
84 // SetGCPercent sets the garbage collection target percentage:
85 // a collection is triggered when the ratio of freshly allocated data
86 // to live data remaining after the previous collection reaches this percentage.
87 // SetGCPercent returns the previous setting.
88 // The initial setting is the value of the GOGC environment variable
89 // at startup, or 100 if the variable is not set.
90 // This setting may be effectively reduced in order to maintain a memory
92 // A negative percentage effectively disables garbage collection, unless
93 // the memory limit is reached.
94 // See SetMemoryLimit for more details.
95 func SetGCPercent(percent int) int {
96 return int(setGCPercent(int32(percent)))
99 // FreeOSMemory forces a garbage collection followed by an
100 // attempt to return as much memory to the operating system
101 // as possible. (Even if this is not called, the runtime gradually
102 // returns memory to the operating system in a background task.)
103 func FreeOSMemory() {
107 // SetMaxStack sets the maximum amount of memory that
108 // can be used by a single goroutine stack.
109 // If any goroutine exceeds this limit while growing its stack,
110 // the program crashes.
111 // SetMaxStack returns the previous setting.
112 // The initial setting is 1 GB on 64-bit systems, 250 MB on 32-bit systems.
113 // There may be a system-imposed maximum stack limit regardless
114 // of the value provided to SetMaxStack.
116 // SetMaxStack is useful mainly for limiting the damage done by
117 // goroutines that enter an infinite recursion. It only limits future
119 func SetMaxStack(bytes int) int {
120 return setMaxStack(bytes)
123 // SetMaxThreads sets the maximum number of operating system
124 // threads that the Go program can use. If it attempts to use more than
125 // this many, the program crashes.
126 // SetMaxThreads returns the previous setting.
127 // The initial setting is 10,000 threads.
129 // The limit controls the number of operating system threads, not the number
130 // of goroutines. A Go program creates a new thread only when a goroutine
131 // is ready to run but all the existing threads are blocked in system calls, cgo calls,
132 // or are locked to other goroutines due to use of runtime.LockOSThread.
134 // SetMaxThreads is useful mainly for limiting the damage done by
135 // programs that create an unbounded number of threads. The idea is
136 // to take down the program before it takes down the operating system.
137 func SetMaxThreads(threads int) int {
138 return setMaxThreads(threads)
141 // SetPanicOnFault controls the runtime's behavior when a program faults
142 // at an unexpected (non-nil) address. Such faults are typically caused by
143 // bugs such as runtime memory corruption, so the default response is to crash
144 // the program. Programs working with memory-mapped files or unsafe
145 // manipulation of memory may cause faults at non-nil addresses in less
146 // dramatic situations; SetPanicOnFault allows such programs to request
147 // that the runtime trigger only a panic, not a crash.
148 // The runtime.Error that the runtime panics with may have an additional method:
152 // If that method exists, it returns the memory address which triggered the fault.
153 // The results of Addr are best-effort and the veracity of the result
154 // may depend on the platform.
155 // SetPanicOnFault applies only to the current goroutine.
156 // It returns the previous setting.
157 func SetPanicOnFault(enabled bool) bool {
158 return setPanicOnFault(enabled)
161 // WriteHeapDump writes a description of the heap and the objects in
162 // it to the given file descriptor.
164 // WriteHeapDump suspends the execution of all goroutines until the heap
165 // dump is completely written. Thus, the file descriptor must not be
166 // connected to a pipe or socket whose other end is in the same Go
167 // process; instead, use a temporary file or network socket.
169 // The heap dump format is defined at https://golang.org/s/go15heapdump.
170 func WriteHeapDump(fd uintptr)
172 // SetTraceback sets the amount of detail printed by the runtime in
173 // the traceback it prints before exiting due to an unrecovered panic
174 // or an internal runtime error.
175 // The level argument takes the same values as the GOTRACEBACK
176 // environment variable. For example, SetTraceback("all") ensure
177 // that the program prints all goroutines when it crashes.
178 // See the package runtime documentation for details.
179 // If SetTraceback is called with a level lower than that of the
180 // environment variable, the call is ignored.
181 func SetTraceback(level string)
183 // SetMemoryLimit provides the runtime with a soft memory limit.
185 // The runtime undertakes several processes to try to respect this
186 // memory limit, including adjustments to the frequency of garbage
187 // collections and returning memory to the underlying system more
188 // aggressively. This limit will be respected even if GOGC=off (or,
189 // if SetGCPercent(-1) is executed).
191 // The input limit is provided as bytes, and includes all memory
192 // mapped, managed, and not released by the Go runtime. Notably, it
193 // does not account for space used by the Go binary and memory
194 // external to Go, such as memory managed by the underlying system
195 // on behalf of the process, or memory managed by non-Go code inside
196 // the same process. Examples of excluded memory sources include: OS
197 // kernel memory held on behalf of the process, memory allocated by
198 // C code, and memory mapped by syscall.Mmap (because it is not
199 // managed by the Go runtime).
201 // More specifically, the following expression accurately reflects
202 // the value the runtime attempts to maintain as the limit:
204 // runtime.MemStats.Sys - runtime.MemStats.HeapReleased
206 // or in terms of the runtime/metrics package:
208 // /memory/classes/total:bytes - /memory/classes/heap/released:bytes
210 // A zero limit or a limit that's lower than the amount of memory
211 // used by the Go runtime may cause the garbage collector to run
212 // nearly continuously. However, the application may still make
215 // The memory limit is always respected by the Go runtime, so to
216 // effectively disable this behavior, set the limit very high.
217 // math.MaxInt64 is the canonical value for disabling the limit,
218 // but values much greater than the available memory on the underlying
219 // system work just as well.
221 // See https://go.dev/doc/gc-guide for a detailed guide explaining
222 // the soft memory limit in more detail, as well as a variety of common
223 // use-cases and scenarios.
225 // The initial setting is math.MaxInt64 unless the GOMEMLIMIT
226 // environment variable is set, in which case it provides the initial
227 // setting. GOMEMLIMIT is a numeric value in bytes with an optional
228 // unit suffix. The supported suffixes include B, KiB, MiB, GiB, and
229 // TiB. These suffixes represent quantities of bytes as defined by
230 // the IEC 80000-13 standard. That is, they are based on powers of
231 // two: KiB means 2^10 bytes, MiB means 2^20 bytes, and so on.
233 // SetMemoryLimit returns the previously set memory limit.
234 // A negative input does not adjust the limit, and allows for
235 // retrieval of the currently set memory limit.
236 func SetMemoryLimit(limit int64) int64 {
237 return setMemoryLimit(limit)