Update the docs for the new API

Author: timholy

docs/src/dev_reference.md

@@ -21,6 +21,13 @@ JuliaInterpreter.get_call_framecode
 JuliaInterpreter.optimize!
 ```
 
+## Frame traversal
+
+```@docs
+root
+leaf
+```
+
 ## Frame execution
 
 ```@docs
@@ -35,6 +42,8 @@ JuliaInterpreter.through_methoddef_or_done!
 JuliaInterpreter.evaluate_call!
 JuliaInterpreter.evaluate_foreigncall
 JuliaInterpreter.maybe_evaluate_builtin
+JuliaInterpreter.maybe_next_call!
+JuliaInterpreter.handle_err
 ```
 
 ## Breakpoints
@@ -45,6 +54,7 @@ breakpoint
 enable
 disable
 remove
+JuliaInterpreter.dummy_breakpoint
 ```
 
 ## Types
@@ -53,6 +63,7 @@ remove
 JuliaInterpreter.Frame
 JuliaInterpreter.FrameCode
 JuliaInterpreter.FrameData
+JuliaInterpreter.FrameInstance
 JuliaInterpreter.BreakpointState
 JuliaInterpreter.BreakpointRef
 ```
@@ -72,8 +83,9 @@ JuliaInterpreter.@lookup
 JuliaInterpreter.is_wrapper_call
 JuliaInterpreter.is_doc_expr
 JuliaInterpreter.is_global_ref
+CodeTracking.whereis
+JuliaInterpreter.linenumber
 JuliaInterpreter.statementnumber
 JuliaInterpreter.Variable
 JuliaInterpreter.locals
-CodeTracking.whereis
 ```

docs/src/internals.md

@@ -9,35 +9,25 @@ let's build a frame:
 
 ```julia
 julia> frame = JuliaInterpreter.enter_call(summer, A)
-Frame(JuliaInterpreter.FrameCode(summer(A::AbstractArray{T,N} where N) where T in Main at REPL[1]:2, CodeInfo(
-1 ─       s = ($(QuoteNode(zero)))($(Expr(:static_parameter, 1)))
-│   %2  = A
-│         #temp# = ($(QuoteNode(iterate)))(%2)
-│   %4  = ($(QuoteNode(===)))(#temp#, nothing)
-│   %5  = ($(QuoteNode(not_int)))(%4)
-└──       goto #4 if not %5
-2 ┄ %7  = #temp#
-│         a = ($(QuoteNode(getfield)))(%7, 1)
-│   %9  = ($(QuoteNode(getfield)))(%7, 2)
-│         s = ($(QuoteNode(+)))(s, a)
-│         #temp# = ($(QuoteNode(iterate)))(%2, %9)
-│   %12 = ($(QuoteNode(===)))(#temp#, nothing)
-│   %13 = ($(QuoteNode(not_int)))(%12)
-└──       goto #4 if not %13
-3 ─       goto #2
-4 ┄       return s
-), Core.TypeMapEntry[#undef, #undef, #undef, #undef, #undef, #undef, #undef, #undef, #undef, #undef, #undef, #undef, #undef, #undef, #undef, #undef], BitSet([2, 4, 5, 7, 9, 12, 13]), false, false, true), Union{Nothing, Some{Any}}[Some(summer), Some([1, 2, 5]), nothing, nothing, nothing], Any[#undef, #undef, #undef, #undef, #undef, #undef, #undef, #undef, #undef, #undef, #undef, #undef, #undef, #undef, #undef, #undef], Any[Int64], Int64[], Base.RefValue{Any}(nothing), Base.RefValue{JuliaInterpreter.JuliaProgramCounter}(JuliaProgramCounter(1)), Dict{Symbol,Int64}(), Any[])
+Frame for summer(A::AbstractArray{T,N} where N) where T in Main at REPL[2]:2
+   1* 2  1 ─       s = (zero)($(Expr(:static_parameter, 1)))
+   2  3  │   %2  = A
+   3  3  │         #temp# = (iterate)(%2)
+⋮
+A = [1, 2, 5]
+T = Int64
 ```
 
-This is a [`JuliaInterpreter.Frame`](@ref). The `CodeInfo` is the most prominent part of this display,
-and extractable as `code = frame.framecode.code`. (It's a slightly modified form of one returned by `@code_lowered`,
+This is a [`Frame`](@ref). Only a portion of the `CodeInfo` is shown, a small region surrounding
+the current statement (marked with `*` or in yellow text). The full `CodeInfo` can be extracted
+as `code = frame.framecode.src`. (It's a slightly modified form of one returned by `@code_lowered`,
 in that it has been processed by [`JuliaInterpreter.optimize!`](@ref) to speed up run-time execution.)
 
-Much of the rest of the `frame` holds values needed for or generated by execution.
+`frame` has another field, `framedata`, that holds values needed for or generated by execution.
 The input arguments are in `locals`:
 
 ```julia
-julia> frame.locals
+julia> frame.framedata.locals
 5-element Array{Union{Nothing, Some{Any}},1}:
  Some(summer)
  Some([1, 2, 5])
@@ -62,7 +52,7 @@ The `Expr(:static_parameter, 1)` statement refers to this value.
 The other main storage is for the generated SSA values:
 
 ```julia
-julia> frame.ssavalues
+julia> frame.framedata.ssavalues
 16-element Array{Any,1}:
  #undef
  #undef
@@ -89,31 +79,25 @@ which just indicates the next statement to be executed:
 
 ```julia
 julia> frame.pc
-JuliaProgramCounter(1)
+1
 ```
 
-This is stored as a `Ref` so that it can be updated as execution progresses.
-
-Let's try executing the first statement. So that we can recurse into calls (e.g., `iterate`, `+`, etc.,),
-we'll create a [stack](https://en.wikipedia.org/wiki/Call_stack) of frames and then run the first statement:
+Let's try executing the first statement:
 
 ```julia
-julia> stack = JuliaInterpreter.Frame[]
-0-element Array{Frame,1}
-
-julia> JuliaInterpreter.step_expr!(stack, frame)
-JuliaProgramCounter(2)
+julia> JuliaInterpreter.step_expr!(frame)
+2
 ```
 
 This indicates that it ran statement 1 and is prepared to run statement 2.
 (It's worth noting that the first line included a `call` to `zero`, so behind the scenes
-JuliaInterpreter pushed this frame onto `stack`, created a new frame for `zero`,
-executed all the statements, and then popped the stack.)
+JuliaInterpreter created a new frame for `zero`, executed all the statements, and then popped
+back to `frame`.)
 Since the first statement is an assignment of a local variable, let's check the
 locals again:
 
 ```julia
-julia> frame.locals
+julia> frame.framedata.locals
 5-element Array{Union{Nothing, Some{Any}},1}:
  Some(summer)
  Some([1, 2, 5])
@@ -128,10 +112,10 @@ The next statement just retrieves one of the slots (the input argument `A`) and
 it in an SSA value:
 
 ```julia
-julia> JuliaInterpreter.step_expr!(stack, frame)
-JuliaProgramCounter(3)
+julia> JuliaInterpreter.step_expr!(frame)
+3
 
-julia> frame.ssavalues
+julia> frame.framedata.ssavalues
 16-element Array{Any,1}:
  #undef
     [1, 2, 5]
@@ -152,9 +136,9 @@ julia> frame.ssavalues
 ```
 
 One can easily continue this until execution completes, which is indicated when `step_expr!`
-returns `nothing`. Alternatively, use the higher-level `JuliaInterpreter.finish!(stack, frame)`
+returns `nothing`. Alternatively, use the higher-level `JuliaInterpreter.finish!(frame)`
 to step through the entire frame,
-or `JuliaInterpreter.finish_and_return!(stack, frame)` to also obtain the return value.
+or `JuliaInterpreter.finish_and_return!(frame)` to also obtain the return value.
 
 ## More complex expressions
 
@@ -171,7 +155,7 @@ ex = quote
 end
 
 frame = JuliaInterpreter.prepare_thunk(Main, ex)
-JuliaInterpreter.finish_and_return!(Frame[], frame)
+JuliaInterpreter.finish_and_return!(frame)
 
 # output
 
@@ -196,7 +180,7 @@ Here's a demonstration of the problem:
 ```julia
 ex = :(map(x->x^2, [1, 2, 3]))
 frame = JuliaInterpreter.prepare_thunk(Main, ex)
-julia> JuliaInterpreter.finish_and_return!(Frame[], frame)
+julia> JuliaInterpreter.finish_and_return!(frame)
 ERROR: this frame needs to be run a top level
 ```
 
@@ -235,7 +219,7 @@ function" for this type, equivalent to `(##17#18)(x) = x^2`.
 In some cases one can fix this simply by indicating that we want to run this frame at top level:
 
 ```julia
-julia> JuliaInterpreter.finish_and_return!(Frame[], frame, true)
+julia> JuliaInterpreter.finish_and_return!(frame, true)
 3-element Array{Int64,1}:
  1
  4
@@ -247,11 +231,10 @@ for more complex situations where there may be nested calls of new methods):
 
 ```julia
 modexs, _ = JuliaInterpreter.split_expressions(Main, ex)
-stack = Frame[]
 for (mod, e) in modexs
     frame = JuliaInterpreter.prepare_thunk(mod, e)
     while true
-        JuliaInterpreter.through_methoddef_or_done!(stack, frame) === nothing && break
+        JuliaInterpreter.through_methoddef_or_done!(frame) === nothing && break
     end
     JuliaInterpreter.get_return(frame)
 end

src/construct.jl

@@ -188,9 +188,7 @@ mymethod (generic function with 1 method)
 julia> framecode, frameargs, lenv, argtypes = JuliaInterpreter.prepare_call(mymethod, [mymethod, [1.0,2.0]]);
 
 julia> framecode
-JuliaInterpreter.FrameCode(mymethod(x::Array{T,1}) where T in Main at none:1, CodeInfo(
-1 ─     return 1
-), Union{Compiled, TypeMapEntry}[#undef], JuliaInterpreter.BreakpointState[#undef], BitSet([]), false, false, true)
+  1  1  1 ─     return 1
 
 julia> frameargs
 2-element Array{Any,1}:
@@ -477,10 +475,10 @@ julia> mymethod(x) = x+1
 mymethod (generic function with 1 method)
 
 julia> JuliaInterpreter.enter_call_expr(:(\$mymethod(1)))
-Frame(JuliaInterpreter.FrameCode(mymethod(x) in Main at none:1, CodeInfo(
-1 ─ %1 = ($(QuoteNode(+)))(x, 1)
-└──      return %1
-), Union{Compiled, TypeMapEntry}[#undef, #undef], JuliaInterpreter.BreakpointState[#undef, #undef], BitSet([1]), false, false, true), Union{Nothing, Some{Any}}[Some(mymethod), Some(1)], Any[#undef, #undef], Any[], Int64[], Base.RefValue{Any}(nothing), Base.RefValue{JuliaInterpreter.JuliaProgramCounter}(JuliaProgramCounter(1)), Dict(Symbol("#self#")=>1,:x=>2), Any[])
+Frame for mymethod(x) in Main at none:1
+  1* 1  1 ─ %1 = (+)(x, 1)
+  2  1  └──      return %1
+x = 1
 
 julia> mymethod(x::Vector{T}) where T = 1
 mymethod (generic function with 2 methods)
@@ -491,9 +489,10 @@ julia> a = [1.0, 2.0]
  2.0
 
 julia> JuliaInterpreter.enter_call_expr(:(\$mymethod(\$a)))
-Frame(JuliaInterpreter.FrameCode(mymethod(x::Array{T,1}) where T in Main at none:1, CodeInfo(
-1 ─     return 1
-), Union{Compiled, TypeMapEntry}[#undef], JuliaInterpreter.BreakpointState[#undef], BitSet([]), false, false, true), Union{Nothing, Some{Any}}[Some(mymethod), Some([1.0, 2.0])], Any[#undef], Any[Float64], Int64[], Base.RefValue{Any}(nothing), Base.RefValue{JuliaInterpreter.JuliaProgramCounter}(JuliaProgramCounter(1)), Dict(Symbol("#self#")=>1,:x=>2), Any[])
+Frame for mymethod(x::Array{T,1}) where T in Main at none:1
+  1* 1  1 ─     return 1
+x = [1.0, 2.0]
+T = Float64
 ```
 
 See [`enter_call`](@ref) for a similar approach not based on expressions.
@@ -518,18 +517,19 @@ julia> mymethod(x) = x+1
 mymethod (generic function with 1 method)
 
 julia> JuliaInterpreter.enter_call(mymethod, 1)
-Frame(JuliaInterpreter.FrameCode(mymethod(x) in Main at none:1, CodeInfo(
-1 ─ %1 = ($(QuoteNode(+)))(x, 1)
-└──      return %1
-), Union{Compiled, TypeMapEntry}[#undef, #undef], JuliaInterpreter.BreakpointState[#undef, #undef], BitSet([1]), false, false, true), Union{Nothing, Some{Any}}[Some(mymethod), Some(1)], Any[#undef, #undef], Any[], Int64[], Base.RefValue{Any}(nothing), Base.RefValue{JuliaInterpreter.JuliaProgramCounter}(JuliaProgramCounter(1)), Dict(Symbol("#self#")=>1,:x=>2), Any[])
+Frame for mymethod(x) in Main at none:1
+  1* 1  1 ─ %1 = (+)(x, 1)
+  2  1  └──      return %1
+x = 1
 
 julia> mymethod(x::Vector{T}) where T = 1
 mymethod (generic function with 2 methods)
 
 julia> JuliaInterpreter.enter_call(mymethod, [1.0, 2.0])
-Frame(JuliaInterpreter.FrameCode(mymethod(x::Array{T,1}) where T in Main at none:1, CodeInfo(
-1 ─     return 1
-), Union{Compiled, TypeMapEntry}[#undef], JuliaInterpreter.BreakpointState[#undef], BitSet([]), false, false, true), Union{Nothing, Some{Any}}[Some(mymethod), Some([1.0, 2.0])], Any[#undef], Any[Float64], Int64[], Base.RefValue{Any}(nothing), Base.RefValue{JuliaInterpreter.JuliaProgramCounter}(JuliaProgramCounter(1)), Dict(Symbol("#self#")=>1,:x=>2), Any[])
+Frame for mymethod(x::Array{T,1}) where T in Main at none:1
+  1* 1  1 ─     return 1
+x = [1.0, 2.0]
+T = Float64
 ```
 
 For a `@generated` function you can use `enter_call((f, true), args...; kwargs...)`

src/types.jl

@@ -185,10 +185,8 @@ function Base.show(io::IO, frame::Frame)
     range = get(io, :limit, false) ? (max(1, pc-2):min(ns, pc+2)) : (1:ns)
     first(range) > 1 && println(io, "⋮")
     print_framecode(io, frame.framecode; pc=pc, range=range)
-    last(range) < ns && print(io, "⋮")
-    for lv in locals(frame)
-        println(IOContext(io, :limit=>true, :compact=>true), '\n', lv)
-    end
+    last(range) < ns && print(io, "\n⋮")
+    print_vars(IOContext(io, :limit=>true, :compact=>true), locals(frame))
     if caller(frame) !== nothing
         print(io, "\ncaller: ", scopeof(caller(frame)))
     end

src/utils.jl

@@ -225,9 +225,12 @@ function print_framecode(io::IO, framecode::FrameCode; pc=0, range=1:nstatements
     ndline = isempty(lt) ? 0 : ndigits(lt[end].line + offset)
     nullline = " "^ndline
     code = framecode_lines(framecode)
+    isfirst = true
     for (stmtidx, stmtline) in enumerate(code)
         stmtidx ∈ range || continue
         bpc = breakpointchar(framecode, stmtidx)
+        isfirst || print(io, '\n')
+        isfirst = false
         print(io, bpc, ' ')
         if iscolor
             color = stmtidx == pc ? Base.warn_color() : :normal
@@ -236,7 +239,7 @@ function print_framecode(io::IO, framecode::FrameCode; pc=0, range=1:nstatements
             print(io, lpad(stmtidx, ndstmt), stmtidx == pc ? '*' : ' ')
         end
         line = linenumber(framecode, stmtidx)
-        println(io, ' ', line === nothing ? nullline : lpad(line, ndline), "  ", stmtline)
+        print(io, ' ', line === nothing ? nullline : lpad(line, ndline), "  ", stmtline)
     end
 end
 
@@ -261,6 +264,13 @@ function locals(frame::Frame)
     return vars
 end
 
+function print_vars(io::IO, vars::Vector{Variable})
+    for v in vars
+        v.name == Symbol("#self#") && (isa(v.value, Type) || sizeof(v.value) == 0) && continue
+        print(io, '\n', v)
+    end
+end
+
 function show_stackloc(io::IO, frame)
     indent = ""
     fr = root(frame)