Revised Mirrors proposal/take 3.

mirrors/debug.dart

Index: mirrors/debug.dart
===================================================================
--- mirrors/debug.dart	(revision 0)
+++ mirrors/debug.dart	(revision 0)
@@ -0,0 +1,130 @@
+#library("debug");
+#import("introspection.dart");

[hausner, 2011/12/21 21:53:19]

Can you import a source file? Should this be #source instead of #import?

[gbracha, 2011/12/22 18:29:59]

introspection should be a library.

+
+/** A mirror on the entire stack of an isolate.
+// questions about being active, suspending, resuming may perhaps belong to the isolate?
+
+The methods in this interface are synchronous wrappers around async message sends. 
+We could make the all return a  future instead. Ideally, I would declare them as 
+async methods.
+*/
+interface StackMirror extends Mirror {
+  /** Return a mirror on the activation at the top of the stack.
+
+*/
+ActivationMirror top(); 
+
+/** Return the otal number of frames in the stack. */
+int length(); 
+
+
+/** 
+Call the function at the current point in the calling frame, and stop at the first pc in that function. 

[hausner, 2011/12/21 21:53:19]

In this description you are implying that there is always a call at a
breakpoint.  That may be true for the actual generated code, but not at the
source level.

A more general question is: what is the granularity of step and next?

BTW, I like the more familiar names stepInto and stepOver better.

[gbracha, 2011/12/22 18:29:59]

I like stepInto and stepOver as well. As for stepping into, if there is no call
at the current pc, one should specify what happens - for instance, nothing.
for stepOver/next, perhaps there needs to be a distinction between evaluating
the next subexpression and the next method invocation. 

+
+Open issue 1: Return void, or an ActivationMirror representing the activation where we
+have landed. Arguably, that activation is always the top-of-stack (TOS); but what's 
+the harm in returning the activation we're at after the operation
+ instead of forcing you to ask for TOS? So I propose we return the TOS after the call.
+
+Open issue 2: Should this take an ActivationMirror as an argument. 
+One can argue that no argument is needed, as TOS (top-of-stack) is implicit.  
+However, it's nice to able to restart from an earlier point. Hence, there is an
+optional argument that specifies what activation to start out from.
+If it's null, we use TOS.

[hausner, 2011/12/21 21:53:19]

Alternatively, step and next could be methods of the ActivationMirror class,
returning a StackMirror object.

[gbracha, 2011/12/22 18:29:59]

Yes, but why?

[hausner, 2011/12/23 00:22:16]

Because then you don't have the issue you mention in the comment. The
ActivationMirror would be the implicit argument (because it's the receiver).

If we limit step/next to the top of stack frame, then they belong in
StackMirror. 

[gbracha, 2011/12/23 00:41:23]

Good point. 
I definitely do NOT want to limit step/next to TOS.  

+ 
+*/
+ActivationMirror step([ActivationMirror callingFrame]);
+// this was stepInto; renamed per Lars' request.
+
+/** 
+Call the function at the current point in the calling frame, and stop at the pc 
+immediately after the call.
+Open issues are similar to those in 'step' above. However, here we very clearly want to
+be able to specify a calling frame.
+*/
+ActivationMirror next([ActivationMirror callingFrame]);
+ // This was stepOver; renamed per Lars' request.
+
+
+// not needed - no first class control construct:
+// void stepIntoClosure(ActivationMirror activation);
+
+/** Resume execution.
+This method is asynchronous (not a synchronous wrapper).
+Does it belong on the isolate?
+*/
+void restart();
+}
+
+
+/** Scope mirrors represent subscopes in function bodies. These could be entire bodies, or blocks within a surrounding body or block, recursively.
+
+Again, methods here are synchronous wrappers.
+*/
+interface ScopeMirror extends ObjectMirror {
+/** Names of all locals. Is this redundant with accessors defined by ObjectMirror? */
+  List<String> localNames(); 
+
+
+/** The enclosing scope/context. 
+For subscopes, its the surrounding ScopeMirror or ActivationMirror. For an activation, it would be the receiver.
+*/
+  ObjectMirror enclosingScope();
+
+/** The program counter. the natural representation is a token, which already captures the location information: character index, file etc.
+  */ 
+  Token pc(); 

[hausner, 2011/12/21 21:53:19]

I don't see Token defined anywhere. What can I do with a Token object?

Also, implicitly generated code does not have a natural token position. For
example, implicit constructors, or code generated in for-in loops to initialize
and advance the implicit iterator object.

[gbracha, 2011/12/22 18:29:59]

Indeed. It should be much the same as in the parser.

What can I do with a Token object?

Ask it for its start and end indices in the source code, what (file)stream it
came from.
Yes, but should we be able to break there?

[mattsh, 2011/12/22 21:00:05]

I'm hoping in Dart we can make an nice UI for stepping through things like
foo(bar(baz() + 1)), and be able to highlight exactly the right tokens, as you
progress through subexpressions of a larger statement.  This makes me think that
returning a single token for the pc (or even a range) is not going to be
sufficient.  We may need to be able to express a discontiguous range of tokens.

[hausner, 2011/12/23 00:22:16]

No, but there can be ActivationFrames on the stack that correspond to this
generated code. An implicit constructor (which does not have source test
associated with it) can call a user-defined constructor, and I can set a
breakpoint there.

[gbracha, 2011/12/23 00:41:23]

Of course.
So Token is probably the wrong word here. I assumed Tokens know where they begin
and where they end, but apparently that isn't always the case. What I mean is a
source location (and I will rename this to Location) which can tell you
beginning and ending indices, the string to which those indices relate, and the
URI where the string came from, if there is one.

I don't see why a range is insufficient. I've built such tools before and a
range has always been adequate. What is not adequate is line number!

[gbracha, 2011/12/23 00:41:23]

If no source code is available, one should be able to detect this and show the
frame with something like "No source code available". Should we have a way of
identifying auto-generated frames vai the API?

[mattsh, 2011/12/23 00:50:19]

Right.  I guess I was picturing that in this expression:
foo(baz() + 1)
first baz() will be highlighted, then, after step, "baz() + 1" will be
highlighted, then the question is, do you want to highlight the whole continuous
range "foo(baz() + 1)"?  I suppose the answer is "yes", in which case a single
continuous range is sufficient.  
But, if at that point you wanted to just highlight the "foo(" and the closing
")", without highlighting the baz() + 1 expression in the middle (because it has
already executed), the we'd need discontinuous ranges.

+  
+/** Returns a list of length 2, representing the range of program counters for the 
+reflectee. 
+ */
+  List<Token> pcRange(); 
+}
+
+
+/** A mirror on a stack frame.
+It gives us access to its local variables, parameters, subscopes, the ability to set the PC etc.
+
+All methods here are synchoronous wrappers again.
+
+*/
+interface ActivationMirror extends ScopeMirror{
+
+/** a mirror on the receiver of this activation
+ If it's a static method return null (not a mirror on null!).
+ Alternately, dispense with this method and require 'this' be looked up among the locals? */
+ObjectMirror receiverMirror(); 
+
+/** Return the frame that called the reflectee. */
+ActivationMirror caller(); 
+
+/**
+  Return an mirror on the activation that would catch the exception represented by
+  o, if it were thrown. Returns null if none. The argument o must be either a value
+  (in which case it will be used as the exception) or an object mirror (in which
+  case o's reflectee will be used as the exception to be thrown).
+
+   There is no easy way to implement this based on other primitives, but
+   the VM has the ability to do this without actually throwing an exception.
+
+*/
+ActivationMirror handlerFor(Object o); // if I threw o, where would I land?
+
+
+
+/** A mirror on the function the reflectee is an activation of.
+ // could be closure. Therefore the return type is 
+// potentially MethodMirror | ClosureMirror. So maybe we should define a common
+// supertype for those two.
+
+This method is not asynchronous. We should be able to embded this data in the
+activation mirror.
+*/
+MethodMirror method();
+
+/**
+Return to the caller of the reflectee. The value returned is o, if o is a value, or
+o's reflectee if o is an objetc mirror; o must be either a value or an object mirror.
+*/
+returnObject(Object o, ActivationMirror); // terminate this frame and return o.
+}