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 }