View source for Javascript script load and execution


== Code and context (data) ==

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


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


== 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''', '''JPath''', ...)
** Standard Javascript functions ('''parseInt''', '''isNaN''', ...)
** Yate objects ('''Engine''', '''Message''', '''ConfigFile''' ...)
* Dispatch a ''script.init'' message to allow other modules to push extensions (custom native objects) into the context.<br/>This is controlled by javascript configuration and specific context (e.g. may be disabled when a message singleton context is created).<br/>
* 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.'''

== 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.<br/>
The code is the same as the one of the script installing the handler or post hook.<br/>
Processing:<br/>
# Initialize (see section above)
# Call the callback function
# 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();
 }

== Script (re)entry points ==

Entry points are functions called by javascript module:<br/>
* 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:<br/>
* Message dispatch(true)
* Engine.sleep(), Engine.usleep(), Engine.idle(), Engine.yield()
* Semaphore wait()
* DNS.query()


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


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

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");

== See also ==

* [[Javascript]]
* [[Javascript Message]]
* [[Javascript Engine]]

[[Category:Javascript]] [[Category:Programmers]] [[Category:Scripting]]