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

View as plain text