Source file src/pkg/runtime/debug.go
1 // Copyright 2009 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 runtime 6 7 // Breakpoint() executes a breakpoint trap. 8 func Breakpoint() 9 10 // LockOSThread wires the calling goroutine to its current operating system thread. 11 // Until the calling goroutine exits or calls UnlockOSThread, it will always 12 // execute in that thread, and no other goroutine can. 13 func LockOSThread() 14 15 // UnlockOSThread unwires the calling goroutine from its fixed operating system thread. 16 // If the calling goroutine has not called LockOSThread, UnlockOSThread is a no-op. 17 func UnlockOSThread() 18 19 // GOMAXPROCS sets the maximum number of CPUs that can be executing 20 // simultaneously and returns the previous setting. If n < 1, it does not 21 // change the current setting. 22 // The number of logical CPUs on the local machine can be queried with NumCPU. 23 // This call will go away when the scheduler improves. 24 func GOMAXPROCS(n int) int 25 26 // NumCPU returns the number of logical CPUs on the local machine. 27 func NumCPU() int 28 29 // NumCgoCall returns the number of cgo calls made by the current process. 30 func NumCgoCall() int64 31 32 // NumGoroutine returns the number of goroutines that currently exist. 33 func NumGoroutine() int 34 35 // MemProfileRate controls the fraction of memory allocations 36 // that are recorded and reported in the memory profile. 37 // The profiler aims to sample an average of 38 // one allocation per MemProfileRate bytes allocated. 39 // 40 // To include every allocated block in the profile, set MemProfileRate to 1. 41 // To turn off profiling entirely, set MemProfileRate to 0. 42 // 43 // The tools that process the memory profiles assume that the 44 // profile rate is constant across the lifetime of the program 45 // and equal to the current value. Programs that change the 46 // memory profiling rate should do so just once, as early as 47 // possible in the execution of the program (for example, 48 // at the beginning of main). 49 var MemProfileRate int = 512 * 1024 50 51 // A MemProfileRecord describes the live objects allocated 52 // by a particular call sequence (stack trace). 53 type MemProfileRecord struct { 54 AllocBytes, FreeBytes int64 // number of bytes allocated, freed 55 AllocObjects, FreeObjects int64 // number of objects allocated, freed 56 Stack0 [32]uintptr // stack trace for this record; ends at first 0 entry 57 } 58 59 // InUseBytes returns the number of bytes in use (AllocBytes - FreeBytes). 60 func (r *MemProfileRecord) InUseBytes() int64 { return r.AllocBytes - r.FreeBytes } 61 62 // InUseObjects returns the number of objects in use (AllocObjects - FreeObjects). 63 func (r *MemProfileRecord) InUseObjects() int64 { 64 return r.AllocObjects - r.FreeObjects 65 } 66 67 // Stack returns the stack trace associated with the record, 68 // a prefix of r.Stack0. 69 func (r *MemProfileRecord) Stack() []uintptr { 70 for i, v := range r.Stack0 { 71 if v == 0 { 72 return r.Stack0[0:i] 73 } 74 } 75 return r.Stack0[0:] 76 } 77 78 // MemProfile returns n, the number of records in the current memory profile. 79 // If len(p) >= n, MemProfile copies the profile into p and returns n, true. 80 // If len(p) < n, MemProfile does not change p and returns n, false. 81 // 82 // If inuseZero is true, the profile includes allocation records 83 // where r.AllocBytes > 0 but r.AllocBytes == r.FreeBytes. 84 // These are sites where memory was allocated, but it has all 85 // been released back to the runtime. 86 // 87 // Most clients should use the runtime/pprof package or 88 // the testing package's -test.memprofile flag instead 89 // of calling MemProfile directly. 90 func MemProfile(p []MemProfileRecord, inuseZero bool) (n int, ok bool) 91 92 // A StackRecord describes a single execution stack. 93 type StackRecord struct { 94 Stack0 [32]uintptr // stack trace for this record; ends at first 0 entry 95 } 96 97 // Stack returns the stack trace associated with the record, 98 // a prefix of r.Stack0. 99 func (r *StackRecord) Stack() []uintptr { 100 for i, v := range r.Stack0 { 101 if v == 0 { 102 return r.Stack0[0:i] 103 } 104 } 105 return r.Stack0[0:] 106 } 107 108 // ThreadCreateProfile returns n, the number of records in the thread creation profile. 109 // If len(p) >= n, ThreadCreateProfile copies the profile into p and returns n, true. 110 // If len(p) < n, ThreadCreateProfile does not change p and returns n, false. 111 // 112 // Most clients should use the runtime/pprof package instead 113 // of calling ThreadCreateProfile directly. 114 func ThreadCreateProfile(p []StackRecord) (n int, ok bool) 115 116 // GoroutineProfile returns n, the number of records in the active goroutine stack profile. 117 // If len(p) >= n, GoroutineProfile copies the profile into p and returns n, true. 118 // If len(p) < n, GoroutineProfile does not change p and returns n, false. 119 // 120 // Most clients should use the runtime/pprof package instead 121 // of calling GoroutineProfile directly. 122 func GoroutineProfile(p []StackRecord) (n int, ok bool) 123 124 // CPUProfile returns the next chunk of binary CPU profiling stack trace data, 125 // blocking until data is available. If profiling is turned off and all the profile 126 // data accumulated while it was on has been returned, CPUProfile returns nil. 127 // The caller must save the returned data before calling CPUProfile again. 128 // Most clients should use the runtime/pprof package or 129 // the testing package's -test.cpuprofile flag instead of calling 130 // CPUProfile directly. 131 func CPUProfile() []byte 132 133 // SetCPUProfileRate sets the CPU profiling rate to hz samples per second. 134 // If hz <= 0, SetCPUProfileRate turns off profiling. 135 // If the profiler is on, the rate cannot be changed without first turning it off. 136 // Most clients should use the runtime/pprof package or 137 // the testing package's -test.cpuprofile flag instead of calling 138 // SetCPUProfileRate directly. 139 func SetCPUProfileRate(hz int) 140 141 // Stack formats a stack trace of the calling goroutine into buf 142 // and returns the number of bytes written to buf. 143 // If all is true, Stack formats stack traces of all other goroutines 144 // into buf after the trace for the current goroutine. 145 func Stack(buf []byte, all bool) int