libgo/go/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         The runtime package 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 // FuncForPC returns a *Func describing the function that contains the
  35 // given program counter address, or else nil.
  36 func FuncForPC(pc uintptr) *Func
  37
  38 // NOTE(rsc): Func must match struct Func in runtime.h
  39
  40 // Func records information about a function in the program,
  41 // in particular  the mapping from program counters to source
  42 // line numbers within that function.
  43 type Func struct {
  44         name   string
  45         typ    string
  46         src    string
  47         pcln   []byte
  48         entry  uintptr
  49         pc0    uintptr
  50         ln0    int32
  51         frame  int32
  52         args   int32
  53         locals int32
  54 }
  55
  56 // Name returns the name of the function.
  57 func (f *Func) Name() string { return f.name }
  58
  59 // Entry returns the entry address of the function.
  60 func (f *Func) Entry() uintptr { return f.entry }
  61
  62 // FileLine returns the file name and line number of the
  63 // source code corresponding to the program counter pc.
  64 // The result will not be accurate if pc is not a program
  65 // counter within f.
  66 func (f *Func) FileLine(pc uintptr) (file string, line int) {
  67         // NOTE(rsc): If you edit this function, also edit
  68         // symtab.c:/^funcline.
  69         var pcQuant uintptr = 1
  70         if GOARCH == "arm" {
  71                 pcQuant = 4
  72         }
  73
  74         targetpc := pc
  75         p := f.pcln
  76         pc = f.pc0
  77         line = int(f.ln0)
  78         file = f.src
  79         for i := 0; i < len(p) && pc <= targetpc; i++ {
  80                 switch {
  81                 case p[i] == 0:
  82                         line += int(p[i+1]<<24) | int(p[i+2]<<16) | int(p[i+3]<<8) | int(p[i+4])
  83                         i += 4
  84                 case p[i] <= 64:
  85                         line += int(p[i])
  86                 case p[i] <= 128:
  87                         line -= int(p[i] - 64)
  88                 default:
  89                         pc += pcQuant * uintptr(p[i]-129)
  90                 }
  91                 pc += pcQuant
  92         }
  93         return
  94 }
  95
  96 // mid returns the current os thread (m) id.
  97 func mid() uint32
  98
  99 // Semacquire waits until *s > 0 and then atomically decrements it.
 100 // It is intended as a simple sleep primitive for use by the synchronization
 101 // library and should not be used directly.
 102 func Semacquire(s *uint32)
 103
 104 // Semrelease atomically increments *s and notifies a waiting goroutine
 105 // if one is blocked in Semacquire.
 106 // It is intended as a simple wakeup primitive for use by the synchronization
 107 // library and should not be used directly.
 108 func Semrelease(s *uint32)
 109
 110 // SetFinalizer sets the finalizer associated with x to f.
 111 // When the garbage collector finds an unreachable block
 112 // with an associated finalizer, it clears the association and runs
 113 // f(x) in a separate goroutine.  This makes x reachable again, but
 114 // now without an associated finalizer.  Assuming that SetFinalizer
 115 // is not called again, the next time the garbage collector sees
 116 // that x is unreachable, it will free x.
 117 //
 118 // SetFinalizer(x, nil) clears any finalizer associated with x.
 119 //
 120 // The argument x must be a pointer to an object allocated by
 121 // calling new or by taking the address of a composite literal.
 122 // The argument f must be a function that takes a single argument
 123 // of x's type and returns no arguments.  If either of these is not
 124 // true, SetFinalizer aborts the program.
 125 //
 126 // Finalizers are run in dependency order: if A points at B, both have
 127 // finalizers, and they are otherwise unreachable, only the finalizer
 128 // for A runs; once A is freed, the finalizer for B can run.
 129 // If a cyclic structure includes a block with a finalizer, that
 130 // cycle is not guaranteed to be garbage collected and the finalizer
 131 // is not guaranteed to run, because there is no ordering that
 132 // respects the dependencies.
 133 //
 134 // The finalizer for x is scheduled to run at some arbitrary time after
 135 // x becomes unreachable.
 136 // There is no guarantee that finalizers will run before a program exits,
 137 // so typically they are useful only for releasing non-memory resources
 138 // associated with an object during a long-running program.
 139 // For example, an os.File object could use a finalizer to close the
 140 // associated operating system file descriptor when a program discards
 141 // an os.File without calling Close, but it would be a mistake
 142 // to depend on a finalizer to flush an in-memory I/O buffer such as a
 143 // bufio.Writer, because the buffer would not be flushed at program exit.
 144 //
 145 // A single goroutine runs all finalizers for a program, sequentially.
 146 // If a finalizer must run for a long time, it should do so by starting
 147 // a new goroutine.
 148 //
 149 // TODO(rsc): allow f to have (ignored) return values
 150 //
 151 func SetFinalizer(x, f interface{})
 152
 153 func getgoroot() string
 154
 155 // GOROOT returns the root of the Go tree.
 156 // It uses the GOROOT environment variable, if set,
 157 // or else the root used during the Go build.
 158 func GOROOT() string {
 159         s := getgoroot()
 160         if s != "" {
 161                 return s
 162         }
 163         return defaultGoroot
 164 }
 165
 166 // Version returns the Go tree's version string.
 167 // It is either a sequence number or, when possible,
 168 // a release tag like "release.2010-03-04".
 169 // A trailing + indicates that the tree had local modifications
 170 // at the time of the build.
 171 func Version() string {
 172         return theVersion
 173 }
 174
 175 // GOOS is the Go tree's operating system target:
 176 // one of darwin, freebsd, linux, and so on.
 177 const GOOS string = theGoos
 178
 179 // GOARCH is the Go tree's architecture target:
 180 // 386, amd64, or arm.
 181 const GOARCH string = theGoarch