Javascript script load and execution

Code and context (data)

Code is the internal structure holding the instructions parsed on script load.
Code won't change during script run.

Context is the internal structure holding all variables created during script run.
Variables created in one context are only available in script using it.

Script context initialize

Each time a context is created the module will do the following:

• Push native objects and functions into the context:
  • Standard Javascript objects (Object, Array, XML, RegExp, ...)
  • Standard Javascript functions (parseInt, isNaN, ...)
  • Routing script context (See How to do routing using javascript). Insert Channel and message objects. Each active call using the routing script will have its own context
  • Yate specific objects (Engine, Message, ConfigFile ...)
• Dispatch a script.init message to allow other modules to push extensions (custom native objects) into the context.
  This is controlled by javascript configuration and specific context (e.g. may be disabled when a message singleton context is created).
  
• Run the script

Example:

// Script run. Function call
Engine.debugName("name");
// Script run. Create a global variable
debug = Engine.debugEnabled();
// Script run. Check if some extension object named SomeObject was inserted into the context during script init
if (SomeObject.initialize)
    SomeObject.initialize();
// Function definition
function callback() {
    // code ...
}
// Script run. Set callback to process
Engine.setInterval(callback,1000);

WARNING: A runtime error (invalid function call ...) occurring during script run will fail script load. If context is a singleton one the callback won't be called.

Script (re)entry points

Entry points are functions called by javascript module:

• When a message handler is installed and it receives a message. See Message.install() and Message.installSingleton()
• When a timer was set and its interval elapsed. See Engine.setInterval() and Engine.setTimeout()
• When an installed event is triggered. See Engine.setEvent()
• When javascript module calls the onUnload function (this function is called when script is unloaded if defined in the context)
• When a message was enqueued and a callback was given. See Message.enqueue()
• When a message post hook is installed and it receives a message. See Message.installPostHook() and Message.installPostHookSingleton()
• When a message hook was installed. See Message.installHook()

Re-entry points are locations where context is unblocked and code execution is resumed after function call:

• Message dispatch(true)
• Engine.sleep(), Engine.usleep(), Engine.idle(), Engine.yield()
• Semaphore wait()
• DNS.query() requesting non blocking operation

On each (re)entry point the context mutex is locked.
The script context should be re-checked for variable presence.

WARNING:
A runtime error (invalid function call ...) occurring in entry point code will fail the callback function call.
Execution returns in C++ code regardless function call stack.
If entry point is a message handler false will be returned to caller.

Example:

function callback(msg) {
    var m = new Message("database");
    // set params ...
    var ok = m.dispatch(true);
    // The Engine object will no longer be available if script is unloaded during database query
    if (!Engine)
        return false;
    Engine.debug(Engine.DebugNote,"Some text");
}
Message.install(callback,"some_message_name");

Singleton context

A singleton context means a context created when handling a message and handler was installed using a singleton handler or processing a message singleton post hook.
The code is the same as the one of the script installing the handler or post hook.
Processing:

1. Initialize (see section above)
2. Call the callback function
3. Delete the singleton context

Example:

function callback() {
    // code ...
}
if (Engine.installSingleton) {
    // Context is run in main script
    Engine.debugName("test");
    Engine.debugLevel("level 10");
    debug = true;
    Message.installSingleton(callback,"test","some_message_name");
}
else {
    // Context is run in message handler: separate context. The javascript module will call the callback function after script init
    // Debug data (name, level) is automatically set by javascript module from main script
    debug = Engine.debugEnabled();
}

See also

• Javascript
• Javascript Message
• Javascript Engine