Trace Service API
#Trace Service API [Aurelia]
##Quick guide
The following snippet is from JsEditor (src/jsEditor/js-editor.js). When you call getTrace(), you send the source code text as input (we will discuss other parameters later). Then, the service will add log calls to that code and run it. Once it ends it will return the results. In the snippet, when the source code changes, the method publishes the event "onTraceChanged" with the trace output as payload. It is expected that the Visualization Team subscribes to this event.
function onEditorChanged(e) {
clearTimeout(editorChangedTimeout);
editorChangedTimeout = setTimeout(function pub() {
let payload = new TraceService().getTrace(editor.getValue());
ea.publish('onTraceChanged', payload);
}, 2500);
}From the previous snippet, the result contained in payload is as follows:
{
status: 'onTraceServiceEnd',
description: 'Trace built successfully.' ,
data : [expression_01,..., expression_n]
}Normally, you will expect an output like the one above. However, long code or problems such as infinite loops/recursion and runtime errors could happen, so we can keep your inform of what is going on. These are the events the service handles:
Let's look this example:
let c= false;
let n=c; The trace (payload.data) will contain the following information:
Assuming that results are published after the document changed, subscribing to the onTraceChanged event will keep your trace up to date:
subscribe() {
let ea = this.eventAggregator;
ea.subscribe('onTraceChanged', payload => {
this.trace = payload;
}
);
}So you can visualize the elements with the aid of a TraceHelper:
visualizelineValues( lineNumber){
let traceHelper = new TraceHelper();
let values = traceHelper.getLineValues(this.trace, lineNumber);
// draw values somehow
}To simplify the output of the trace, use the following methods:
This is the case shows values only for variables in the trace.
#Service Workflow
This is the whole picture of how Trace Service works:
We have the following events for the service:
######ExecutionTrace feature team trace javascript classes and functions
- Usage: creates a new traceServer object.
- Parameter Information: none.
- Function Dependencies: none.
- Class Dependencies: estracer.js.
- Usage: get the maximum time limit on code execution to prevent infinite loop.
- Parameter Information: none.
- Function Dependencies: none.
- Class Dependencies: estracer.js
- Usage: set the maximum time limit on code execution.
- Parameter Information: none.
- Function Dependencies: none.
- Class Dependencies: estracer.js
- Usage: stops trace object from collecting trace any longer.
- Parameter Information: none.
- Function Dependencies: none.
- Class Dependencies: estracer.js
- Usage: gets the next trace of the code update.
- Parameter Information: timeLimit and publisher are optional parameters. Publisher object must contain method publish (to be used with an EventAggregator)
- Function Dependencies: estracer.traceExecution(code, timelimit, publisher) - publisher is optional parameter.
- Class Dependencies: estracer.js
- Usage: updates trace information in ace editor annotation tool.
- Parameter Information: aceEditor is an Ace object created from AceEditor.
- Function Dependencies: none.
- Class Dependencies: estracer.js, (AceEditor).
- Usage: gets a "toString()" version of the stack trace.
- Parameter Information: none.
- Function Dependencies: none.
- Class Dependencies: none.
- Usage: gets a "toString()" version of the execution trace.
- Parameter Information: none.
- Function Dependencies: none.
- Class Dependencies: none.
- Usage: determines whether the given position in esprima range is in "inRange".
- Parameter Information: none.
- Function Dependencies: none.
- Class Dependencies: none.
- Usage: get all the values of the "lineNumber" stored in an array
- Parameter Information: none.
- Function Dependencies: getValues(Map esprimaRange, Map valueTable): Array
- Class Dependencies: none.
- Usage: get all the values within the "esprimaRange" stored in an array
- Parameter Information: none.
- Function Dependencies: none.
- Class Dependencies: none.
- Usage: get all the values with the type within the "esprimaRange" stored in a map
- Parameter Information: none.
- Function Dependencies: none.
- Class Dependencies: none.
We got a version that does not use classes in the "ExecutionTrace" branch. Please, add the code you want to see the trace output in our [kitchen sink] (https://github.com/tlatoza/SeeCodeRun/blob/ExecutionTrace/include/executiontrace/David/TraceServiceKitchensink.html). Open it in Cloud9, you can check out the "ExecutionTrace" branch and run the previous file.
The service is called automatically every time the code is changed.
We are visualizing the output on the top right side of the page. ####Note ######Currently, due to Aurelia's custom execution context, we cannot call eval() to trace the code. Once we know how to implement this in Aurelia, we'll commit to the master branch. Please refer to the examples above meanwhile.
Our API consists of two classes, TraceService and TraceHelper. You get the trace by calling getTrace() on an instance of TraceService. The result of that call is the status of the trace and its data, you can use TraceHelper to extract meaningful information with ease. In the following communication diagram, we depict how the API works:
