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