QScriptEngineAgent Class

Detailed Description

The QScriptEngineAgent class is the basis of tools that monitor and/or control the execution of a QScriptEngine, such as debuggers and profilers.

To process script loading and unloading events, reimplement the scriptLoad() and scriptUnload() functions. scriptLoad() is called after the input to QScriptEngine::evaluate() has been parsed, right before the given script is executed. The engine assigns each script an ID, which is available as one of the arguments to scriptLoad(); subsequently, other event handlers can use the ID to identify a particular script. One common usage of scriptLoad() is to retain the script text, filename and base line number (the original input to QScriptEngine::evaluate()), so that other event handlers can e.g. map a line number to the corresponding line of text.

scriptUnload() is called when the QScriptEngine has no further use for a script; the QScriptEngineAgent may at this point safely discard any resources associated with the script (such as the script text). Note that after scriptUnload() has been called, the QScriptEngine may reuse the relevant script ID for new scripts (i.e. as argument to a subsequent call to scriptLoad()).

Evaluating the following script will result in scriptUnload() being called immediately after evaluation has completed:

 var a = Math.random() + 2;

Evaluating the following script will not result in a call to scriptUnload() when evaluation has completed:

 function cube(a) {
     return a * a * a;
 }

 var a = cube(3);

The script isn't unloaded because it defines a function (cube) that remains in the script environment after evaluation has completed. If a subsequent script removed the cube function (e.g. by setting it to null), scriptUnload() would be called when the function is garbage collected. In general terms, a script isn't unloaded until the engine has determined that none of its contents is referenced.

To process script function calls and returns, reimplement the functionEntry() and functionExit() functions. functionEntry() is called when a script function is about to be executed; functionExit() is called when a script function is about to return, either normally or due to an exception.

To process individual script statements, reimplement positionChange(). positionChange() is called each time the engine is about to execute a new statement of a script, and thus offers the finest level of script monitoring.

To process exceptions, reimplement exceptionThrow() and exceptionCatch(). exceptionThrow() is called when a script exception is thrown, before it has been handled. exceptionCatch() is called when an exception handler is present, and execution is about to be resumed at the handler code.