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

     1  /*
     2  © 2022–present Harald Rudell <harald.rudell@gmail.com> (https://haraldrudell.github.io/haraldrudell/)
     3  ISC License
     4  */
     5  
     6  package parl
     7  
     8  import (
     9  	"fmt"
    10  
    11  	"github.com/haraldrudell/parl/pruntime"
    12  )
    13  
    14  // Stack contains a stack trace parsed into basic type only datapoints
    15  //   - stack trace from [pdebug.Stack]
    16  type Stack interface {
    17  	// thread ID 1… for the thread requesting the stack trace
    18  	//	- ThreadID is comparable and has IsValid and String methods
    19  	//	- ThreadID is typically an incremented 64-bit integer with
    20  	//		main thread having ID 1
    21  	ID() (threadID ThreadID)
    22  	// a word indicating thread status, typically word “running”
    23  	Status() (threadStatus ThreadStatus)
    24  	// true if the thread is the main thread
    25  	//	- false for a launched goroutine
    26  	IsMain() (isMain bool)
    27  	// A list of code locations for this thread
    28  	//	- index [0] is the most recent code location, typically the invoker requesting the stack trace
    29  	//	- includes invocation argument values
    30  	Frames() (frames []pruntime.Frame)
    31  	// the goroutine function used to launch this thread
    32  	//	- if IsMain is true, zero-value. Check using GoFunction().IsSet()
    33  	//	- never nil
    34  	GoFunction() (goFunction *pruntime.CodeLocation)
    35  	// the code location of the go statement creating this thread
    36  	//	- if IsMain is true, zero-value. Check with Creator().IsSet()
    37  	//	- never nil
    38  	//	- goRoutineRef: “in goroutine 9”
    39  	Creator() (creator *pruntime.CodeLocation, creatorID ThreadID, goRoutineRef string)
    40  	// Shorts lists short code locations for all stack frames, most recent first:
    41  	// Shorts("prepend") →
    42  	//  prepend Thread ID: 1
    43  	//  prepend main.someFunction()-pruntime.go:84
    44  	//  prepend main.main()-pruntime.go:52
    45  	Shorts(prepend string) (s string)
    46  	// String is a multi-line stack trace, most recent code location first:
    47  	//  ID: 18 IsMain: false status: running␤
    48  	//  main.someFunction({0x100dd2616, 0x19})␤
    49  	//  ␠␠pruntime.go:64␤
    50  	//  cre: main.main-pruntime.go:53␤
    51  	fmt.Stringer
    52  }
    53  
    54  // Frame represents an executing code location, ie. a code line in source code
    55  //   - parl.Frame is similar to [runtime.Frame] returned by [runtime.CallersFrames]
    56  //     but has only basic types, ie. it can be printed, stored and transferred
    57  type Frame interface {
    58  	// the code location for this frame, never nil
    59  	Loc() (location *pruntime.CodeLocation)
    60  	// function argument values like “(1, 0x14000113040)”
    61  	//	- values of basic types like int are displayed
    62  	//	- most types appear as a pointer value “0x…”
    63  	Args() (args string)
    64  	// prints the Frame suitable to be part of a stack trace
    65  	//   - fully qualified package name with function or type and method
    66  	//     and argument values
    67  	//   - absolute path to source file and line number
    68  	//
    69  	// output:
    70  	//
    71  	//	github.com/haraldrudell/parl/pdebug.TestFrame(0x1400014a340)␤
    72  	//	␠␠frame_test.go:15
    73  	String() (s string)
    74  }