...
Run Format

Source file src/pkg/runtime/extern.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	/*
     6	Package runtime contains operations that interact with Go's runtime system,
     7	such as functions to control goroutines. It also includes the low-level type information
     8	used by the reflect package; see reflect's documentation for the programmable
     9	interface to the run-time type system.
    10	
    11	Environment Variables
    12	
    13	The following environment variables ($name or %name%, depending on the host
    14	operating system) control the run-time behavior of Go programs. The meanings
    15	and use may change from release to release.
    16	
    17	The GOGC variable sets the initial garbage collection target percentage.
    18	A collection is triggered when the ratio of freshly allocated data to live data
    19	remaining after the previous collection reaches this percentage. The default
    20	is GOGC=100. Setting GOGC=off disables the garbage collector entirely.
    21	The runtime/debug package's SetGCPercent function allows changing this
    22	percentage at run time. See http://golang.org/pkg/runtime/debug/#SetGCPercent.
    23	
    24	The GODEBUG variable controls debug output from the runtime. GODEBUG value is
    25	a comma-separated list of name=val pairs. Supported names are:
    26	
    27		allocfreetrace: setting allocfreetrace=1 causes every allocation to be
    28		profiled and a stack trace printed on each object's allocation and free.
    29	
    30		efence: setting efence=1 causes the allocator to run in a mode
    31		where each object is allocated on a unique page and addresses are
    32		never recycled.
    33	
    34		gctrace: setting gctrace=1 causes the garbage collector to emit a single line to standard
    35		error at each collection, summarizing the amount of memory collected and the
    36		length of the pause. Setting gctrace=2 emits the same summary but also
    37		repeats each collection.
    38	
    39		gcdead: setting gcdead=1 causes the garbage collector to clobber all stack slots
    40		that it thinks are dead.
    41	
    42		scheddetail: setting schedtrace=X and scheddetail=1 causes the scheduler to emit
    43		detailed multiline info every X milliseconds, describing state of the scheduler,
    44		processors, threads and goroutines.
    45	
    46		schedtrace: setting schedtrace=X causes the scheduler to emit a single line to standard
    47		error every X milliseconds, summarizing the scheduler state.
    48	
    49	The GOMAXPROCS variable limits the number of operating system threads that
    50	can execute user-level Go code simultaneously. There is no limit to the number of threads
    51	that can be blocked in system calls on behalf of Go code; those do not count against
    52	the GOMAXPROCS limit. This package's GOMAXPROCS function queries and changes
    53	the limit.
    54	
    55	The GOTRACEBACK variable controls the amount of output generated when a Go
    56	program fails due to an unrecovered panic or an unexpected runtime condition.
    57	By default, a failure prints a stack trace for every extant goroutine, eliding functions
    58	internal to the run-time system, and then exits with exit code 2.
    59	If GOTRACEBACK=0, the per-goroutine stack traces are omitted entirely.
    60	If GOTRACEBACK=1, the default behavior is used.
    61	If GOTRACEBACK=2, the per-goroutine stack traces include run-time functions.
    62	If GOTRACEBACK=crash, the per-goroutine stack traces include run-time functions,
    63	and if possible the program crashes in an operating-specific manner instead of
    64	exiting. For example, on Unix systems, the program raises SIGABRT to trigger a
    65	core dump.
    66	
    67	The GOARCH, GOOS, GOPATH, and GOROOT environment variables complete
    68	the set of Go environment variables. They influence the building of Go programs
    69	(see http://golang.org/cmd/go and http://golang.org/pkg/go/build).
    70	GOARCH, GOOS, and GOROOT are recorded at compile time and made available by
    71	constants or functions in this package, but they do not influence the execution
    72	of the run-time system.
    73	*/
    74	package runtime
    75	
    76	// Gosched yields the processor, allowing other goroutines to run.  It does not
    77	// suspend the current goroutine, so execution resumes automatically.
    78	func Gosched()
    79	
    80	// Goexit terminates the goroutine that calls it.  No other goroutine is affected.
    81	// Goexit runs all deferred calls before terminating the goroutine.
    82	//
    83	// Calling Goexit from the main goroutine terminates that goroutine
    84	// without func main returning. Since func main has not returned,
    85	// the program continues execution of other goroutines.
    86	// If all other goroutines exit, the program crashes.
    87	func Goexit()
    88	
    89	// Caller reports file and line number information about function invocations on
    90	// the calling goroutine's stack.  The argument skip is the number of stack frames
    91	// to ascend, with 0 identifying the caller of Caller.  (For historical reasons the
    92	// meaning of skip differs between Caller and Callers.) The return values report the
    93	// program counter, file name, and line number within the file of the corresponding
    94	// call.  The boolean ok is false if it was not possible to recover the information.
    95	func Caller(skip int) (pc uintptr, file string, line int, ok bool)
    96	
    97	// Callers fills the slice pc with the program counters of function invocations
    98	// on the calling goroutine's stack.  The argument skip is the number of stack frames
    99	// to skip before recording in pc, with 0 identifying the frame for Callers itself and
   100	// 1 identifying the caller of Callers.
   101	// It returns the number of entries written to pc.
   102	func Callers(skip int, pc []uintptr) int
   103	
   104	type Func struct {
   105		opaque struct{} // unexported field to disallow conversions
   106	}
   107	
   108	// FuncForPC returns a *Func describing the function that contains the
   109	// given program counter address, or else nil.
   110	func FuncForPC(pc uintptr) *Func
   111	
   112	// Name returns the name of the function.
   113	func (f *Func) Name() string {
   114		return funcname_go(f)
   115	}
   116	
   117	// Entry returns the entry address of the function.
   118	func (f *Func) Entry() uintptr {
   119		return funcentry_go(f)
   120	}
   121	
   122	// FileLine returns the file name and line number of the
   123	// source code corresponding to the program counter pc.
   124	// The result will not be accurate if pc is not a program
   125	// counter within f.
   126	func (f *Func) FileLine(pc uintptr) (file string, line int) {
   127		return funcline_go(f, pc)
   128	}
   129	
   130	// implemented in symtab.c
   131	func funcline_go(*Func, uintptr) (string, int)
   132	func funcname_go(*Func) string
   133	func funcentry_go(*Func) uintptr
   134	
   135	// SetFinalizer sets the finalizer associated with x to f.
   136	// When the garbage collector finds an unreachable block
   137	// with an associated finalizer, it clears the association and runs
   138	// f(x) in a separate goroutine.  This makes x reachable again, but
   139	// now without an associated finalizer.  Assuming that SetFinalizer
   140	// is not called again, the next time the garbage collector sees
   141	// that x is unreachable, it will free x.
   142	//
   143	// SetFinalizer(x, nil) clears any finalizer associated with x.
   144	//
   145	// The argument x must be a pointer to an object allocated by
   146	// calling new or by taking the address of a composite literal.
   147	// The argument f must be a function that takes a single argument
   148	// to which x's type can be assigned, and can have arbitrary ignored return
   149	// values. If either of these is not true, SetFinalizer aborts the
   150	// program.
   151	//
   152	// Finalizers are run in dependency order: if A points at B, both have
   153	// finalizers, and they are otherwise unreachable, only the finalizer
   154	// for A runs; once A is freed, the finalizer for B can run.
   155	// If a cyclic structure includes a block with a finalizer, that
   156	// cycle is not guaranteed to be garbage collected and the finalizer
   157	// is not guaranteed to run, because there is no ordering that
   158	// respects the dependencies.
   159	//
   160	// The finalizer for x is scheduled to run at some arbitrary time after
   161	// x becomes unreachable.
   162	// There is no guarantee that finalizers will run before a program exits,
   163	// so typically they are useful only for releasing non-memory resources
   164	// associated with an object during a long-running program.
   165	// For example, an os.File object could use a finalizer to close the
   166	// associated operating system file descriptor when a program discards
   167	// an os.File without calling Close, but it would be a mistake
   168	// to depend on a finalizer to flush an in-memory I/O buffer such as a
   169	// bufio.Writer, because the buffer would not be flushed at program exit.
   170	//
   171	// It is not guaranteed that a finalizer will run if the size of *x is
   172	// zero bytes.
   173	//
   174	// A single goroutine runs all finalizers for a program, sequentially.
   175	// If a finalizer must run for a long time, it should do so by starting
   176	// a new goroutine.
   177	func SetFinalizer(x, f interface{})
   178	
   179	func getgoroot() string
   180	
   181	// GOROOT returns the root of the Go tree.
   182	// It uses the GOROOT environment variable, if set,
   183	// or else the root used during the Go build.
   184	func GOROOT() string {
   185		s := getgoroot()
   186		if s != "" {
   187			return s
   188		}
   189		return defaultGoroot
   190	}
   191	
   192	// Version returns the Go tree's version string.
   193	// It is either the commit hash and date at the time of the build or,
   194	// when possible, a release tag like "go1.3".
   195	func Version() string {
   196		return theVersion
   197	}
   198	
   199	// GOOS is the running program's operating system target:
   200	// one of darwin, freebsd, linux, and so on.
   201	const GOOS string = theGoos
   202	
   203	// GOARCH is the running program's architecture target:
   204	// 386, amd64, or arm.
   205	const GOARCH string = theGoarch
   206	

View as plain text