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 // A negative percentage disables garbage collection.
91 func SetGCPercent(percent
int) int {
92 return int(setGCPercent(int32(percent
)))
95 // FreeOSMemory forces a garbage collection followed by an
96 // attempt to return as much memory to the operating system
97 // as possible. (Even if this is not called, the runtime gradually
98 // returns memory to the operating system in a background task.)
103 // SetMaxStack sets the maximum amount of memory that
104 // can be used by a single goroutine stack.
105 // If any goroutine exceeds this limit while growing its stack,
106 // the program crashes.
107 // SetMaxStack returns the previous setting.
108 // The initial setting is 1 GB on 64-bit systems, 250 MB on 32-bit systems.
110 // SetMaxStack is useful mainly for limiting the damage done by
111 // goroutines that enter an infinite recursion. It only limits future
113 func SetMaxStack(bytes
int) int {
114 return setMaxStack(bytes
)
117 // SetMaxThreads sets the maximum number of operating system
118 // threads that the Go program can use. If it attempts to use more than
119 // this many, the program crashes.
120 // SetMaxThreads returns the previous setting.
121 // The initial setting is 10,000 threads.
123 // The limit controls the number of operating system threads, not the number
124 // of goroutines. A Go program creates a new thread only when a goroutine
125 // is ready to run but all the existing threads are blocked in system calls, cgo calls,
126 // or are locked to other goroutines due to use of runtime.LockOSThread.
128 // SetMaxThreads is useful mainly for limiting the damage done by
129 // programs that create an unbounded number of threads. The idea is
130 // to take down the program before it takes down the operating system.
131 func SetMaxThreads(threads
int) int {
132 return setMaxThreads(threads
)
135 // SetPanicOnFault controls the runtime's behavior when a program faults
136 // at an unexpected (non-nil) address. Such faults are typically caused by
137 // bugs such as runtime memory corruption, so the default response is to crash
138 // the program. Programs working with memory-mapped files or unsafe
139 // manipulation of memory may cause faults at non-nil addresses in less
140 // dramatic situations; SetPanicOnFault allows such programs to request
141 // that the runtime trigger only a panic, not a crash.
142 // SetPanicOnFault applies only to the current goroutine.
143 // It returns the previous setting.
144 func SetPanicOnFault(enabled
bool) bool {
145 return setPanicOnFault(enabled
)
148 // WriteHeapDump writes a description of the heap and the objects in
149 // it to the given file descriptor.
151 // WriteHeapDump suspends the execution of all goroutines until the heap
152 // dump is completely written. Thus, the file descriptor must not be
153 // connected to a pipe or socket whose other end is in the same Go
154 // process; instead, use a temporary file or network socket.
156 // The heap dump format is defined at https://golang.org/s/go15heapdump.
157 func WriteHeapDump(fd
uintptr)
159 // SetTraceback sets the amount of detail printed by the runtime in
160 // the traceback it prints before exiting due to an unrecovered panic
161 // or an internal runtime error.
162 // The level argument takes the same values as the GOTRACEBACK
163 // environment variable. For example, SetTraceback("all") ensure
164 // that the program prints all goroutines when it crashes.
165 // See the package runtime documentation for details.
166 // If SetTraceback is called with a level lower than that of the
167 // environment variable, the call is ignored.
168 func SetTraceback(level
string)