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.
4
5package debug
6
7import (
8	"runtime"
9	"sort"
10	"time"
11)
12
13// GCStats collect information about recent garbage collections.
14type GCStats struct {
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
21}
22
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.
31func 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)
40	}
41
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
47	// any conversion.
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]
55
56	if cap(stats.PauseEnd) < maxPause {
57		stats.PauseEnd = make([]time.Time, 0, maxPause)
58	}
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)))
62	}
63
64	if len(stats.PauseQuantiles) > 0 {
65		if n == 0 {
66			for i := range stats.PauseQuantiles {
67				stats.PauseQuantiles[i] = 0
68			}
69		} else {
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]
78			}
79			stats.PauseQuantiles[nq] = sorted[len(sorted)-1]
80		}
81	}
82}
83
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.
91func SetGCPercent(percent int) int {
92	return int(setGCPercent(int32(percent)))
93}
94
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.)
99func FreeOSMemory() {
100	freeOSMemory()
101}
102
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.
109// There may be a system-imposed maximum stack limit regardless
110// of the value provided to SetMaxStack.
111//
112// SetMaxStack is useful mainly for limiting the damage done by
113// goroutines that enter an infinite recursion. It only limits future
114// stack growth.
115func SetMaxStack(bytes int) int {
116	return setMaxStack(bytes)
117}
118
119// SetMaxThreads sets the maximum number of operating system
120// threads that the Go program can use. If it attempts to use more than
121// this many, the program crashes.
122// SetMaxThreads returns the previous setting.
123// The initial setting is 10,000 threads.
124//
125// The limit controls the number of operating system threads, not the number
126// of goroutines. A Go program creates a new thread only when a goroutine
127// is ready to run but all the existing threads are blocked in system calls, cgo calls,
128// or are locked to other goroutines due to use of runtime.LockOSThread.
129//
130// SetMaxThreads is useful mainly for limiting the damage done by
131// programs that create an unbounded number of threads. The idea is
132// to take down the program before it takes down the operating system.
133func SetMaxThreads(threads int) int {
134	return setMaxThreads(threads)
135}
136
137// SetPanicOnFault controls the runtime's behavior when a program faults
138// at an unexpected (non-nil) address. Such faults are typically caused by
139// bugs such as runtime memory corruption, so the default response is to crash
140// the program. Programs working with memory-mapped files or unsafe
141// manipulation of memory may cause faults at non-nil addresses in less
142// dramatic situations; SetPanicOnFault allows such programs to request
143// that the runtime trigger only a panic, not a crash.
144// The runtime.Error that the runtime panics with may have an additional method:
145//     Addr() uintptr
146// If that method exists, it returns the memory address which triggered the fault.
147// The results of Addr are best-effort and the veracity of the result
148// may depend on the platform.
149// SetPanicOnFault applies only to the current goroutine.
150// It returns the previous setting.
151func SetPanicOnFault(enabled bool) bool {
152	return setPanicOnFault(enabled)
153}
154
155// WriteHeapDump writes a description of the heap and the objects in
156// it to the given file descriptor.
157//
158// WriteHeapDump suspends the execution of all goroutines until the heap
159// dump is completely written.  Thus, the file descriptor must not be
160// connected to a pipe or socket whose other end is in the same Go
161// process; instead, use a temporary file or network socket.
162//
163// The heap dump format is defined at https://golang.org/s/go15heapdump.
164func WriteHeapDump(fd uintptr)
165
166// SetTraceback sets the amount of detail printed by the runtime in
167// the traceback it prints before exiting due to an unrecovered panic
168// or an internal runtime error.
169// The level argument takes the same values as the GOTRACEBACK
170// environment variable. For example, SetTraceback("all") ensure
171// that the program prints all goroutines when it crashes.
172// See the package runtime documentation for details.
173// If SetTraceback is called with a level lower than that of the
174// environment variable, the call is ignored.
175func SetTraceback(level string)
176