View source

class Debugger

package cpp.vm

Available on cpp

This class wraps the hxcpp C++ implementation to provide a Haxe interface to the low level debugging features

Static variables

@:value("NONEXISTENT_VALUE")@:keepstaticNONEXISTENT_VALUE:String = "NONEXISTENT_VALUE"

This tagging value is returned by getStackVariableValue() and setStackVariableValue() if the requested value does not exist at the requested stack frame

@:value(1)@:keepstaticinlineread onlySTEP_INTO:Int = 1

@:value(3)@:keepstaticinlineread onlySTEP_OUT:Int = 3

@:value(2)@:keepstaticinlineread onlySTEP_OVER:Int = 2

@:value(1)@:keepstaticinlineread onlyTHREAD_CREATED:Int = 1

@:value("THREAD_NOT_STOPPED")@:keepstaticTHREAD_NOT_STOPPED:String = "THREAD_NOT_STOPPED"

This tagging value is returned by getStackVariableValue() and setStackVariableValue() if the stack variable that is being set is on a thread that is running, in which case the set does not take place.

@:value(3)@:keepstaticinlineread onlyTHREAD_STARTED:Int = 3

@:value(4)@:keepstaticinlineread onlyTHREAD_STOPPED:Int = 4

@:value(2)@:keepstaticinlineread onlyTHREAD_TERMINATED:Int = 2

Static methods

@:has_untyped@:keepstaticaddClassFunctionBreakpoint(className:String, functionName:String):Int

Adds a new class:function breakpoint. The breakpoint number of the newly added breakpoint is returned.

@:has_untyped@:keepstaticaddFileLineBreakpoint(file:String, line:Int):Int

Adds a new file:line breakpoint. The breakpoint number of the newly added breakpoint is returned.

@:has_untyped@:value({ wait : true })@:keepstaticbreakNow(wait:Bool = true):Void

Breaks all threads except the debugger thread (which should be the same as the calling thread!).

If wait is true, waits up to 2 seconds for all threads to be broken. Threads which are in blocking system calls and cannot break after 2 seconds remain running when this function returns.

@:has_untyped@:keepstaticcontinueThreads(specialThreadNumber:Int, continueCount:Int):Void

Continue execution of all stopped threads. If specialThreadNumber is a valid thread number, then it will be continued past continueCount breakpoints instead of just 1 like all of the other threads.

@:has_untyped@:keepstaticdeleteBreakpoint(number:Null<Int>):Void

Deletes a breakpoint, or all breakpoints.

@:has_untyped@:keepstaticenableCurrentThreadDebugging(enabled:Bool):Void

This can be called to turn off (and then back on) all stopping of debugged threads temporarily. It should only be used by classes that actually implement the debugger to hide themselves from the debugger as necessary.

@:has_untyped@:keepstaticgetClasses():Array<String>

Returns the set of class names of all classes known to the debugger. This is a copy of the original array and could be quite large. The caller should cache this value to avoid multiple copies needing to be made.

Returns:

the set of class names of all classes known to the debugger.

@:has_untyped@:keepstaticgetCurrentThreadNumber():Int

Returns the thread number of the calling thread.

Returns:

the thread number of the calling thread.

@:has_untyped@:keepstaticgetFiles():Array<String>

Returns the set of source files known to the debugger. This is a copy of the original array and could be quite large. The caller should cache this value to avoid multiple copies needing to be made.

Returns:

the set of source files known to the debugger.

@:has_untyped@:keepstaticgetFilesFullPath():Array<String>

Returns the full paths of the set of source files known to the debugger. This is a copy of the original array and could be quite large. It is possible that this set will be empty, in which case the full paths are not known. The index of these files matches the index from getFiles(), so the full path for a given short path can be calculated.

Returns:

the known full paths of the set of source files

@:has_untyped@:keepstaticgetStackVariableValue(threadNumber:Int, stackFrameNumber:Int, name:String, unsafe:Bool):Dynamic

Returns the value of a stack variable, or NONEXISTENT_VALUE if the requested value does not exist. If the thread is actively running and unsafe is not true, returns THREAD_NOT_STOPPED.

@:has_untyped@:keepstaticgetStackVariables(threadNumber:Int, stackFrameNumber:Int, unsafe:Bool):Array<String>

Returns the list of local variables (including this, function arguments, and local variables) visible to the given thread at the given stack frame.

Returns a list with a single entry, THREAD_NOT_STOPPED, if the thread is not stopped and thus variables cannot be fetched and unsafe is not true.

Returns:

the list of local variables (including this, function arguments, and local variables) visible to the given thread at the given stack frame.

@:has_untyped@:keepstaticgetThreadInfo(threadNumber:Int, unsafe:Bool):ThreadInfo

Returns a ThreadInfo object describing a single thread, or null if there is no such thread or the thread queried about was the debugger thread and unsafe was not true.

@:has_untyped@:keepstaticgetThreadInfos():Array<ThreadInfo>

Returns a ThreadInfo object describing every thread that existed at the moment that the call was made, except for the debugger thread.

@:has_untyped@:keepstaticsetEventNotificationHandler(handler:(threadNumber:Int, event:Int, stackFrame:Int, className:String, functionName:String, fileName:String, lineNumber:Int) ‑> Void):Void

Sets the handler callback to be made when asynchronous events occur, specifically, when threads are created, terminated, started, or stopped. The calling thread becomes the "debugger" thread, which means that it will be excluded from any breakpoints and will not be reported on by any thread reporting requests.

Be aware that this callback is made asynchronously and possibly by multiple threads simultaneously.

Setting this to null prevents further callbacks.

Throws a string exception if the program does not support debugging because it was not compiled with the HXCPP_DEBUGGER flag set.

Parameters:

handler

is a function that will be called back by asynchronous thread events. Note that this function is called directly from the thread experiencing the event and the handler should return quickly to avoid blocking the calling thread unnecessarily. The parameters to handler are:

	 - `threadNumber`, the thread number of the event
	 - event, one of `THREAD_CREATED`, `THREAD_TERMINATED`,
	   `THREAD_STARTED`, or `THREAD_STOPPED`
	 - stackFrame, the stack frame number at which the thread is stopped,
	   undefined if event is not `THREAD_STOPPED`
	 - `className`, the class name at which the thread is stopped,
	   undefined if event is not `THREAD_STOPPED`
	 - `functionName`, the function name at which the thread is
	   stopped, undefined if event is not `THREAD_STOPPED`
	 - `fileName`, the file name at which the thread is stopped,
	   undefined if event is not `THREAD_STOPPED`
	 - `lineNumber`, the line number at which the thread is stopped,
	   undefined if event is not `THREAD_STOPPED`

@:has_untyped@:keepstaticsetStackVariableValue(threadNumber:Int, stackFrameNumber:Int, name:String, value:Dynamic, unsafe:Bool):Dynamic

Sets the value of a stack variable and returns that value. If the variable does not exist, on the stack, this function returns NONEXISTENT_VALUE. If the thread is actively running and unsafe is not true, returns THREAD_NOT_STOPPED, and the value is not set.

@:has_untyped@:value({ stepCount : 1 })@:keepstaticstepThread(threadNumber:Int, stepType:Int, stepCount:Int = 1):Void

Single steps the given thread.