// Copyright 2014 The Go Authors. All rights reserved.// Use of this source code is governed by a BSD-style// license that can be found in the LICENSE file. // Package plugin defines the plugin implementations that the main pprof driver requires.package plugin import ( "bufio" "fmt" "os" "regexp" "strings" "time" "cmd/pprof/internal/profile") // A FlagSet creates and parses command-line flags.// It is similar to the standard flag.FlagSet.type FlagSet interface { // Bool, Int, Float64, and String define new flags, // like the functions of the same name in package flag. Bool(name string, def bool, usage string) *bool Int(name string, def int, usage string) *int Float64(name string, def float64, usage string) *float64 String(name string, def string, usage string) *string // ExtraUsage returns any additional text that should be // printed after the standard usage message. // The typical use of ExtraUsage is to show any custom flags // defined by the specific pprof plugins being used. ExtraUsage() string // Parse initializes the flags with their values for this run // and returns the non-flag command line arguments. // If an unknown flag is encountered or there are no arguments, // Parse should call usage and return nil. Parse(usage func()) []string} // An ObjTool inspects shared libraries and executable files.type ObjTool interface { // Open opens the named object file. // If the object is a shared library, start is the address where // it is mapped into memory in the address space being inspected. Open(file string, start uint64) (ObjFile, error) // Demangle translates a batch of symbol names from mangled // form to human-readable form. Demangle(names []string) (map[string]string, error) // Disasm disassembles the named object file, starting at // the start address and stopping at (before) the end address. Disasm(file string, start, end uint64) ([]Inst, error) // SetConfig configures the tool. // The implementation defines the meaning of the string // and can ignore it entirely. SetConfig(config string)} // NoObjTool returns a trivial implementation of the ObjTool interface.// Open returns an error indicating that the requested file does not exist.// Demangle returns an empty map and a nil error.// Disasm returns an error.// SetConfig is a no-op.func NoObjTool() ObjTool { return noObjTool{}} type noObjTool struct{} func (noObjTool) Open(file string, start uint64) (ObjFile, error) { return nil, &os.PathError{Op: "open", Path: file, Err: os.ErrNotExist}} func (noObjTool) Demangle(name []string) (map[string]string, error) { return make(map[string]string), nil} func (noObjTool) Disasm(file string, start, end uint64) ([]Inst, error) { return nil, fmt.Errorf("disassembly not supported")} func (noObjTool) SetConfig(config string) {} // An ObjFile is a single object file: a shared library or executable.type ObjFile interface { // Name returns the underlyinf file name, if available Name() string // Base returns the base address to use when looking up symbols in the file. Base() uint64 // BuildID returns the GNU build ID of the file, or an empty string. BuildID() string // SourceLine reports the source line information for a given // address in the file. Due to inlining, the source line information // is in general a list of positions representing a call stack, // with the leaf function first. SourceLine(addr uint64) ([]Frame, error) // Symbols returns a list of symbols in the object file. // If r is not nil, Symbols restricts the list to symbols // with names matching the regular expression. // If addr is not zero, Symbols restricts the list to symbols // containing that address. Symbols(r *regexp.Regexp, addr uint64) ([]*Sym, error) // Close closes the file, releasing associated resources. Close() error} // A Frame describes a single line in a source file.type Frame struct { Func string // name of function File string // source file name Line int // line in file} // A Sym describes a single symbol in an object file.type Sym struct { Name []string // names of symbol (many if symbol was dedup'ed) File string // object file containing symbol Start uint64 // start virtual address End uint64 // virtual address of last byte in sym (Start+size-1)} // An Inst is a single instruction in an assembly listing.type Inst struct { Addr uint64 // virtual address of instruction Text string // instruction text File string // source file Line int // source line} // A UI manages user interactions.type UI interface { // Read returns a line of text (a command) read from the user. ReadLine() (string, error) // Print shows a message to the user. // It formats the text as fmt.Print would and adds a final \n if not already present. // For line-based UI, Print writes to standard error. // (Standard output is reserved for report data.) Print(...interface{}) // PrintErr shows an error message to the user. // It formats the text as fmt.Print would and adds a final \n if not already present. // For line-based UI, PrintErr writes to standard error. PrintErr(...interface{}) // IsTerminal returns whether the UI is known to be tied to an // interactive terminal (as opposed to being redirected to a file). IsTerminal() bool // SetAutoComplete instructs the UI to call complete(cmd) to obtain // the auto-completion of cmd, if the UI supports auto-completion at all. SetAutoComplete(complete func(string) string)} // StandardUI returns a UI that reads from standard input,// prints messages to standard output,// prints errors to standard error, and doesn't use auto-completion.func StandardUI() UI { return &stdUI{r: bufio.NewReader(os.Stdin)}} type stdUI struct { r *bufio.Reader} func (ui *stdUI) ReadLine() (string, error) { os.Stdout.WriteString("(pprof) ") return ui.r.ReadString('\n')} func (ui *stdUI) Print(args ...interface{}) { ui.fprint(os.Stderr, args)} func (ui *stdUI) PrintErr(args ...interface{}) { ui.fprint(os.Stderr, args)} func (ui *stdUI) IsTerminal() bool { return false} func (ui *stdUI) SetAutoComplete(func(string) string) {} func (ui *stdUI) fprint(f *os.File, args []interface{}) { text := fmt.Sprint(args...) if !strings.HasSuffix(text, "\n") { text += "\n" } f.WriteString(text)} // A Fetcher reads and returns the profile named by src.// It gives up after the given timeout, unless src contains a timeout override// (as defined by the implementation).// It can print messages to ui.type Fetcher func(src string, timeout time.Duration, ui UI) (*profile.Profile, error) // A Symbolizer annotates a profile with symbol information.// The profile was fetch from src.// The meaning of mode is defined by the implementation.type Symbolizer func(mode, src string, prof *profile.Profile, obj ObjTool, ui UI) error
// Copyright 2014 The Go Authors. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
// Package plugin defines the plugin implementations that the main pprof driver requires.
package plugin
import (
"bufio"
"fmt"
"os"
"regexp"
"strings"
"time"
"cmd/pprof/internal/profile"
)
// A FlagSet creates and parses command-line flags.
// It is similar to the standard flag.FlagSet.
type FlagSet interface {
// Bool, Int, Float64, and String define new flags,
// like the functions of the same name in package flag.
Bool(name string, def bool, usage string) *bool
Int(name string, def int, usage string) *int
Float64(name string, def float64, usage string) *float64
String(name string, def string, usage string) *string
// ExtraUsage returns any additional text that should be
// printed after the standard usage message.
// The typical use of ExtraUsage is to show any custom flags
// defined by the specific pprof plugins being used.
ExtraUsage() string
// Parse initializes the flags with their values for this run
// and returns the non-flag command line arguments.
// If an unknown flag is encountered or there are no arguments,
// Parse should call usage and return nil.
Parse(usage func()) []string
}
// An ObjTool inspects shared libraries and executable files.
type ObjTool interface {
// Open opens the named object file.
// If the object is a shared library, start is the address where
// it is mapped into memory in the address space being inspected.
Open(file string, start uint64) (ObjFile, error)
// Demangle translates a batch of symbol names from mangled
// form to human-readable form.
Demangle(names []string) (map[string]string, error)
// Disasm disassembles the named object file, starting at
// the start address and stopping at (before) the end address.
Disasm(file string, start, end uint64) ([]Inst, error)
// SetConfig configures the tool.
// The implementation defines the meaning of the string
// and can ignore it entirely.
SetConfig(config string)
}
// NoObjTool returns a trivial implementation of the ObjTool interface.
// Open returns an error indicating that the requested file does not exist.
// Demangle returns an empty map and a nil error.
// Disasm returns an error.
// SetConfig is a no-op.
func NoObjTool() ObjTool {
return noObjTool{}
}
type noObjTool struct{}
func (noObjTool) Open(file string, start uint64) (ObjFile, error) {
return nil, &os.PathError{Op: "open", Path: file, Err: os.ErrNotExist}
}
func (noObjTool) Demangle(name []string) (map[string]string, error) {
return make(map[string]string), nil
}
func (noObjTool) Disasm(file string, start, end uint64) ([]Inst, error) {
return nil, fmt.Errorf("disassembly not supported")
}
func (noObjTool) SetConfig(config string) {
}
// An ObjFile is a single object file: a shared library or executable.
type ObjFile interface {
// Name returns the underlyinf file name, if available
Name() string
// Base returns the base address to use when looking up symbols in the file.
Base() uint64
// BuildID returns the GNU build ID of the file, or an empty string.
BuildID() string
// SourceLine reports the source line information for a given
// address in the file. Due to inlining, the source line information
// is in general a list of positions representing a call stack,
// with the leaf function first.
SourceLine(addr uint64) ([]Frame, error)
// Symbols returns a list of symbols in the object file.
// If r is not nil, Symbols restricts the list to symbols
// with names matching the regular expression.
// If addr is not zero, Symbols restricts the list to symbols
// containing that address.
Symbols(r *regexp.Regexp, addr uint64) ([]*Sym, error)
// Close closes the file, releasing associated resources.
Close() error
}
// A Frame describes a single line in a source file.
type Frame struct {
Func string // name of function
File string // source file name
Line int // line in file
}
// A Sym describes a single symbol in an object file.
type Sym struct {
Name []string // names of symbol (many if symbol was dedup'ed)
File string // object file containing symbol
Start uint64 // start virtual address
End uint64 // virtual address of last byte in sym (Start+size-1)
}
// An Inst is a single instruction in an assembly listing.
type Inst struct {
Addr uint64 // virtual address of instruction
Text string // instruction text
File string // source file
Line int // source line
}
// A UI manages user interactions.
type UI interface {
// Read returns a line of text (a command) read from the user.
ReadLine() (string, error)
// Print shows a message to the user.
// It formats the text as fmt.Print would and adds a final \n if not already present.
// For line-based UI, Print writes to standard error.
// (Standard output is reserved for report data.)
Print(...interface{})
// PrintErr shows an error message to the user.
// It formats the text as fmt.Print would and adds a final \n if not already present.
// For line-based UI, PrintErr writes to standard error.
PrintErr(...interface{})
// IsTerminal returns whether the UI is known to be tied to an
// interactive terminal (as opposed to being redirected to a file).
IsTerminal() bool
// SetAutoComplete instructs the UI to call complete(cmd) to obtain
// the auto-completion of cmd, if the UI supports auto-completion at all.
SetAutoComplete(complete func(string) string)
}
// StandardUI returns a UI that reads from standard input,
// prints messages to standard output,
// prints errors to standard error, and doesn't use auto-completion.
func StandardUI() UI {
return &stdUI{r: bufio.NewReader(os.Stdin)}
}
type stdUI struct {
r *bufio.Reader
}
func (ui *stdUI) ReadLine() (string, error) {
os.Stdout.WriteString("(pprof) ")
return ui.r.ReadString('\n')
}
func (ui *stdUI) Print(args ...interface{}) {
ui.fprint(os.Stderr, args)
}
func (ui *stdUI) PrintErr(args ...interface{}) {
ui.fprint(os.Stderr, args)
}
func (ui *stdUI) IsTerminal() bool {
return false
}
func (ui *stdUI) SetAutoComplete(func(string) string) {
}
func (ui *stdUI) fprint(f *os.File, args []interface{}) {
text := fmt.Sprint(args...)
if !strings.HasSuffix(text, "\n") {
text += "\n"
}
f.WriteString(text)
}
// A Fetcher reads and returns the profile named by src.
// It gives up after the given timeout, unless src contains a timeout override
// (as defined by the implementation).
// It can print messages to ui.
type Fetcher func(src string, timeout time.Duration, ui UI) (*profile.Profile, error)
// A Symbolizer annotates a profile with symbol information.
// The profile was fetch from src.
// The meaning of mode is defined by the implementation.
type Symbolizer func(mode, src string, prof *profile.Profile, obj ObjTool, ui UI) error