cdebug

type AllState struct {

	// mode we're running in
	Mode Modes

	// overall debugger status
	Status Status

	// current run state
	State State

	// id of the current system thread to examine
	CurThread int

	// id of the current task to examine
	CurTask int

	// frame number within current thread
	CurFrame int

	// current breakpoint that we stopped at -- will be 0 if none, after UpdateState
	CurBreak int

	// all breakpoints that have been set -- some may not be On
	Breaks []*Break

	// current, active breakpoints as retrieved from debugger
	CurBreaks []*Break

	// all system threads
	Threads []*Thread

	// all tasks
	Tasks []*Task

	// current stack frame for current thread / task
	Stack []*Frame

	// current local variables and args for current frame
	Vars []*Variable

	// global variables for current thread / task
	GlobalVars []*Variable

	// current find-frames result
	FindFrames []*Frame
}

type Break struct {

	// unique numerical ID of the breakpoint
	ID int `edit:"-"`

	// whether the breakpoint is currently enabled
	On bool `width:"4"`

	// program counter (address) -- may be subset of multiple
	PC uint64 `edit:"-" format:"%#X"`

	// file name (trimmed up to point of project base path)
	File string `edit:"-"`

	// line within file
	Line int `edit:"-"`

	// full path to file
	FPath string `edit:"-" view:"-" tableview:"-"`

	// the name of the function
	Func string `edit:"-" width:"80"`

	// condition for conditional breakbpoint
	Cond string

	// if true, execution does not stop -- just a message is reported when this point is hit
	Trace bool `width:"7"`
}

type Frame struct {

	// depth in overall stack -- 0 is the bottom (currently executing) frame, and it counts up from there
	Depth int

	// the Task or Thread id that this frame belongs to
	ThreadID int

	// program counter (address) -- may be subset of multiple
	PC uint64 `format:"%#X"`

	// file name (trimmed up to point of project base path)
	File string

	// line within file
	Line int

	// full path to file
	FPath string `tableview:"-" tableview:"-"`

	// the name of the function
	Func string `width:"80"`

	// values of the local variables at this frame
	Vars []*Variable `tableview:"-"`

	// values of the local function args at this frame
	Args []*Variable `tableview:"-"`
}

type GiDebug interface {

	// HasTasks returns true if the debugger supports a level of threading
	// below the system thread level.  If true, then use Task data
	// otherwise, use Threads
	HasTasks() bool

	// Start starts the debugger for a given exe path, and overall project
	// root path (for trimming file names), and sets output of debugger
	// session to given textbuf which is used to monitor output.
	// params must have relevant settings in place (StatFunc, Mode, etc).
	Start(path, rootPath string, outbuf *texteditor.Buffer, pars *Params) error

	// SetParams sets the current parameters to control how info is returned
	SetParams(params *Params)

	// IsActive returns true if the debugger is active and ready for commands
	IsActive() bool

	// Returns the pid of the process we are debugging.
	ProcessPid() int

	// LastModified returns the time that the process' executable was modified.
	LastModified() time.Time

	// Detach detaches the debugger, optionally killing the process.
	Detach(killProcess bool) error

	// Disconnect closes the connection to the server without
	// sending a Detach request first.  If cont is true a continue
	// command will be sent instead.
	Disconnect(cont bool) error

	// Restarts program.
	Restart() error

	// GetState returns the current debugger state.
	// This will return immediately -- if the target is running then
	// the Running flag will be set and a Stop bus be called to
	// get any further information about the target.
	GetState() (*State, error)

	// Continue resumes process execution.  The channel will block until the
	// process stops by any means.  Tracepoints are automatically handled by
	// the debugger, and do not appear.  Typically there is just one State
	// in the channel, but perhaps there could be more -- use a range to iterate
	// over all items in the channel -- it will close after data is sent.
	// The last state can be used for further updating.
	Continue(all *AllState) <-chan *State

	// StepOver continues to the next source line, not entering function calls.
	StepOver() (*State, error)

	// StepInto continues to the next source line, entering function calls.
	StepInto() (*State, error)

	// StepOut continues to the return point of the current function
	StepOut() (*State, error)

	// StepSingle step a single cpu instruction.
	StepSingle() (*State, error)

	// SwitchThread switches the current system thread context to given one
	SwitchThread(threadID int) (*State, error)

	// SwitchTask switches the current thread to given one
	SwitchTask(threadID int) (*State, error)

	// Stop suspends the process.
	Stop() (*State, error)

	// GetBreak gets info about a breakpoint by ID.
	GetBreak(id int) (*Break, error)

	// SetBreak sets a new breakpoint at given file (must be enough to be unique)
	// and line number
	SetBreak(fname string, line int) (*Break, error)

	// ListBreaks gets all breakpoints.
	ListBreaks() ([]*Break, error)

	// ClearBreak deletes a breakpoint by ID.
	ClearBreak(id int) error

	// AmmendBreak updates the Condition and Trace information
	// for the given breakpoint
	AmendBreak(id int, fname string, line int, cond string, trace bool) error

	// UpdateBreaks updates current breakpoints based on given list of breakpoints.
	// first gets the current list, and does actions to ensure that the list is set.
	UpdateBreaks(brk *[]*Break) error

	// Cancels a Next or Step call that was interrupted by a
	// manual stop or by another breakpoint
	CancelNext() error

	// InitAllState initializes the given AllState with relevant info
	// for current debugger state.  Does NOT get AllVars.
	InitAllState(all *AllState) error

	// UpdateAllState updates the state for given threadId and
	// frame number (only info different from current results is updated).
	// For given thread (lowest-level supported by language,
	// e.g., Task if supported, else Thread), and frame number.
	UpdateAllState(all *AllState, threadID int, frame int) error

	// FindFrames looks through the Stacks of all Tasks / Threads
	// for the closest Stack Frame to given file and line number.
	// Results are sorted by line number proximity to given line.
	FindFrames(all *AllState, fname string, line int) ([]*Frame, error)

	// CurThreadID returns the proper current threadID (task or thread)
	// based on debugger, from given state.
	CurThreadID(all *AllState) int

	// ListThreads lists all system threads.
	ListThreads() ([]*Thread, error)

	// GetThread gets a thread by its ID.
	GetThread(id int) (*Thread, error)

	// ListTasks lists all the currently active threads (if supported)
	ListTasks() ([]*Task, error)

	// Stack returns the current stack, up to given depth,
	// for given thread (lowest-level supported by language,
	// e.g., Task if supported, else Thread), and frame number.
	Stack(threadID int, depth int) ([]*Frame, error)

	// ListGlobalVars lists global variables (subject to filter) in the context
	// of the current thread.
	ListGlobalVars(filter string) ([]*Variable, error)

	// ListVars lists all stack-frame local variables (including args)
	// for given thread (lowest-level supported by language,
	// e.g., Task if supported, else Thread), and frame number.
	ListVars(threadID int, frame int) ([]*Variable, error)

	// GetVar returns a variable for given thread (lowest-level supported by
	// language -- e.g., Task if supported, else Thread), and frame number,
	// from given expression, which depending on debugger can be a full
	// expression (e.g., path, address with cast, etc)
	GetVar(expr string, threadID int, frame int) (*Variable, error)

	// FollowPtr fills in the Child of given Variable
	// with retrieved value.  Uses last eval scope.
	FollowPtr(vr *Variable) error

	// SetVar sets the value of a variable.
	// for given thread (lowest-level supported by language,
	// e.g., Task if supported, else Thread), and frame number.
	SetVar(name, value string, threadID int, frame int) error

	// ListSources lists all source files in the process matching filter.
	ListSources(filter string) ([]string, error)

	// ListFuncs lists all functions in the process matching filter.
	ListFuncs(filter string) ([]string, error)

	// ListTypes lists all types in the process matching filter.
	ListTypes(filter string) ([]string, error)

	// WriteToConsole writes given message string to the debugger's output console.
	// message should end in newline
	WriteToConsole(msg string)
}

type Location struct {

	// program counter (address) -- may be subset of multiple
	PC uint64 `format:"%#X"`

	// file name (trimmed up to point of project base path)
	File string

	// line within file
	Line int

	// full path to file
	FPath string `view:"-" tableview:"-"`

	// the name of the function
	Func string `width:"80"`
}

type Modes int32

type Params struct {

	// mode for running the debugger
	Mode Modes `xml:"-" toml:"-" json:"-" view:"-"`

	// process id number to attach to, for Attach mode
	PID uint64 `xml:"-" toml:"-" json:"-" view:"-"`

	// optional extra args to pass to the debugger.
	// Use -- double-dash and then add args to pass args to the executable
	// (double-dash is by itself as a separate arg first).
	// For Debug test, must use -test.run instead of plain -run to specify tests to run.
	Args []string

	// status function for debugger updating status
	StatFunc func(stat Status) `xml:"-" toml:"-" json:"-" view:"-"`

	// parameters for level of detail on overall list of variables
	VarList VarParams

	// parameters for level of detail retrieving a specific variable
	GetVar VarParams
}

type State struct {

	// currently executing system thread
	Thread Thread

	// currently executing task
	Task Task

	// true if the process is running and no other information can be collected.
	Running bool

	// if true, a Next or Step is already in progress and another should not be attempted until after a Continue
	NextUp bool

	// if true, the program has exited
	Exited bool

	// indicates the exit status if Exited
	ExitStatus int

	// error communicated to client -- if non-empty, something bad happened
	Err error

	// if this is > 0, then we just hit that tracepoint -- the Continue process will continue execution
	CurTrace int
}

type Status int32 //enums:enum

type Task struct {

	// task identifier
	ID int

	// program counter (address) -- may be subset of multiple
	PC uint64 `format:"%#X"`

	// file name (trimmed up to point of project base path)
	File string

	// line within file
	Line int

	// full path to file
	FPath string `tableview:"-" tableview:"-"`

	// the name of the function
	Func string `width:"80"`

	// id of the current Thread this task is running on
	Thread int `format:"%#X"`

	// where did this task first start running?
	StartLoc Location `tableview:"-"`

	// at what point was this task launched from another task?
	LaunchLoc Location `tableview:"-"`
}

type Thread struct {

	// thread identifier
	ID int `format:"%#X"`

	// program counter (address) -- may be subset of multiple
	PC uint64 `format:"%#X"`

	// file name (trimmed up to point of project base path)
	File string

	// line within file
	Line int

	// full path to file
	FPath string `tableview:"-"`

	// the name of the function
	Func string `width:"80"`

	// id of the current Task within this system thread (if relevant)
	Task int
}

type VarParams struct {

	// requests pointers to be automatically dereferenced -- this can be very dangerous in terms of size of variable data returned and is not recommended.
	FollowPointers bool `default:"false"`

	// how far to recurse when evaluating nested types.
	MaxRecurse int

	// the maximum number of bytes read from a string
	MaxStringLen int

	// the maximum number of elements read from an array, a slice or a map.
	MaxArrayValues int

	// the maximum number of fields read from a struct, -1 will read all fields.
	MaxStructFields int
}

type Variable struct {
	tree.NodeBase

	// value of variable -- may be truncated if long
	Value string `inactive:"-" width:"60"`

	// type of variable as a string expression (shortened for display)
	TypeStr string `inactive:"-"`

	// type of variable as a string expression (full length)
	FullTypeStr string `view:"-" inactive:"-"`

	// kind of element
	Kind syms.Kinds `inactive:"-"`

	// own elemental value of variable (blank for composite types)
	ElValue string `inactive:"-" view:"-"`

	// length of variable (slices, maps, strings etc)
	Len int64 `inactive:"-"`

	// capacity of vaiable
	Cap int64 `inactive:"-" tableview:"-"`

	// address where variable is located in memory
	Addr uintptr `inactive:"-"`

	// if true, the variable is stored in the main memory heap, not the stack
	Heap bool `inactive:"-"`

	// location where the variable was defined in source
	Loc Location `inactive:"-" tableview:"-"`

	// if kind is a list type (array, slice), and elements are primitive types, this is the contents
	List []string `tableview:"-"`

	// if kind is a map, and elements are primitive types, this is the contents
	Map map[string]string `tableview:"-"`

	// if kind is a map, and elements are not primitive types, this is the contents
	MapVar map[string]*Variable `tableview:"-"`

	// our debugger -- for getting further variable data
	Dbg GiDebug `view:"-"`
}