debugger

package
v2.0.0-alpha.36 Latest Latest
Warning

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

 Go to latest Published: Jul 24, 2026 License: Apache-2.0 Imports: 20 Imported by: 0

Documentation

Overview

Package debugger implements source-level debugger policy and orchestration over a retained VM execution.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Breakpoint 

type Breakpoint struct {
	File            string
	RequestedLine   int
	RequestedColumn int
	ID              BreakpointID
	PointID         bytecode.DebugPointID
	FunctionID      int
	Line            int
	Column          int
	BindingMode     BreakpointBindingMode
	Bound           bool
}

Breakpoint describes a requested source-location breakpoint and its resolved executable location, when one exists.

type BreakpointBindingMode 

type BreakpointBindingMode int

BreakpointBindingMode selects how a requested source location resolves to an executable debug point. 

const (
	// BreakpointBindNextExecutableInFile preserves the friendly legacy binding
	// behavior and is the zero-value default.
	BreakpointBindNextExecutableInFile BreakpointBindingMode = iota
	BreakpointBindExact
	BreakpointBindNextExecutableInFunction
)

type BreakpointID 

type BreakpointID int

BreakpointID identifies a breakpoint within one debugger session.

type BreakpointOptions 

type BreakpointOptions struct {
	BindingMode BreakpointBindingMode
}

BreakpointOptions configures how a requested source location binds.

type Config 

type Config struct {
	Execution   vm.DebugExecution
	Values      vm.DebugValueAccess
	Services    SessionServices
	Source      *source.Source
	DebugPoints []bytecode.DebugPoint
	Params      []string
	Format      FormatOptions
}

Config contains the dependencies for an advanced debugger session.

type Event 

type Event struct {
	Error            error
	Output           *encoding.Output
	Reason           Reason
	HitBreakpointIDs []BreakpointID
	Location         Location
	Depth            int
}

Event reports a debugger stop, completion, or termination.

type FormatOptions 

type FormatOptions struct {
	MaxDepth int
	MaxItems int
	MaxBytes int
}

FormatOptions bounds debugger value traversal and rendered output.

func DefaultFormatOptions 

func DefaultFormatOptions() FormatOptions

DefaultFormatOptions returns conservative debugger formatting limits.

type Frame 

type Frame struct {
	Name       string
	Location   Location
	FunctionID int
}

Frame describes the paused top frame or one of its callers.

type Location 

type Location struct {
	File   string
	Line   int
	Column int
	Span   source.Span
}

Location identifies a source location in the debugged file.

type Reason 

type Reason string

Reason identifies why a debug execution stopped. 

const (
	ReasonEntry        Reason = "entry"
	ReasonBreakpoint   Reason = "breakpoint"
	ReasonStep         Reason = "step"
	ReasonPause        Reason = "pause"
	ReasonRuntimeError Reason = "runtime-error"
	ReasonCompleted    Reason = "completed"
	ReasonTerminated   Reason = "terminated"
)

type Session 

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

Session controls one retained-state source-level debug execution. Command calls are serialized. Pause is safe to call concurrently with a running command.

func NewSession 

func NewSession(config Config) (*Session, error)

NewSession creates an advanced debugger session from explicit dependencies.

func (*Session) Breakpoints 

func (s *Session) Breakpoints() []Breakpoint

Breakpoints returns a stable ID-ordered snapshot.

func (*Session) Close 

func (s *Session) Close() error

Close requests termination, then releases retained VM state and embedding-owned session resources after any active command exits.

func (*Session) Continue 

func (s *Session) Continue(ctx context.Context) (*Event, error)

Continue resumes execution until a breakpoint, pause request, error, or completion.

func (*Session) DeleteBreakpoint 

func (s *Session) DeleteBreakpoint(id BreakpointID) error

DeleteBreakpoint removes a breakpoint by ID.

func (*Session) Evaluate 

func (s *Session) Evaluate(ctx context.Context, expression string) (Value, error)

Evaluate evaluates a conservative, side-effect-free expression against the paused top frame. It supports literals, locals, parameters, supported member reads, scalar arithmetic/comparisons, boolean logic, and conditionals. It rejects calls, queries, mutation, async/event behavior, and full collection execution.

func (*Session) Frames 

func (s *Session) Frames() ([]Frame, error)

Frames returns the current frame followed by callers.

func (*Session) Locals 

func (s *Session) Locals() ([]Variable, error)

Locals returns the visible top-frame locals followed by bound parameters.

func (*Session) Next 

func (s *Session) Next(ctx context.Context) (*Event, error)

Next stops at the next logical source location at the same or shallower call depth.

func (*Session) Out 

func (s *Session) Out(ctx context.Context) (*Event, error)

Out stops at the next logical source location in a caller. At main it runs to completion.

func (*Session) Pause 

func (s *Session) Pause() error

Pause requests a stop at the next logical source location.

func (*Session) SetBreakpoint 

func (s *Session) SetBreakpoint(file string, line int) (Breakpoint, error)

SetBreakpoint adds a source-line breakpoint using the legacy friendly next-executable-in-file binding policy.

func (*Session) SetBreakpointAt 

func (s *Session) SetBreakpointAt(location SourceLocation, opts BreakpointOptions) (Breakpoint, error)

SetBreakpointAt adds a breakpoint at an explicit source location.

func (*Session) Start 

func (s *Session) Start(ctx context.Context) (*Event, error)

Start begins execution and stops at the first executable source location.

func (*Session) Step 

func (s *Session) Step(ctx context.Context) (*Event, error)

Step stops at the next logical source location, including inside calls.

func (*Session) Variables 

func (s *Session) Variables(reference ValueReference) ([]Variable, error)

Variables returns the child variables for one expandable debugger value from the current paused state.

type SessionServices 

type SessionServices interface {
	BeforeRun(context.Context) (context.Context, error)
	AfterRun(context.Context, error) error
	ExtendContext(context.Context) context.Context
	Materialize(*vm.Result) (*encoding.Output, error)
	Close() error
}

SessionServices supplies embedding-owned lifecycle and output behavior.

type SourceLocation 

type SourceLocation struct {
	File   string
	Line   int
	Column int
}

SourceLocation identifies a requested location in debugger source. Line and Column are 1-based; Column 0 means no column was requested.

type StateError 

type StateError struct {
	Operation string
	State     string
}

StateError reports a debugger command that is invalid for the current session state.

func (*StateError) Error 

func (e *StateError) Error() string

func (*StateError) Is 

func (e *StateError) Is(target error) bool

func (*StateError) Unwrap 

func (e *StateError) Unwrap() error

type Value 

type Value struct {
	Type      string
	Display   string
	Reference ValueReference
}

Value is a safely formatted debugger value.

type ValueReference 

type ValueReference int

ValueReference identifies an expandable debugger value within one paused session state. References are invalidated when execution starts or resumes.

func (ValueReference) Valid 

func (r ValueReference) Valid() bool

Valid reports whether the reference can be used to request child variables.

type Variable 

type Variable struct {
	Name    string
	Value   Value
	Mutable bool
	Param   bool
}

Variable describes a visible local or bind parameter.

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.