...
Run Format

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	// A negative percentage disables garbage collection.
    91	func SetGCPercent(percent int) int {
    92		old := setGCPercent(int32(percent))
    93		runtime.GC()
    94		return int(old)
    95	}
    96	
    97	// FreeOSMemory forces a garbage collection followed by an
    98	// attempt to return as much memory to the operating system
    99	// as possible. (Even if this is not called, the runtime gradually
   100	// returns memory to the operating system in a background task.)
   101	func FreeOSMemory() {
   102		freeOSMemory()
   103	}
   104	
   105	// SetMaxStack sets the maximum amount of memory that
   106	// can be used by a single goroutine stack.
   107	// If any goroutine exceeds this limit while growing its stack,
   108	// the program crashes.
   109	// SetMaxStack returns the previous setting.
   110	// The initial setting is 1 GB on 64-bit systems, 250 MB on 32-bit systems.
   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.
   115	func 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.
   133	func 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	// SetPanicOnFault applies only to the current goroutine.
   145	// It returns the previous setting.
   146	func SetPanicOnFault(enabled bool) bool {
   147		return setPanicOnFault(enabled)
   148	}
   149	
   150	// WriteHeapDump writes a description of the heap and the objects in
   151	// it to the given file descriptor.
   152	//
   153	// WriteHeapDump suspends the execution of all goroutines until the heap
   154	// dump is completely written.  Thus, the file descriptor must not be
   155	// connected to a pipe or socket whose other end is in the same Go
   156	// process; instead, use a temporary file or network socket.
   157	//
   158	// The heap dump format is defined at https://golang.org/s/go15heapdump.
   159	func WriteHeapDump(fd uintptr)
   160	
   161	// SetTraceback sets the amount of detail printed by the runtime in
   162	// the traceback it prints before exiting due to an unrecovered panic
   163	// or an internal runtime error.
   164	// The level argument takes the same values as the GOTRACEBACK
   165	// environment variable. For example, SetTraceback("all") ensure
   166	// that the program prints all goroutines when it crashes.
   167	// See the package runtime documentation for details.
   168	// If SetTraceback is called with a level lower than that of the
   169	// environment variable, the call is ignored.
   170	func SetTraceback(level string)
   171	

View as plain text