github.com/haraldrudell/parl@v0.4.176/pruntime/stack.go (about)

     1  /*
     2  © 2024–present Harald Rudell <harald.rudell@gmail.com> (https://haraldrudell.github.io/haraldrudell/)
     3  ISC License
     4  */
     5  
     6  /*
     7  Package pruntime provides an interface to the Go standard library’s runtime package using
     8  only serializable simple types
     9  
    10  Stack traces and code locations have several formats:
    11  
    12  	codeLocation := pruntime.NewCodeLocation(0)
    13  	codeLocation.Base() // package and type
    14  	  → mypackage.(*MyType).MyFunc
    15  	codeLocation.PackFunc() // very brief
    16  	  → mypackage.MyFunc
    17  	codeLocation.Name(): // function name only
    18  	  → MyFunc
    19  	codeLocation.Short() // line, no package path
    20  	  → mypackage.(*MyType).MyFunc-myfile.go:19
    21  	codeLocation.Long() // uniquely identifiable
    22  	  → codeberg.org/haraldrudell/mypackage.(*MyType).MyFunc-myfile.go:19
    23  	codeLocation.Full() // everything
    24  	  → codeberg.org/haraldrudell/mypackage.(*MyType).MyFunc-/fs/mypackage/myfile.go:19
    25  	codeLocation.String() // two lines
    26  	  → "codeberg.org/haraldrudell/mypackage.(*MyType).MyFunc\n  /fs/mypackage/myfile.go:19"
    27  
    28  Stack can determine where a goroutine was created and whether this is the main thread
    29  
    30  	pruntime.GoRoutineID()  → 1
    31  	pruntime.NewStack(0).Creator.Short()  → main.main-pruntime.go:30
    32  	fmt.Println(pruntime.NewStack(0).IsMainThread)  → true
    33  	pruntime.NewStack(0).Frames[0].Args  → (0x104c12c60?)
    34  */
    35  package pruntime
    36  
    37  import (
    38  	"fmt"
    39  )
    40  
    41  // Stack is implemented by:
    42  //   - [github.com/haraldrudell/parl.stack]
    43  //   - [github.com/haraldrudell/parl/pdebug.stack]
    44  type Stack interface {
    45  	// true if the thread is the main thread
    46  	//	- false for a launched goroutine
    47  	IsMain() (isMain bool)
    48  	// A list of code locations for this thread
    49  	//	- index [0] is the most recent code location, typically the invoker requesting the stack trace
    50  	//	- includes invocation argument values
    51  	Frames() (frames []Frame)
    52  	// the goroutine function used to launch this thread
    53  	//	- if IsMain is true, zero-value. Check using GoFunction().IsSet()
    54  	//	- never nil
    55  	GoFunction() (goFunction *CodeLocation)
    56  	// Shorts lists short code locations for all stack frames, most recent first:
    57  	// Shorts("prepend") →
    58  	//  prepend Thread ID: 1
    59  	//  prepend main.someFunction()-pruntime.go:84
    60  	//  prepend main.main()-pruntime.go:52
    61  	Shorts(prepend string) (s string)
    62  	// String is a multi-line stack trace, most recent code location first:
    63  	//  ID: 18 IsMain: false status: running␤
    64  	//  main.someFunction({0x100dd2616, 0x19})␤
    65  	//  ␠␠pruntime.go:64␤
    66  	//  cre: main.main-pruntime.go:53␤
    67  	fmt.Stringer
    68  }