NAME

Devel::hdb::App::Control - Control execution of the debugged program

DESCRIPTION

Registers routes for methods to control execution of the debugged program

Routes

GET /status

Get status information about the debugged program. Returns 200 and a JSON-encoded hash in the body with these keys:

  running     => True if the program is running, false if terminated
  subroutine  => Name of the subroutine the program is stopped in
  filename    => Name of the file the program is stopped in
  line        => Line number the program is stopped on
  stack_depth => How deep the program stack currently is
  events      => Array of program events since the last status report

For each event, there will be a hash describing the event. All events have a 'type' key. The other keys are type-specific.

fork

Immediately after the debugged program fork()s.

        type     => "fork"
        pid      => Child process ID
        href     => URL to communicate with the child process debugger
        gui_href => URL to bring up the child process GUI
        href_continue => URL to GET to tell the child to run without stopping

exception

When the program generates an uncaught exception

        type       => "exception"
        value      => Value of the exception
        package    => Location where the exception occurred
        filename   => ...
        subroutine => ...
        line       => ...

watchpoint

When a watchpoint expression changes value. The location reported is whichever line had executed immediately before the current program line - likely the line that caused the change.

        type       => "watchpoint"
        expr       => Expression that changed value
        old        => Listref of the previous value
        new        => Listref of the new value
        package    => Location where the value was changed
        filename   => ...
        subroutine => ...
        line       => ...

exit

When the program is terminating

        type       => "exit"
        value      => Program exit code

hangup

When the program is exiting and will not respond to further requests.

        type       => "hangup"

trace_diff

When run in follow mode and an execution difference has happened.

        type       => "trace_diff"
        filename   => Where the program is stopped now
        line       => ...
        package    => ...
        subroutine => ...
        sub_offset => ...
        expected_filename   => where the trace expected to be instead
        expected_line       => ...
        expected_package    => ...
        expected_subroutine => ...

POST /stepin

Causes the debugger to execute the current statement and pause before the next. If the current statement involves a function call, execution stops at the first line inside the called function.

Returns 200 and the same JSON hash as GET /status

POST /stepover

Causes the debugger to execute the current statement and pause before the next. If the current statement involves function calls, these functions are run to completion and execution stops before the next statement at the current stack level. If execution of these functions leaves the current stack frame, usually from an exception caught at a higher frame or a goto, execution pauses at the first statement following the unwinding.

Returns 200 and the same JSON hash as GET /status

POST /steoput

Causes the debugger to start running continuously until the current stack frame exits.

Returns 200 and the same JSON hash as GET /status

POST /continue

Causes the debugger to start running continuously until it encounters another breakpoint.

Returns 200 and the same JSON hash as GET /status

POST /continue?nostop=1

Request the debugger continue execution. The param nostop=1 instructs the debugger to run the program to completion and not stop at any breakpoints.

Returns 204 if successful.

/status, /stepin, /stepover, /stepout and continue accept either or both of these optional parameters

next_statement=1

The returned status hash includes a next_statement key whose value is a string representation of the next Perl statement to execute.

next_fragment=<integer>

The returned status hash includes a next_fragment key whose value is a string representation of the immediately-next opcode to execute. The integer value is the number of parents of the current opcode to go up before starting to deparse. 0 means to deparse only the current opcode; 1 means to deparse the current opcode's parent and that parent's children.

SEE ALSO

Devel::hdb

AUTHOR

Anthony Brummett <brummett@cpan.org>

COPYRIGHT

Copyright 2018, Anthony Brummett. This module is free software. It may be used, redistributed and/or modified under the same terms as Perl itself.