HaxeFoundation.haxe/std/cpp/vm/Debugger.hx

/*
 * Copyright (C)2005-2017 Haxe Foundation
 *
 * Permission is hereby granted, free of charge, to any person obtaining a
 * copy of this software and associated documentation files (the "Software"),
 * to deal in the Software without restriction, including without limitation
 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
 * and/or sell copies of the Software, and to permit persons to whom the
 * Software is furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 * DEALINGS IN THE SOFTWARE.
 */
package cpp.vm;


/**
 * Parameter describes a function parameter.  Instances of this class are
 * embedded in stack frame objects to describe the function parameters that
 * were used in the invocation of the function that defines that stack frame.
 **/
class Parameter
{
    public var name(default, null) : String;
    public var value(default, null) : Dynamic;

    public function new(name : String, value : Dynamic)
   {
        this.name = name;
        this.value = value;
   }
   }

/**
 * StackFrame describes one call stack frame.
 **/
class StackFrame
   {
    public var fileName(default, null) : String;
    public var lineNumber(default, null) : Int;
    public var className(default, null) : String;
    public var functionName(default, null) : String;
    public var parameters(default, null) : Array<Parameter>;

    public function new(fileName : String, lineNumber : Int,
                        className : String, functionName : String)
   {
        this.fileName = fileName;
        this.lineNumber = lineNumber;
        this.className = className;
        this.functionName = functionName;
        this.parameters = new Array<Parameter>();
   }
   }

/**
 * ThreadInfo describes the state of a single thread.
 **/
class ThreadInfo
   {
    public static inline var STATUS_RUNNING = 1;
    public static inline var STATUS_STOPPED_BREAK_IMMEDIATE = 2;
    public static inline var STATUS_STOPPED_BREAKPOINT = 3;
    public static inline var STATUS_STOPPED_UNCAUGHT_EXCEPTION = 4;
    public static inline var STATUS_STOPPED_CRITICAL_ERROR = 5;

    // 0 is never a valid thread number
    public var number(default, null) : Int;
    public var status(default, null) : Int;
    // If status is "stopped breakpoint", this is the breakpoint number
    public var breakpoint(default, null) : Int;
    // If status is "critical error", this describes the error
    public var criticalErrorDescription(default, null) : String;
    // Stack will be listed with the lowest frame first
    public var stack(default, null) : Array<StackFrame>;

    public function new(number : Int, status : Int, breakpoint : Int = -1,
                        criticalErrorDescription : String = null)
   {
        this.number = number;
        this.status = status;
        this.breakpoint = breakpoint;
        this.criticalErrorDescription = criticalErrorDescription;
        this.stack = new Array<StackFrame>();
   }
   }

/**
 * This class wraps the hxcpp C++ implementation to provide a Haxe interface
 * to the low level debugging features
 **/
class Debugger
   {
    public static inline var THREAD_CREATED = 1;
    public static inline var THREAD_TERMINATED = 2;
    public static inline var THREAD_STARTED = 3;
    public static inline var THREAD_STOPPED = 4;

    public static inline var STEP_INTO = 1;
    public static inline var STEP_OVER = 2;
    public static inline var STEP_OUT = 3;

    // This tagging value is returned by getStackVariableValue() and
    // setStackVariableValue if the requested value does not exist at the
    // requested stack frame
    public static var NONEXISTENT_VALUE = new String("NONEXISTENT_VALUE");
    // 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.
    public static var THREAD_NOT_STOPPED = new String("THREAD_NOT_STOPPED");

    /**
     * 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 discluded 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.
     *
     * @param 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
     **/
    public static function setEventNotificationHandler(
             handler : Int -> Int -> Int -> String -> String -> String -> Int -> Void)
    {
        untyped __global__.__hxcpp_dbg_setEventNotificationHandler(handler);
    }

    /**
     * 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.
     **/
    public static function enableCurrentThreadDebugging(enabled : Bool)
    {
        untyped __global__.__hxcpp_dbg_enableCurrentThreadDebugging(enabled);
    }

    /**
     * Returns the thread number of the calling thread.
     *
     * @return the thread number of the calling thread.
     **/
	public static function getCurrentThreadNumber() : Int
	{
        return untyped __global__.__hxcpp_dbg_getCurrentThreadNumber();
	}

    /**
     * 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.
     *
     * @return the set of source files known to the debugger.
     **/
    public static function getFiles() : Array<String>
   {
        return untyped __global__.__hxcpp_dbg_getFiles();
   }


    /**
     * 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.
     *
     * @return the known full paths of the set of source files
     **/
   public static function getFilesFullPath() : Array<String>
   {
        return untyped __global__.__hxcpp_dbg_getFilesFullPath();
   }

    /**
     * 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.
     *
     * @return the set of class names of all classes known to the debugger.
     **/
    public static function getClasses() : Array<String>
    {
        return untyped __global__.__hxcpp_dbg_getClasses();
    }

    /**
     * Returns a ThreadInfo object describing every thread that existed at the
     * moment that the call was made, except for the debugger thread.
     **/
    public static function getThreadInfos() : Array<ThreadInfo>
    {
        return untyped __global__.__hxcpp_dbg_getThreadInfos();
    }

    /**
     * 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.
     **/
    public static function getThreadInfo(threadNumber : Int,
                                         unsafe : Bool) : ThreadInfo
    {
        return untyped __global__.__hxcpp_dbg_getThreadInfo
            (threadNumber, unsafe);
    }

    /**
     * Adds a new file:line breakpoint.  The breakpoint number of the newly
     * added breakpoint is returned.
     **/
    public static function addFileLineBreakpoint(file : String,
                                                 line : Int) : Int
    {
        return untyped __global__.__hxcpp_dbg_addFileLineBreakpoint
            (file, line);
    }

    /**
     * Adds a new class:function breakpoint.  The breakpoint number of the
     * newly added breakpoint is returned.
     **/
    public static function addClassFunctionBreakpoint(className : String,
                                                   functionName : String) : Int
    {
        return untyped __global__.__hxcpp_dbg_addClassFunctionBreakpoint
            (className, functionName);
    }

    /**
     * Deletes a breakpoint, or all breakpoints.
     **/
    public static function deleteBreakpoint(number : Null<Int>)
    {
        if (number == null) {
            untyped __global__.__hxcpp_dbg_deleteAllBreakpoints();
        }
        else {
            untyped __global__.__hxcpp_dbg_deleteBreakpoint
                (cast (number, Int));
        }
    }

    /**
     * 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.
     **/
    public static function breakNow(wait : Bool = true)
    {
        untyped __global__.__hxcpp_dbg_breakNow(wait);
    }

    /**
     * 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.
     **/
    public static function continueThreads(specialThreadNumber : Int,
                                           continueCount : Int)
    {
        untyped __global__.__hxcpp_dbg_continueThreads
            (specialThreadNumber, continueCount);
    }

    /**
     * Single steps the given thread.
     **/
    public static function stepThread(threadNumber : Int,
                                      stepType : Int,
                                      stepCount : Int = 1)
    {
        untyped __global__.__hxcpp_dbg_stepThread
            (threadNumber, stepType, stepCount);
    }

    /**
     * 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.
     *
     * @return the list of local variables (including "this", function
     *         arguments, and local variables) visible to the given thread at
     *         the given stack frame.
     **/
    public static function getStackVariables(threadNumber : Int,
                                             stackFrameNumber : Int,
                                             unsafe : Bool) : Array<String>
    {
        return untyped __global__.__hxcpp_dbg_getStackVariables
            (threadNumber, stackFrameNumber, unsafe, THREAD_NOT_STOPPED);
    }

    /**
     * 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.
     **/
    public static function getStackVariableValue(threadNumber : Int,
                                                 stackFrameNumber : Int,
                                                 name : String,
                                                 unsafe : Bool) : Dynamic
    {
        return untyped __global__.__hxcpp_dbg_getStackVariableValue
            (threadNumber, stackFrameNumber, name, unsafe, NONEXISTENT_VALUE,
             THREAD_NOT_STOPPED);
    }

    /**
     * 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.
     **/
    public static function setStackVariableValue(threadNumber : Int,
                                                 stackFrameNumber : Int,
                                                 name : String,
                                                 value : Dynamic,
                                                 unsafe : Bool) : Dynamic
    {
        return untyped __global__.__hxcpp_dbg_setStackVariableValue
            (threadNumber, stackFrameNumber, name, value, unsafe,
             NONEXISTENT_VALUE, THREAD_NOT_STOPPED);
    }

    // The hxcpp runtime calls back through these functions to create Haxe
    // objects as needed, which allows the C++ implementation code to create
    // Haxe objects without having to actually know the structure of those
    // objects
    private static function __init__()
    {
        untyped __global__.__hxcpp_dbg_setNewParameterFunction
        (
         function (name : String, value : Dynamic) : Dynamic {
             return new Parameter(name, value);
         }
        );

        untyped __global__.__hxcpp_dbg_setNewStackFrameFunction
        (
         function (fileName : String, lineNumber : Int,
                   className : String, functionName : String)
         {
             return new StackFrame(fileName, lineNumber,
                                   className, functionName);
         }
        );

        untyped __global__.__hxcpp_dbg_setNewThreadInfoFunction
        (
         function (number : Int, status : Int, breakpoint : Int,
                   criticalErrorDescription : String) : Dynamic {
             return new ThreadInfo(number, status, breakpoint,
                                   criticalErrorDescription);
         }
        );

        untyped __global__.__hxcpp_dbg_setAddParameterToStackFrameFunction
        (
         function(inStackFrame : Dynamic, inParameter : Dynamic) {
             var stackFrame : StackFrame = cast inStackFrame;
             var parameter : Parameter = cast inParameter;
             stackFrame.parameters.push(parameter);
         }
        );

        untyped __global__.__hxcpp_dbg_setAddStackFrameToThreadInfoFunction
        (
         function(inThreadInfo : Dynamic, inStackFrame : Dynamic) {
             var threadInfo : ThreadInfo = cast inThreadInfo;
             var stackFrame : StackFrame = cast inStackFrame;
             threadInfo.stack.push(stackFrame);
   }
        );
   }
}