github.com/razvanm/vanadium-go-1.3@v0.0.0-20160721203343-4a65068e5915/src/runtime/debug/garbage.go (about)

     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  	PauseQuantiles []time.Duration
    20  }
    21  
    22  // ReadGCStats reads statistics about garbage collection into stats.
    23  // The number of entries in the pause history is system-dependent;
    24  // stats.Pause slice will be reused if large enough, reallocated otherwise.
    25  // ReadGCStats may use the full capacity of the stats.Pause slice.
    26  // If stats.PauseQuantiles is non-empty, ReadGCStats fills it with quantiles
    27  // summarizing the distribution of pause time. For example, if
    28  // len(stats.PauseQuantiles) is 5, it will be filled with the minimum,
    29  // 25%, 50%, 75%, and maximum pause times.
    30  func ReadGCStats(stats *GCStats) {
    31  	// Create a buffer with space for at least two copies of the
    32  	// pause history tracked by the runtime. One will be returned
    33  	// to the caller and the other will be used as a temporary buffer
    34  	// for computing quantiles.
    35  	const maxPause = len(((*runtime.MemStats)(nil)).PauseNs)
    36  	if cap(stats.Pause) < 2*maxPause {
    37  		stats.Pause = make([]time.Duration, 2*maxPause)
    38  	}
    39  
    40  	// readGCStats fills in the pause history (up to maxPause entries)
    41  	// and then three more: Unix ns time of last GC, number of GC,
    42  	// and total pause time in nanoseconds. Here we depend on the
    43  	// fact that time.Duration's native unit is nanoseconds, so the
    44  	// pauses and the total pause time do not need any conversion.
    45  	readGCStats(&stats.Pause)
    46  	n := len(stats.Pause) - 3
    47  	stats.LastGC = time.Unix(0, int64(stats.Pause[n]))
    48  	stats.NumGC = int64(stats.Pause[n+1])
    49  	stats.PauseTotal = stats.Pause[n+2]
    50  	stats.Pause = stats.Pause[:n]
    51  
    52  	if len(stats.PauseQuantiles) > 0 {
    53  		if n == 0 {
    54  			for i := range stats.PauseQuantiles {
    55  				stats.PauseQuantiles[i] = 0
    56  			}
    57  		} else {
    58  			// There's room for a second copy of the data in stats.Pause.
    59  			// See the allocation at the top of the function.
    60  			sorted := stats.Pause[n : n+n]
    61  			copy(sorted, stats.Pause)
    62  			sort.Sort(byDuration(sorted))
    63  			nq := len(stats.PauseQuantiles) - 1
    64  			for i := 0; i < nq; i++ {
    65  				stats.PauseQuantiles[i] = sorted[len(sorted)*i/nq]
    66  			}
    67  			stats.PauseQuantiles[nq] = sorted[len(sorted)-1]
    68  		}
    69  	}
    70  }
    71  
    72  type byDuration []time.Duration
    73  
    74  func (x byDuration) Len() int           { return len(x) }
    75  func (x byDuration) Swap(i, j int)      { x[i], x[j] = x[j], x[i] }
    76  func (x byDuration) Less(i, j int) bool { return x[i] < x[j] }
    77  
    78  // SetGCPercent sets the garbage collection target percentage:
    79  // a collection is triggered when the ratio of freshly allocated data
    80  // to live data remaining after the previous collection reaches this percentage.
    81  // SetGCPercent returns the previous setting.
    82  // The initial setting is the value of the GOGC environment variable
    83  // at startup, or 100 if the variable is not set.
    84  // A negative percentage disables garbage collection.
    85  func SetGCPercent(percent int) int {
    86  	old := setGCPercent(int32(percent))
    87  	runtime.GC()
    88  	return int(old)
    89  }
    90  
    91  // FreeOSMemory forces a garbage collection followed by an
    92  // attempt to return as much memory to the operating system
    93  // as possible. (Even if this is not called, the runtime gradually
    94  // returns memory to the operating system in a background task.)
    95  func FreeOSMemory() {
    96  	freeOSMemory()
    97  }
    98  
    99  // SetMaxStack sets the maximum amount of memory that
   100  // can be used by a single goroutine stack.
   101  // If any goroutine exceeds this limit while growing its stack,
   102  // the program crashes.
   103  // SetMaxStack returns the previous setting.
   104  // The initial setting is 1 GB on 64-bit systems, 250 MB on 32-bit systems.
   105  //
   106  // SetMaxStack is useful mainly for limiting the damage done by
   107  // goroutines that enter an infinite recursion. It only limits future
   108  // stack growth.
   109  func SetMaxStack(bytes int) int {
   110  	return setMaxStack(bytes)
   111  }
   112  
   113  // SetMaxThreads sets the maximum number of operating system
   114  // threads that the Go program can use. If it attempts to use more than
   115  // this many, the program crashes.
   116  // SetMaxThreads returns the previous setting.
   117  // The initial setting is 10,000 threads.
   118  //
   119  // The limit controls the number of operating system threads, not the number
   120  // of goroutines. A Go program creates a new thread only when a goroutine
   121  // is ready to run but all the existing threads are blocked in system calls, cgo calls,
   122  // or are locked to other goroutines due to use of runtime.LockOSThread.
   123  //
   124  // SetMaxThreads is useful mainly for limiting the damage done by
   125  // programs that create an unbounded number of threads. The idea is
   126  // to take down the program before it takes down the operating system.
   127  func SetMaxThreads(threads int) int {
   128  	return setMaxThreads(threads)
   129  }
   130  
   131  // SetPanicOnFault controls the runtime's behavior when a program faults
   132  // at an unexpected (non-nil) address. Such faults are typically caused by
   133  // bugs such as runtime memory corruption, so the default response is to crash
   134  // the program. Programs working with memory-mapped files or unsafe
   135  // manipulation of memory may cause faults at non-nil addresses in less
   136  // dramatic situations; SetPanicOnFault allows such programs to request
   137  // that the runtime trigger only a panic, not a crash.
   138  // SetPanicOnFault applies only to the current goroutine.
   139  // It returns the previous setting.
   140  func SetPanicOnFault(enabled bool) bool {
   141  	return setPanicOnFault(enabled)
   142  }
   143  
   144  // WriteHeapDump writes a description of the heap and the objects in
   145  // it to the given file descriptor.
   146  // The heap dump format is defined at http://golang.org/s/go13heapdump.
   147  func WriteHeapDump(fd uintptr)