Source file src/runtime/debug/garbage.go

     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  
     5  package debug
     6  
     7  import (
     8  	"runtime"
     9  	"sort"
    10  	"time"
    11  )
    12  
    13  // GCStats collect information about recent garbage collections.
    14  type 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.
    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)
    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  // This setting may be effectively reduced in order to maintain a memory
    91  // limit.
    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)))
    97  }
    98  
    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() {
   104  	freeOSMemory()
   105  }
   106  
   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.
   115  //
   116  // SetMaxStack is useful mainly for limiting the damage done by
   117  // goroutines that enter an infinite recursion. It only limits future
   118  // stack growth.
   119  func SetMaxStack(bytes int) int {
   120  	return setMaxStack(bytes)
   121  }
   122  
   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.
   128  //
   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.
   133  //
   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)
   139  }
   140  
   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:
   149  //
   150  //	Addr() uintptr
   151  //
   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)
   159  }
   160  
   161  // WriteHeapDump writes a description of the heap and the objects in
   162  // it to the given file descriptor.
   163  //
   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.
   168  //
   169  // The heap dump format is defined at https://golang.org/s/go15heapdump.
   170  func WriteHeapDump(fd uintptr)
   171  
   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)
   182  
   183  // SetMemoryLimit provides the runtime with a soft memory limit.
   184  //
   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).
   190  //
   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).
   200  //
   201  // More specifically, the following expression accurately reflects
   202  // the value the runtime attempts to maintain as the limit:
   203  //
   204  //	runtime.MemStats.Sys - runtime.MemStats.HeapReleased
   205  //
   206  // or in terms of the runtime/metrics package:
   207  //
   208  //	/memory/classes/total:bytes - /memory/classes/heap/released:bytes
   209  //
   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
   213  // progress.
   214  //
   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.
   220  //
   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.
   224  //
   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.
   232  //
   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)
   238  }
   239  

View as plain text