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 package runtime 12 13 // Gosched yields the processor, allowing other goroutines to run. It does not 14 // suspend the current goroutine, so execution resumes automatically. 15 func Gosched() 16 17 // Goexit terminates the goroutine that calls it. No other goroutine is affected. 18 // Goexit runs all deferred calls before terminating the goroutine. 19 func Goexit() 20 21 // Caller reports file and line number information about function invocations on 22 // the calling goroutine's stack. The argument skip is the number of stack frames 23 // to ascend, with 1 identifying the caller of Caller. (For historical reasons the 24 // meaning of skip differs between Caller and Callers.) The return values report the 25 // program counter, file name, and line number within the file of the corresponding 26 // call. The boolean ok is false if it was not possible to recover the information. 27 func Caller(skip int) (pc uintptr, file string, line int, ok bool) 28 29 // Callers fills the slice pc with the program counters of function invocations 30 // on the calling goroutine's stack. The argument skip is the number of stack frames 31 // to skip before recording in pc, with 0 starting at the caller of Callers. 32 // It returns the number of entries written to pc. 33 func Callers(skip int, pc []uintptr) int 34 35 type Func struct { // Keep in sync with runtime.h:struct Func 36 name string 37 typ string // go type string 38 src string // src file name 39 pcln []byte // pc/ln tab for this func 40 entry uintptr // entry pc 41 pc0 uintptr // starting pc, ln for table 42 ln0 int32 43 frame int32 // stack frame size 44 args int32 // number of 32-bit in/out args 45 locals int32 // number of 32-bit locals 46 } 47 48 // FuncForPC returns a *Func describing the function that contains the 49 // given program counter address, or else nil. 50 func FuncForPC(pc uintptr) *Func 51 52 // Name returns the name of the function. 53 func (f *Func) Name() string { return f.name } 54 55 // Entry returns the entry address of the function. 56 func (f *Func) Entry() uintptr { return f.entry } 57 58 // FileLine returns the file name and line number of the 59 // source code corresponding to the program counter pc. 60 // The result will not be accurate if pc is not a program 61 // counter within f. 62 func (f *Func) FileLine(pc uintptr) (file string, line int) { 63 return funcline_go(f, pc) 64 } 65 66 // implemented in symtab.c 67 func funcline_go(*Func, uintptr) (string, int) 68 69 // mid returns the current os thread (m) id. 70 func mid() uint32 71 72 // SetFinalizer sets the finalizer associated with x to f. 73 // When the garbage collector finds an unreachable block 74 // with an associated finalizer, it clears the association and runs 75 // f(x) in a separate goroutine. This makes x reachable again, but 76 // now without an associated finalizer. Assuming that SetFinalizer 77 // is not called again, the next time the garbage collector sees 78 // that x is unreachable, it will free x. 79 // 80 // SetFinalizer(x, nil) clears any finalizer associated with x. 81 // 82 // The argument x must be a pointer to an object allocated by 83 // calling new or by taking the address of a composite literal. 84 // The argument f must be a function that takes a single argument 85 // of x's type and can have arbitrary ignored return values. 86 // If either of these is not true, SetFinalizer aborts the program. 87 // 88 // Finalizers are run in dependency order: if A points at B, both have 89 // finalizers, and they are otherwise unreachable, only the finalizer 90 // for A runs; once A is freed, the finalizer for B can run. 91 // If a cyclic structure includes a block with a finalizer, that 92 // cycle is not guaranteed to be garbage collected and the finalizer 93 // is not guaranteed to run, because there is no ordering that 94 // respects the dependencies. 95 // 96 // The finalizer for x is scheduled to run at some arbitrary time after 97 // x becomes unreachable. 98 // There is no guarantee that finalizers will run before a program exits, 99 // so typically they are useful only for releasing non-memory resources 100 // associated with an object during a long-running program. 101 // For example, an os.File object could use a finalizer to close the 102 // associated operating system file descriptor when a program discards 103 // an os.File without calling Close, but it would be a mistake 104 // to depend on a finalizer to flush an in-memory I/O buffer such as a 105 // bufio.Writer, because the buffer would not be flushed at program exit. 106 // 107 // A single goroutine runs all finalizers for a program, sequentially. 108 // If a finalizer must run for a long time, it should do so by starting 109 // a new goroutine. 110 func SetFinalizer(x, f interface{}) 111 112 func getgoroot() string 113 114 // GOROOT returns the root of the Go tree. 115 // It uses the GOROOT environment variable, if set, 116 // or else the root used during the Go build. 117 func GOROOT() string { 118 s := getgoroot() 119 if s != "" { 120 return s 121 } 122 return defaultGoroot 123 } 124 125 // Version returns the Go tree's version string. 126 // It is either a sequence number or, when possible, 127 // a release tag like "release.2010-03-04". 128 // A trailing + indicates that the tree had local modifications 129 // at the time of the build. 130 func Version() string { 131 return theVersion 132 } 133 134 // GOOS is the running program's operating system target: 135 // one of darwin, freebsd, linux, and so on. 136 const GOOS string = theGoos 137 138 // GOARCH is the running program's architecture target: 139 // 386, amd64, or arm. 140 const GOARCH string = theGoarch