View source for Breaking the grip JS has on the DOM

We care more about speed now. See {{bug|570738}}.

----

We want to change the grip JS has on the DOM and on XUL.  We will do this in 2 steps:

* Change the framework to be language neutral - https://bugzilla.mozilla.org/show_bug.cgi?id=255942
* Create a Python implementation.

This work is currently being done on a DOM_AGNOSTIC2_BRANCH cvs branch (note the 2 in the branch name!).  The initial work on this, including a Python implementation is largely complete.  This document attempts to capture the current state of this work, including any issues not yet addressed.

== Description of changes - both already made and yet to be made ==

=== Overview ===

A [[#new interface nsILanguageRuntime]] will be implemented for each language.  It is a singleton (JS will be manually instantiated, but all other languages will be services).  <tt>nsDOMScriptObjectFactory</tt> will become the factory for these <tt>nsILanguageRuntime</tt>s, with the language runtime taking responsibility for creating the <tt>nsIScriptContext</tt>.
    
The existing <tt>nsIScriptContext</tt> interface will remain tied to a specific language.  The <tt>void *</tt> params in its interface will remain.  This means that a <tt>void *</tt> and a suitable <tt>nsIScriptContext</tt> must always be treated as a pair (ie, given just a <tt>void *</tt>, there is no way to determine an appropriate <tt>nsIScriptContext</tt> suitable for it.  See [[#nsIScriptContext]]

<tt>nsIProgrammingLanguage</tt> constants will internally identify a language offering an efficient array-based implementation for multiple languages.  The <tt>nsIDOMScriptObjectFactory</tt> will be able to convert language names to IDs and will be responsible for instantiating new language runtimes.

The existing <tt>nsIScriptGlobalObject</tt> interface will move towards a model where there is a global <tt>nsIScriptContext</tt> per language.  <tt>GetGlobalJSObject</tt> and <tt>GetContext</tt> hav largely been replaced with <tt>GetLanguageGlobal</tt> and <tt>GetLanguageContext</tt> methods (hard-coding <tt>nsIProgrammingLanguage::JAVASCRIPT</tt>) where necessary.  Thus, <tt>nsIScriptGlobalObject</tt> may have many <tt>nsIScriptContext</tt>s associated with it (one per supported and initialized language).  The script global itself is responsible for preparing itself to work with a specific language, but will only do so via an explicit request to <tt>EnsureScriptEnvironment()</tt> for a language.  See [[#nsIScriptGlobalObject and nsGlobalWindow]]

A new context stack may need to be invented - see [[#Context Stack]]

The special casing for js in <tt>nsDOMClassInfo</tt> will need a fair bit of work for each language - see [[#nsDOMClassInfo]]

Below are specific implementation notes:

=== Array and Variant object model changes ===

* <tt>nsIArray</tt> to be used in place of <tt>jsval</tt> argc/argv used now.  There is a new <tt>nsJSArgArray</tt> object that "wraps" a <tt>jsval *argv/int argc</tt> pair into an <tt>nsIArray</tt> - but also support a private interface for getting the original <tt>jsval</tt> based array.  Thus, js->js calls do not convert elements in the array - (offering both performance and no conversion issues), but they are converted when <tt>nsIArray</tt> methods are directly used (eg, when another language sees the array).

* Each of these <tt>nsIArray</tt> elements params are expected to hold either an <tt>nsIVariant</tt> or an <tt>nsISupportsPrimitive</tt>.

* Result values from calling scripts are now nsIVariant.  This is currently used only for the "return value" of an event handler, and only boolean and string result values are handled.  If may be more efficient to convert this to use <tt>nsISupportsPrimitive</tt> (but xpconnect already provided <tt>nsIVariant</tt> converters).

=== new interface nsILanguageRuntime ===

This is a factory for nsIScriptContext objects and has methods for parsing "version strings" into a version integer specific to the language.

nsJSEnvironment implements this interface and becomes the JS factory (and renamed to nsJSRuntime).  Public function for creating JSContext replaced with public function for the nsJSRuntime.

All memory management/object ownership related functions will exist on the language runtime.  This is so a language object can be locked or unlocked without having an nsIScriptContent - all it needs is the integer language ID so it can fetch the nsILanguageRuntime to perform the operation.  Currently these are defined in terms of the JS GC API (and hence ignored by Python), but this will change to a more language neutral technique.

=== nsIScriptContext ===

* The ownership model of the <tt>void *</tt> objects returned from <tt>nsIScriptContext</tt> must be clarified and made more explicit.  MarkH is working on this.

* Existing <tt>JSObject</tt> replaced with <tt>void</tt>.  JS implementation still returns a <tt>JSObject</tt>, but that implementation detail is hidden inside the script context itself.

* Existing <tt>char *version</tt> replaced with <tt>PRUint32 version</tt>.  New method on <tt>nsILanguageRuntime</tt> to convert a <tt>char * version</tt> string into the flags.

* New <tt>ClearScope</tt> method - JS implementation does the <tt>ClearScope/ClearWatchpointsForObject/ClearRegExpStatistics</tt> dance.

* As described above, <tt>nsIArray</tt> and <tt>nsIVariant</tt> used to make language args and result values agnostic..

* <tt>CompileEventHandler</tt> now takes an array of arg names - this is because the <tt>onerror</tt> event takes 3 params.  <tt>nsContentUtils::GetEventArgName()</tt> renamed to <tt>GetEventArgNames()</tt> with params changed accordingly, and returns 3 names for 'onerror'.

* A new <tt>SetProperty</tt> method has been added, currently used only to set <tt>window.arguments</tt>.  Note that <tt>BindCompiledEventHandler()</tt> changes make these 2 functions almost identical in concept, so these could possibly be merged.  Alternatively, now we use <tt>nsIArray</tt> for window arguments, we could possibly add <tt>arguments</tt> as an XPCOM property on the DOM object itself, meaning <tt>SetProperty()</tt> could go away.

* <tt>SetTerminationFunction</tt> needs thinking through - this does *not* seem to be a per-language thing, but is used only for JS GC, so that the script global is notified when the JS global object is collected.  This needs more thinking through, or possibly just moved privately inside the JS implementation.

* New method <tt>void *GetNativeGlobal()</tt> to return the "global object" used by <tt>nsIScriptGlobalWindow</tt> (previously stored in <tt>mJSObject</tt>) for this context.  <tt>nsIScriptGlobalObject</tt> calls this method during language init to setup its environment.

* New <tt>Serialize</tt> and <tt>Deserialize</tt> methods added with <tt>nsXULPrototypeScript</tt> delegating to these.

=== nsIScriptGlobalObject and nsGlobalWindow ===

<tt>nsGlobalWindow</tt> is the main implemention of <tt>nsIScriptGlobalObject</tt>, but XUL and XBL have a few.

* <tt>nsIScriptGlobalObject</tt> remains a single object (ie, not per language).  It keeps an array of <tt>nsIScriptContext</tt> objects and <tt>void *</tt> globals for each supported language.  Methods <tt>GetContext</tt> and <tt>GetGlobalJSObject</tt> have been replaced with <tt>GetLanguageContext</tt> and <tt>GetLanguageGlobal</tt>, both of which take the language ID as a param.  The places still tied to JS explicitly pass <tt>nsIProgrammingLanguage::JAVASCRIPT</tt> when necessary.

* New method <tt>EnsureScriptEnvironment(PRUint32 langID)</tt> to ensure the <tt>nsIScriptGlobalObject</tt> is initialized for a specific language.  This may be called at any time - whenever someone needs to run a script in a language.

* nsGlobalWindow still has some complicated JS specific code in place - most notably in <tt>SetNewDocument</tt>.  Some of these subtleties must also be done for other languages - but these have not yet been done in the hope of keeping the patch as small and "obviously correct" as possible.

* A new interface <tt>nsIScriptTimeoutHandler</tt> has been created.  This abstracts most of the JS specific code related to timeouts and intervals.  The core logic in nsGlobalWindow relating to timeouts has not changed at all.  The JS specific code that remains in nsGlobalWindow should probably be relocated into a JS specific file to help keep the size of nsGlobalWindow.cpp down.

=== XUL Fastload Cache ===

* XUL cache now stores and returns both a <tt>void *</tt> and a <tt>PRUint32 langID</tt>.  As described in [[#new interface nsILanguageRuntime]], this language ID is enough to perform the necessary ownership management of objects in the cache.

* Serializing scripts is supported by first writing the language ID to the stream, then delegating to the (new) <tt>nsIScriptContext::Serialize()</tt> method.  Deserialization then reads this language ID to determine the appropriate nsIScriptContext to delegate to.

* Note that fast-load is fragile in the face of errors; more work is needed to ensure things work for script languages that do not support fast-load. This is not currently a problem as Python does implement this functionality.  This fragility did previously exist - it is just more open to failing when multi-languages are considered.

=== nsDOMClassInfo ===

nsDOMClassInfo provides 2 key functions:

* standard nsIClassInfo implementations for DOM.

* Enhanced support for DOM objects which can not be expressed using nsIClassInfo.  These are the "scriptable helpers"

The extra nsIClassInfo implementation is suitable for all languages.  However, the scriptable helpers have lots of DOM namespace magic, and are very JS specific.  This functionality currently needs to be re-implemented for Python.

Widgets implemented in XBL do not have any class info available.  This works in JavaScript as the widgets themselves are implemented by JS, and therefore all methods and properties exist as native JS properties.  Thus, JS does not use XPConnect to talk to XBL implemented widgets.  Python has currently worked around this by hardcoding mapping between a XUL tag name and a list of interfaces that should be implemented.  This should be addressed in XBL 1.5/2.0.


=== Context Stack ===

[MarkH - I've managed to completely ignore this for the time being]

Existing code that works directly with the nsIJSContextStack "@mozilla.org/js/xpc/ContextStack;1" service must be modified to be language agnostic.  These callers may be unaware of the language being used, or the set of language available.  Therefore, the nsIScriptGlobalObject interface will grow a way to generically push and pop contexts for *all* languages.  It will probably not be possible to explicitly push a context for only a single language, as that will muddy the semantics.
	
Exactly what this means is still TDB, but there are a few possibilities:
* We invent a new interface for each language to do its thing.
* We simple push nsIScriptContext objects directly on a stack - we push a context for every language known to us.

If a language is initialized even after items are already on the context stack, only new items pushed will include a context item for that language.  Once the stack pops back past where a language has no entries, the language will not be able to run (but this should be impossible - there can be no stack entries for that language higher in the context stack, and attempting to start a new script in that language will simply re-push a context entry which will again include the language)

As mentioned above re nsIScriptContext, we may need to handle SetTerminationFunction functionality on this stack.

Tricky: We need to interoperate with code that is not multi-language nor nsIScriptGlobalObject aware, and may not be for some time.  Eg:
http://lxr.mozilla.org/seamonkey/source/extensions/pref/autoconfig/src/nsJSConfigTriggers.cpp#216
http://lxr.mozilla.org/seamonkey/source/extensions/webservices/security/src/nsWebScriptsAccess.cpp#767 - pushes a NULL context?

Generic "GetCallerDocShell" or similar will avoid some JS specifics - eg, http://lxr.mozilla.org/seamonkey/source/docshell/base/nsDocShell.cpp#6092

Possible implementation strategy:

==== New interface - nsIDOMContextStackItem ====
An item on the context stack - stores one nsIScriptContext for every language initialized for this item.

nsIDOMContextStackItem : nsISupports
{
  nsIScriptContext getLanguageContext(in PRInt32 langId);
  void setLanguageContext(in PRInt32 langId, in nsIScriptContext cx);
};

==== New interface - nsIDOMContextStack ====

interface nsIDOMContextStack : nsISupports
{
  readonly attribute PRInt32     count;
  nsIDOMContextStackItem      peek();
  nsIDOMContextStackItem      pop();
  void                                   push(in nsIDOMContextStackItem cx);

  /* what is a "safe context" anyway??? 
   * - a context guaranteed to be available and usable.
   */
  nsIScriptContext getLanguageSafeContext(in PRInt32 langId);
  
  /* A helper for code that wants the most recent nsIDocShell on
  the context stack - any/all languages on the stack can provide it */
  nsIDocShell GetCallerDocShell()
};

=== Exceptions ===

Exceptions should be chained across languages.  This should just mean diligent use of nsIExceptionService?  This has not been addressed yet.