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 to 23 // ascend, with 0 identifying the the caller of Caller. The return values report the 24 // program counter, file name, and line number within the file of the corresponding 25 // call. The boolean ok is false if it was not possible to recover the information. 26 func Caller(skip int) (pc uintptr, file string, line int, ok bool) 27 28 // Callers fills the slice pc with the program counters of function invocations 29 // on the calling goroutine's stack. The argument skip is the number of stack frames 30 // to skip before recording in pc, with 0 starting at the caller of Caller. 31 // It returns the number of entries written to pc. 32 func Callers(skip int, pc []uintptr) int 33 34 type Func struct { // Keep in sync with runtime.h:struct Func 35 name string 36 typ string // go type string 37 src string // src file name 38 pcln []byte // pc/ln tab for this func 39 entry uintptr // entry pc 40 pc0 uintptr // starting pc, ln for table 41 ln0 int32 42 frame int32 // stack frame size 43 args int32 // number of 32-bit in/out args 44 locals int32 // number of 32-bit locals 45 } 46 47 // FuncForPC returns a *Func describing the function that contains the 48 // given program counter address, or else nil. 49 func FuncForPC(pc uintptr) *Func 50 51 // Name returns the name of the function. 52 func (f *Func) Name() string { return f.name } 53 54 // Entry returns the entry address of the function. 55 func (f *Func) Entry() uintptr { return f.entry } 56 57 // FileLine returns the file name and line number of the 58 // source code corresponding to the program counter pc. 59 // The result will not be accurate if pc is not a program 60 // counter within f. 61 func (f *Func) FileLine(pc uintptr) (file string, line int) { 62 // NOTE(rsc): If you edit this function, also edit 63 // symtab.c:/^funcline. That function also has the 64 // comments explaining the logic. 65 targetpc := pc 66 67 var pcQuant uintptr = 1 68 if GOARCH == "arm" { 69 pcQuant = 4 70 } 71 72 p := f.pcln 73 pc = f.pc0 74 line = int(f.ln0) 75 i := 0 76 //print("FileLine start pc=", pc, " targetpc=", targetpc, " line=", line, 77 // " tab=", p, " ", p[0], " quant=", pcQuant, " GOARCH=", GOARCH, "\n") 78 for { 79 for i < len(p) && p[i] > 128 { 80 pc += pcQuant * uintptr(p[i]-128) 81 i++ 82 } 83 //print("pc<", pc, " targetpc=", targetpc, " line=", line, "\n") 84 if pc > targetpc || i >= len(p) { 85 break 86 } 87 if p[i] == 0 { 88 if i+5 > len(p) { 89 break 90 } 91 line += int(p[i+1]<<24) | int(p[i+2]<<16) | int(p[i+3]<<8) | int(p[i+4]) 92 i += 5 93 } else if p[i] <= 64 { 94 line += int(p[i]) 95 i++ 96 } else { 97 line -= int(p[i] - 64) 98 i++ 99 } 100 //print("pc=", pc, " targetpc=", targetpc, " line=", line, "\n") 101 pc += pcQuant 102 } 103 file = f.src 104 return 105 } 106 107 // mid returns the current os thread (m) id. 108 func mid() uint32 109 110 // Semacquire waits until *s > 0 and then atomically decrements it. 111 // It is intended as a simple sleep primitive for use by the synchronization 112 // library and should not be used directly. 113 func Semacquire(s *uint32) 114 115 // Semrelease atomically increments *s and notifies a waiting goroutine 116 // if one is blocked in Semacquire. 117 // It is intended as a simple wakeup primitive for use by the synchronization 118 // library and should not be used directly. 119 func Semrelease(s *uint32) 120 121 // SetFinalizer sets the finalizer associated with x to f. 122 // When the garbage collector finds an unreachable block 123 // with an associated finalizer, it clears the association and runs 124 // f(x) in a separate goroutine. This makes x reachable again, but 125 // now without an associated finalizer. Assuming that SetFinalizer 126 // is not called again, the next time the garbage collector sees 127 // that x is unreachable, it will free x. 128 // 129 // SetFinalizer(x, nil) clears any finalizer associated with x. 130 // 131 // The argument x must be a pointer to an object allocated by 132 // calling new or by taking the address of a composite literal. 133 // The argument f must be a function that takes a single argument 134 // of x's type and returns no arguments. If either of these is not 135 // true, SetFinalizer aborts the 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 // 160 // TODO(rsc): allow f to have (ignored) return values 161 // 162 func SetFinalizer(x, f interface{}) 163 164 func getgoroot() string 165 166 // GOROOT returns the root of the Go tree. 167 // It uses the GOROOT environment variable, if set, 168 // or else the root used during the Go build. 169 func GOROOT() string { 170 s := getgoroot() 171 if s != "" { 172 return s 173 } 174 return defaultGoroot 175 } 176 177 // Version returns the Go tree's version string. 178 // It is either a sequence number or, when possible, 179 // a release tag like "release.2010-03-04". 180 // A trailing + indicates that the tree had local modifications 181 // at the time of the build. 182 func Version() string { 183 return theVersion 184 } 185 186 // GOOS is the Go tree's operating system target: 187 // one of darwin, freebsd, linux, and so on. 188 const GOOS string = theGoos 189 190 // GOARCH is the Go tree's architecture target: 191 // 386, amd64, or arm. 192 const GOARCH string = theGoarch