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.
     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.
    11	Environment Variables
    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.
    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.
    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:
    27		allocfreetrace: setting allocfreetrace=1 causes every allocation to be
    28		profiled and a stack trace printed on each object's allocation and free.
    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.
    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.
    39		gcdead: setting gcdead=1 causes the garbage collector to clobber all stack slots
    40		that it thinks are dead.
    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.
    46		schedtrace: setting schedtrace=X causes the scheduler to emit a single line to standard
    47		error every X milliseconds, summarizing the scheduler state.
    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.
    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.
    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
    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()
    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()
    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)
    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
   104	type Func struct {
   105		opaque struct{} // unexported field to disallow conversions
   106	}
   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
   112	// Name returns the name of the function.
   113	func (f *Func) Name() string {
   114		return funcname_go(f)
   115	}
   117	// Entry returns the entry address of the function.
   118	func (f *Func) Entry() uintptr {
   119		return funcentry_go(f)
   120	}
   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	}
   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
   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{})
   179	func getgoroot() string
   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	}
   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	}
   199	// GOOS is the running program's operating system target:
   200	// one of darwin, freebsd, linux, and so on.
   201	const GOOS string = theGoos
   203	// GOARCH is the running program's architecture target:
   204	// 386, amd64, or arm.
   205	const GOARCH string = theGoarch

View as plain text