src

package standard library
go1.23.4 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 3, 2024 License: BSD-3-Clause Imports: 3 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// It is expected that the front end or a phase in SSA will usually generate positions tagged with
	// PosDefaultStmt, but note statement boundaries with PosIsStmt.  Simple statements will have a single
	// boundary; for loops with initialization may have one for their entry and one for their back edge
	// (this depends on exactly how the loop is compiled; the intent is to provide a good experience to a
	// user debugging a program; the goal is that a breakpoint set on the loop line fires both on entry
	// and on iteration).  Proper treatment of non-gofmt input with multiple simple statements on a single
	// line is TBD.
	//
	// Optimizing compilation will move instructions around, and some of these will become known-bad as
	// step targets for debugging purposes (examples: register spills and reloads; code generated into
	// the entry block; invariant code hoisted out of loops) but those instructions will still have interesting
	// positions for profiling purposes. To reflect this these positions will be changed to PosNotStmt.
	//
	// When the optimizer removes an instruction marked PosIsStmt; it should attempt to find a nearby
	// instruction with the same line marked PosDefaultStmt to be the new statement boundary.  I.e., the
	// optimizer should make a best-effort to conserve statement boundary positions, and might be enhanced
	// to note when a statement boundary is not conserved.
	//
	// Code cloning, e.g. loop unrolling or loop unswitching, is an exception to the conservation rule
	// because a user running a debugger would expect to see breakpoints active in the copies of the code.
	//
	// In non-optimizing compilation there is still a role for PosNotStmt because of code generation
	// into the entry block.  PosIsStmt statement positions should be conserved.
	//
	// When code generation occurs any remaining default-marked positions are replaced with not-statement
	// positions.
	//
	PosDefaultStmt uint = iota // Default; position is not a statement boundary, but might be if optimization removes the designated statement boundary
	PosIsStmt                  // Position is a statement boundary; if optimization removes the corresponding instruction, it should attempt to find a new instruction to be the boundary.
	PosNotStmt                 // Position should not be a statement boundary, but line should be preserved for profiling and low-level debugging purposes.
)
View Source 
const FileSymPrefix = "gofile.."

FileSymPrefix is the linker symbol prefix that used to be used for linker pseudo-symbols representing file names.

Variables

This section is empty.

Functions

This section is empty.

Types

type Pos 

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

A Pos encodes a source position consisting of a (line, column) number pair and a position base. A zero Pos is a ready to use "unknown" position (nil position base and zero line number).

The (line, column) values refer to a position in a file independent of any position base ("absolute" file position).

The position base is used to determine the "relative" position, that is the filename and line number relative to the position base. If the base refers to the current file, there is no difference between absolute and relative positions. If it refers to a //line directive, a relative position is relative to that directive. A position base in turn contains the position at which it was introduced in the current file. 

var NoPos Pos

NoPos is a valid unknown position.

func MakePos 

func MakePos(base *PosBase, line, col uint) Pos

MakePos creates a new Pos value with the given base, and (file-absolute) line and column.

func (Pos) AbsFilename 

func (p Pos) AbsFilename() string

AbsFilename() returns the absolute filename recorded with the position's base.

func (Pos) After 

func (p Pos) After(q Pos) bool

After reports whether the position p comes after q in the source. For positions in different files, ordering is by filename.

func (Pos) Base 

func (p Pos) Base() *PosBase

Base returns the position base.

func (Pos) Before 

func (p Pos) Before(q Pos) bool

Before reports whether the position p comes before q in the source. For positions in different files, ordering is by filename.

func (Pos) Col 

func (x Pos) Col() uint

func (Pos) FileIndex added in go1.22.0 

func (p Pos) FileIndex() int

FileIndex returns the file index of the position's base's absolute filename within the PosTable that it was registered.

func (Pos) Filename 

func (p Pos) Filename() string

Filename returns the name of the actual file containing this position.

func (Pos) Format 

func (p Pos) Format(showCol, showOrig bool) string

Format formats a position as "filename:line" or "filename:line:column", controlled by the showCol flag and if the column is known (!= 0). For positions relative to line directives, the original position is shown as well, as in "filename:line[origfile:origline:origcolumn] if showOrig is set.

func (Pos) IsKnown 

func (p Pos) IsKnown() bool

IsKnown reports whether the position p is known. A position is known if it either has a non-nil position base, or a non-zero line number.

func (Pos) IsStmt added in go1.11 

func (x Pos) IsStmt() uint

func (Pos) Line 

func (x Pos) Line() uint

func (Pos) LineNumber added in go1.11 

func (p Pos) LineNumber() string

func (Pos) LineNumberHTML added in go1.11 

func (p Pos) LineNumberHTML() string

func (Pos) RelCol added in go1.11 

func (p Pos) RelCol() uint

RelCol returns the column number relative to the position's base.

func (Pos) RelFilename 

func (p Pos) RelFilename() string

RelFilename returns the filename recorded with the position's base.

func (Pos) RelLine 

func (p Pos) RelLine() uint

RelLine returns the line number relative to the position's base.

func (Pos) SameLine added in go1.14 

func (x Pos) SameLine(y lico) bool

func (*Pos) SetBase 

func (p *Pos) SetBase(base *PosBase)

SetBase sets the position base.

func (Pos) String 

func (p Pos) String() string

func (Pos) WriteTo added in go1.15 

func (p Pos) WriteTo(w io.Writer, showCol, showOrig bool)

WriteTo a position to w, formatted as Format does.

func (Pos) Xlogue added in go1.11 

func (x Pos) Xlogue() PosXlogue

type PosBase 

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

A PosBase encodes a filename and base position. Typically, each file and line directive introduce a PosBase.

func NewFileBase 

func NewFileBase(filename, absFilename string) *PosBase

NewFileBase returns a new *PosBase for a file with the given (relative and absolute) filenames.

func NewInliningBase 

func NewInliningBase(orig *PosBase, inlTreeIndex int) *PosBase

NewInliningBase returns a copy of the orig PosBase with the given inlining index. If orig == nil, NewInliningBase panics.

func NewLinePragmaBase 

func NewLinePragmaBase(pos Pos, filename, absFilename string, line, col uint) *PosBase

NewLinePragmaBase returns a new *PosBase for a line directive of the form 

//line filename:line:col
/*line filename:line:col*/

at position pos.

func (*PosBase) AbsFilename 

func (b *PosBase) AbsFilename() string

AbsFilename returns the absolute filename recorded with the base. If b == nil, the result is the empty string.

func (*PosBase) Col added in go1.11 

func (b *PosBase) Col() uint

Col returns the column number recorded with the base. If b == nil, the result is 0.

func (*PosBase) FileIndex added in go1.22.0 

func (b *PosBase) FileIndex() int

FileIndex returns the index of the base's absolute filename within its PosTable's FileTable. It panics if it hasn't been registered with a PosTable. If b == nil, the result is -1.

func (*PosBase) Filename 

func (b *PosBase) Filename() string

Filename returns the filename recorded with the base. If b == nil, the result is the empty string.

func (*PosBase) InliningIndex 

func (b *PosBase) InliningIndex() int

InliningIndex returns the index into the global inlining tree recorded with the base. If b == nil or the base has not been inlined, the result is < 0.

func (*PosBase) Line 

func (b *PosBase) Line() uint

Line returns the line number recorded with the base. If b == nil, the result is 0.

func (*PosBase) Pos 

func (b *PosBase) Pos() *Pos

Pos returns the position at which base is located. If b == nil, the result is the zero position.

type PosTable 

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

A PosTable tracks Pos -> XPos conversions and vice versa. Its zero value is a ready-to-use PosTable.

func (*PosTable) FileTable added in go1.16 

func (t *PosTable) FileTable() []string

FileTable returns a slice of all files used to build this package.

func (*PosTable) Pos 

func (t *PosTable) Pos(p XPos) Pos

Pos returns the corresponding Pos for the given p. If p cannot be translated via t, the function panics.

func (*PosTable) XPos 

func (t *PosTable) XPos(pos Pos) XPos

XPos returns the corresponding XPos for the given pos, adding pos to t if necessary.

type PosXlogue added in go1.11 

type PosXlogue uint
const (
	PosDefaultLogue PosXlogue = iota
	PosPrologueEnd
	PosEpilogueBegin
)

type XPos 

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

XPos is a more compact representation of Pos. 

var NoXPos XPos

NoXPos is a valid unknown position.

func (XPos) After 

func (p XPos) After(q XPos) bool

After reports whether the position p comes after q in the source. For positions with different bases, ordering is by base index.

func (XPos) AtColumn1 added in go1.13 

func (p XPos) AtColumn1() XPos

AtColumn1 returns the same location but shifted to column 1.

func (XPos) Before 

func (p XPos) Before(q XPos) bool

Before reports whether the position p comes before q in the source. For positions with different bases, ordering is by base index.

func (XPos) Col 

func (x XPos) Col() uint

func (XPos) FileIndex added in go1.13 

func (p XPos) FileIndex() int32

FileIndex returns a smallish non-negative integer corresponding to the file for this source position. Smallish is relative; it can be thousands large, but not millions.

func (XPos) IsKnown 

func (p XPos) IsKnown() bool

IsKnown reports whether the position p is known. XPos.IsKnown() matches Pos.IsKnown() for corresponding positions.

func (XPos) IsStmt added in go1.11 

func (x XPos) IsStmt() uint

func (XPos) Line 

func (x XPos) Line() uint

func (XPos) LineNumber added in go1.11 

func (p XPos) LineNumber() string

LineNumber returns a string for the line number, "?" if it is not known.

func (XPos) LineNumberHTML added in go1.11 

func (p XPos) LineNumberHTML() string

func (XPos) SameFile added in go1.11 

func (p XPos) SameFile(q XPos) bool

SameFile reports whether p and q are positions in the same file.

func (XPos) SameFileAndLine added in go1.14 

func (p XPos) SameFileAndLine(q XPos) bool

SameFileAndLine reports whether p and q are positions on the same line in the same file.

func (XPos) SameLine added in go1.14 

func (x XPos) SameLine(y lico) bool

func (XPos) WithBogusLine added in go1.13 

func (p XPos) WithBogusLine() XPos

WithBogusLine returns a bogus line that won't match any recorded for the source code. Its use is to disrupt the statements within an infinite loop so that the debugger will not itself loop infinitely waiting for the line number to change. gdb chooses not to display the bogus line; delve shows it with a complaint, but the alternative behavior is to hang.

func (XPos) WithDefaultStmt added in go1.11 

func (p XPos) WithDefaultStmt() XPos

WithDefaultStmt returns the same location with undetermined is_stmt

func (XPos) WithIsStmt added in go1.11 

func (p XPos) WithIsStmt() XPos

WithIsStmt returns the same location to be marked with DWARF is_stmt=1

func (XPos) WithNotStmt added in go1.11 

func (p XPos) WithNotStmt() XPos

WithNotStmt returns the same location to be marked with DWARF is_stmt=0

func (XPos) WithXlogue added in go1.11 

func (p XPos) WithXlogue(x PosXlogue) XPos

WithXlogue returns the same location but marked with DWARF function prologue/epilogue

func (XPos) Xlogue added in go1.11 

func (x XPos) Xlogue() PosXlogue

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.