Documentation
¶
Overview ¶
Package debugger defines portable contracts and values for controlling and inspecting Ferret debug sessions, including events, breakpoints, frames, and values. Retained event output is detached result.Content, preserving absent versus present empty data and remaining readable without consuming another observer's output or retaining a live result.Output handle.
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 is detached encoded content, not a live consumable handle.
// Nil means absent; a non-nil pointer means present, including empty data.
// Retained snapshots must remain valid after debugger cleanup and must
// not share mutable implementation buffers. Recipients coordinate any
// mutation of shared Content themselves.
Output *result.Content `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. Retained data is materialized; reading an event does not consume another observer's output. Available completion content may accompany an error.
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 returns a detached, ID-ordered snapshot, including after Close.
// Nil or canceled contexts return an error.
Breakpoints(ctx context.Context) ([]Breakpoint, error)
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 content when subsequent cleanup fails. Event.Output holds detached materialized Content that remains readable after cleanup; inspecting a retained event never consumes a live output handle. Context arguments must be non-nil. Inspection checks cancellation before and after command admission; cancellation need not interrupt the admission wait. A canceled Pause must not request a stop. Breakpoint mutations observe their request context through publication; canceling a request does not cancel the execution. Cancellation observed before publication aborts the mutation; cancellation after publication does not undo success.
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