Documentation
¶
Overview ¶
Package debugger defines portable contracts and values for controlling and inspecting Ferret debug sessions, including events, breakpoints, frames, and values.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Breakpoint ¶
type Breakpoint struct {
Location source.Range `json:"location"`
RequestedLocation source.Location `json:"requestedLocation"`
ID BreakpointID `json:"id"`
PointID PointID `json:"pointID"`
FunctionID FunctionID `json:"functionID"`
BindingMode BreakpointBindingMode `json:"bindingMode"`
Bound bool `json:"bound"`
}
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 ( // BreakpointBindNextExecutableInSource selects the next executable point in // the named source and is the zero-value default. BreakpointBindNextExecutableInSource BreakpointBindingMode = iota BreakpointBindExact BreakpointBindNextExecutableInFunction )
func BreakpointBindingModeFromString ¶
func BreakpointBindingModeFromString(s string) BreakpointBindingMode
type BreakpointID ¶
type BreakpointID int
BreakpointID identifies a breakpoint within one debugger session.
type BreakpointOptions ¶
type BreakpointOptions struct {
BindingMode BreakpointBindingMode `json:"bindingMode"`
}
BreakpointOptions configures how a requested source location binds.
type BreakpointRequest ¶
type BreakpointRequest struct {
Position source.Position `json:"position"`
Options BreakpointOptions `json:"options"`
}
BreakpointRequest specifies one position and its binding policy within a source-wide replacement. Source identity belongs to ReplaceBreakpoints.
type Event ¶
type Event struct {
Error error `json:"error"`
Output *result.Output `json:"output"`
Reason Reason `json:"reason"`
HitBreakpointIDs []BreakpointID `json:"hitBreakpointIDs"`
Location source.Range `json:"location"`
Depth int `json:"depth"`
}
Event reports a debugger stop, completion, or termination.
type Frame ¶
type Frame struct {
Name string `json:"name"`
Location source.Location `json:"location"`
FunctionID FunctionID `json:"functionID"`
}
Frame describes the paused top frame or one of its callers.
type FunctionID ¶
type FunctionID int
FunctionID identifies a callable function within one compiled program.
const NoFunction FunctionID = -1
NoFunction identifies the top-level program body rather than a callable function.
type Reason ¶
type Reason string
Reason identifies why a debug execution stopped.
func ReasonFromString ¶
type Session ¶
type Session interface {
io.Closer
Start(ctx context.Context) (*Event, error)
Continue(ctx context.Context) (*Event, error)
StepIn(ctx context.Context) (*Event, error)
StepOver(ctx context.Context) (*Event, error)
StepOut(ctx context.Context) (*Event, error)
Pause(ctx context.Context) error
// ReplaceBreakpoints atomically replaces one source's complete requested set,
// before execution, while paused, or while running. Empty requests clear it;
// an empty sourceName selects the launched source. Other sources are unchanged.
// Results follow request order. Invalid positions or binding modes fail the
// operation without publication; valid but unresolved locations return Bound=false.
//
// Unchanged requests retain IDs; duplicates match in ascending ID order.
// Removed IDs are never reused in the session.
// A hit already decided against an older set retains its IDs and remains an
// inspectable stop. Additions affect subsequent visits, never past instructions.
//
// Cancellation observed before publication leaves the previous set intact.
// After publication the operation returns success even if cancellation follows.
// Session terminal commitment and publication are ordered: publication first
// succeeds; completion, termination, or Close first rejects replacement.
// Concurrent writers are serialized in admission order. Callers requiring
// request order must await each result before issuing the next replacement.
ReplaceBreakpoints(ctx context.Context, sourceName string, requests []BreakpointRequest) ([]Breakpoint, error)
SetBreakpoint(ctx context.Context, pos source.Location) (Breakpoint, error)
SetBreakpointAt(ctx context.Context, loc source.Location, opts BreakpointOptions) (Breakpoint, error)
DeleteBreakpoint(ctx context.Context, id BreakpointID) error
Breakpoints(ctx context.Context) []Breakpoint
Frames(ctx context.Context) ([]Frame, error)
Locals(ctx context.Context) ([]Variable, error)
FrameLocals(ctx context.Context, frame int) ([]Variable, error)
Variables(ctx context.Context, reference ValueReference) ([]Variable, error)
Evaluate(ctx context.Context, expression string) (Value, error)
EvaluateFrame(ctx context.Context, frame int, expression string) (Value, error)
}
Session controls one retained execution. Start establishes its lifetime; resume commands observe both that lifetime and their non-nil caller context. Execution and inspection commands are serialized. Breakpoint operations may run concurrently with execution. Pause and Close may interrupt an active command. Close terminates execution, waits for commands, and releases resources; repeated closes retain the cleanup result without requiring identical error-wrapper pointers. Inspection references expire on resume. A command can return an event and an error, including available completion output when subsequent cleanup fails. Context arguments must be non-nil.
type Value ¶
type Value struct {
Type string `json:"type"`
Display string `json:"display"`
Reference ValueReference `json:"reference"`
}
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 has a valid portable encoding. It does not check whether it belongs to the current paused state.
Source Files