pdebug

Documentation

Overview

Package pdebug provides a portable, parsed stack trace.

Index

• func NewStack(skipFrames int) (stack parl.Stack)
• func ParseCreatedLine(createdLine []byte) (funcName, goroutineRef string, IsMainThread bool)
• func ParseFileLine(fileLine []byte) (file string, line int)
• func ParseFirstLine(debugStack []byte) (ID parl.ThreadID, status parl.ThreadStatus, err error)
• func ParseFuncLine(funcLine []byte) (funcName string, args string)
• type Frame
  • func (f *Frame) Args() (args string)
  • func (f *Frame) Loc() (location *pruntime.CodeLocation)
  • func (f *Frame) String() (s string)
• type Stack
  • func (s *Stack) Creator() (creator *pruntime.CodeLocation, goRoutineRef string)
  • func (s *Stack) Dump() (s2 string)
  • func (s *Stack) Frames() (frames []parl.Frame)
  • func (s *Stack) GoFunction() (goFunction *pruntime.CodeLocation)
  • func (s *Stack) ID() (threadID parl.ThreadID)
  • func (s *Stack) IsMain() (isMainThread bool)
  • func (s *Stack) Shorts(prepend string) (shorts string)
  • func (s *Stack) Status() (status parl.ThreadStatus)
  • func (s *Stack) String() (s2 string)

Functions

func NewStack

func NewStack(skipFrames int) (stack parl.Stack)

NewStack populates a Stack object with the current thread and its stack using debug.Stack

func ParseCreatedLine

func ParseCreatedLine(createdLine []byte) (funcName, goroutineRef string, IsMainThread bool)

ParseCreatedLine parses the second-to-last line of the stack trace. samples:

• “created by main.main”
• “created by main.(*MyType).goroutine1”
• “main.main()”
• go1.21.5 231219: “created by codeberg.org/haraldrudell/tools/gact.(*Transcriber).TranscriberThread in goroutine 9”

func ParseFileLine

func ParseFileLine(fileLine []byte) (file string, line int)

ParseFileLine parses a line of a tab character then absolue file path, followed by a colon and line number, then a space character and a byte offset.

"\t/gp-debug-stack/debug-stack.go:29 +0x44"
"\t/opt/sw/parl/g0/waiterr.go:49"

func ParseFirstLine

func ParseFirstLine(debugStack []byte) (ID parl.ThreadID, status parl.ThreadStatus, err error)

getID obtains gorutine ID, as of go1.18 a numeric string "1"…

func ParseFuncLine

func ParseFuncLine(funcLine []byte) (funcName string, args string)

ParseFuncLine parses a line of a package name, optionally fully qualified, and a possible receiver type name and a function name, followed by a parenthesised argument list. samples:

main.main()
main.(*MyType).goroutine1(0x0?, 0x140000120d0, 0x2)
codeberg.org/haraldrudell/goprogramming/std/runtime-debug/gp-debug-stack/mypackage.Fn(...)

Types

type Frame

type Frame struct {
	pruntime.CodeLocation
	// contains filtered or unexported fields
}

Frame represents an executing code location, ie. a code line in source code

• parl.Frame is similar to runtime.Frame returned by runtime.CallersFrames but has only basic types, ie. can be stored or transferred
• pdebug.Frame implements parl.Frame
• Frame is a value container only created by pdebug.NewStack. Frame extends pruntime.CodeLocation with argument values

func (*Frame) Args

func (f *Frame) Args() (args string)

function argument values like "(1, 0x14000113040)"

• values of basic types like int are displayed
• most types appear as a pointer value “0x…”

func (*Frame) Loc

func (f *Frame) Loc() (location *pruntime.CodeLocation)

the code location for this frame, never nil

func (*Frame) String

func (f *Frame) String() (s string)

prints the Frame suitable to be part of a stack trace

• fully qualified package name with function or type and method and argument values
• absolute path to source file and line number

output:

github.com/haraldrudell/parl/pdebug.TestFrame(0x1400014a340)␤
␠␠frame_test.go:15

type Stack

type Stack struct {
	// contains filtered or unexported fields
}

• Go stack traces are created by runtime.Stack and is a byte slice
• [debug.Stack] repeatedly calls runtime.Stack with an increased buffer size that is eventually returned
• [debug.PrintStack] writes the byte stream to os.Stderr
• interning large strings is a temporary memory leak. Converting the entire byte-slice stack-trace to string retains the memory for as long as there is a reference to any one character. This leads to megabytes of memory leaks

func (*Stack) Creator

func (s *Stack) Creator() (creator *pruntime.CodeLocation, goRoutineRef string)

the code location of the go statement creating this thread

• if IsMain is true, zero-value. Check with Creator().IsSet()
• never nil

func (*Stack) Dump

func (s *Stack) Dump() (s2 string)

func (*Stack) Frames

func (s *Stack) Frames() (frames []parl.Frame)

A list of code locations for this thread

• index [0] is the most recent code location, typically the invoker requesting the stack trace
• includes invocation argument values

func (*Stack) GoFunction

func (s *Stack) GoFunction() (goFunction *pruntime.CodeLocation)

the goroutine function used to launch this thread

• if IsMain is true, zero-value. Check using GoFunction().IsSet()
• never nil

func (*Stack) ID

func (s *Stack) ID() (threadID parl.ThreadID)

thread ID 1… for the thread requesting the stack trace

• ThreadID is comparable and has IsValid and String methods
• ThreadID is typically an incremented 64-bit integer with main thread having ID 1

func (*Stack) IsMain

func (s *Stack) IsMain() (isMainThread bool)

true if the thread is the main thread

• false for a launched goroutine

func (*Stack) Shorts

func (s *Stack) Shorts(prepend string) (shorts string)

Shorts lists short code locations for all stack frames, most recent first: Shorts("prepend") →

prepend Thread ID: 1
prepend main.someFunction()-pruntime.go:84
prepend main.main()-pruntime.go:52

func (*Stack) Status

func (s *Stack) Status() (status parl.ThreadStatus)

a word indicating thread status, typically word “running”

func (*Stack) String

func (s *Stack) String() (s2 string)

String is a multi-line stack trace, most recent code location first:

ID: 18 IsMain: false status: running␤
main.someFunction({0x100dd2616, 0x19})␤
␠␠pruntime.go:64␤
cre: main.main-pruntime.go:53␤