Clarify the use of @Step and @Main on the main entry point method

[dvojtise]

Apparently having only @Main on the main entry point method does not behave the same if we also add the @Step on it.

This has impact in:

• the tracemanager, if there is no @Step on the main method, we do not get a big step in the trace for it,
• the stack in the debug view

If I take the Logo example (from https://github.com/dvojtise/mde-crashcourse-logo)

@Aspect(className=LogoProgram)
class LogoProgramAspect {
    @Step                                               
    @InitializeModel                                    
    def void initializeModel(EList<String> args){
        val context = VmFactory.eINSTANCE.createInterpreterRuntimeContext
        context.turtle = VmFactory.eINSTANCE.createTurtle
        val point = VmFactory.eINSTANCE.createPoint
        point.x = 0
        point.y = 0
        context.turtle.reachedPoints.add(point)
        context.turtle.position = point
        _self.runtimeContext = context
    }

    @Main
    def void run(){
        val context = _self.runtimeContext as InterpreterRuntimeContext
        _self.instructions.forEach[i | i.run(_self.runtimeContext as InterpreterRuntimeContext)]
    }
}

we get this stack:

and if we add the @Step too, we get

This second version (with both @Step and @Main) is more regular in the way we can deal with the stack. (and have a cleaner representation for its content). Additionnaly this make sure to store a value in the trace for it. The notion of "global context" frame is more a trick that was useful in the context of the concurrent engine but does not really make sense in the context of a sequential engine. (It can represent the engine stack frame that will run the initialize method then run the main method even if it has no stored step in the trace?)

[ebousse]

To me the separation between @main and @step has always been clear:

• @main tells where the interpreter starts,
• @step tells what are observable domain execution steps.

If your @main method is not a @step, it means an execution of a model of your language does not instantly start with an observable step, but will indirectly trigger some (through other @step methods).

If your @main method is a @step, it means for your language that all your steps will always be enclosed in one large domain step.

I would not say that there is a good or bad option here, it only depends how one wants to structure the domain steps of her language. One could argue for instance that a state machine DSL is only a sequence of fire observable steps and nothing else, while someone else could consider that all these fire steps are enclosed in a larger run observable step.

And the "global context" does not represent any real frame whatsoever, and especially not an "execution engine" context/frame since we are only here showing model-level information. This frame is only a hack to have a place to put all the variables into, it should not even exist if we did not have any issues with the latter point (but you mentioned a branch where you solved it so that's good news :)). Therefore for this discussion here, I consider that we can pretend this "Global context" frame does not even exist, as it is irrelevant and is not related to observable domain-level execution steps.

To come back to the initial suggestion: yes we can put a small comment in the documentation on whether or not one would want to put @step on the @main method, if that can help some.

[dvojtise]

agreed for the doc, however, as a default, I would probably also change most official example in order to add @Step on every main method. Then the user will be free to remove it if not required in his language. Note: this has some impact when correctly setting the currentInstruction versus context information in the frame. If there is no "container" frame referencing the main, obviously, setting the currentInstruction will have no visible effect since it should apply on the larger frame.

Yes I'm also tempted to remove this global context too, (at least from the general framework and the sequential engines) I only need to see how to deal with it in the concurrent engine when it'll be back in the master