xptcall FAQ

  • Revision slug: xptcall_FAQ
  • Revision title: xptcall FAQ
  • Revision id: 140359
  • Created:
  • Creator: Pd
  • Is current revision? No
  • Comment /* Why does <tt>xptcall</tt> exist? */

Revision Content

What is <tt>xptcall</tt>?

<tt>xptcall</tt> is a small low level xpcom method call library. It is implemented using platform specific C/C and assembly language code. It is used to facilitate cross language and cross thread method calls. Porting this code is required in order to make mozilla run on any given platfrom.

Why does <tt>xptcall</tt> exist?

<tt>xptcall</tt> exists for two reasons:

  1. To support invoking arbitrary methods on xpcom interfaces.
  2. To support dynamically impersonating any xpcom interface.

Both of these facilities are required by XPConnect. These facilities are also used by <tt>xpcom/proxy</tt>. It may also be used by other subsystems in the future.

The <tt>xptcall</tt> approach was chosen over an approach that would have required generating stub code for calling and implementing all interfaces. Though the chosen approach requires some core platform specific code, it has minimal footprint and is extendable to work with any valid XPCOM interface without requiring additional per platform compiled code to be distributed.

What does <tt>xptcall</tt> really do?

The core invoke function has the declaration:

 XPTC_PUBLIC_API(nsresult)
 XPTC_InvokeByIndex(nsISupports* that, PRUint32 methodIndex, PRUint32 paramCount, nsXPTCVariant* params);

<tt>nsXPTCVariant</tt> is a discriminated union of the types that can be passed as parameters to the target function (including <tt>void*</tt> to represent arbitrary pointer types).

Given the correct set of params, this function can call any method on any XPCOM interface. XPConnect uses information from {{mediawiki.external('typelib_file.html typelib')}} files to reflect arbitrary XPCOM interfaces into JavaScript and to make calls from JavaScript to XPCOM using <tt>XPTC_InvokeByIndex</tt>. The information in the typelibs allows XPConnect to convert function params and build the <tt>nsXPTCVariant</tt> array required to make this call.

The stubs (or impersonation) facility of <tt>xptcall</tt> allows for implementing a class which can, at runtime, pretend to be any XPCOM interface. This is done by providing a vtbl full of generic function stubs in <tt>xptcall</tt>. These stubs forward calls to a shared function whose job it is to use the typelib information to extract the params from the platform specific calling convention to build an array of variants to hold the params and then call an inherited method which can then do whatever it wants with the call. This code also does the platform specific cleanup as the call returns.

This all works and is being used in mozilla today on numerous platforms.

Why can't <tt>xptcall</tt> just be implemented in C or C ?

Neither of these two facilities can be done in a fully cross platform way. Nor can they generally be done fully in C or C . Let's take them one at a time to see why.

The invoke facility requires code that can build and invoke an arbitrary call frame. The C compiler builds such call frames all the time. But the compiler builds frames customized at compile time for the specific signature of the callee. <tt>xptcall</tt> needs to be able to call any valid XPCOM method signature and it needs to specify this at runtime.

The stubs facility needs to impersonate the full vtbl full of methods for any given valid XPCOM interface (including ancestor methods). There are a few ways to do this. We could run the compiler at runtime and dynamically build and load stubs. Or, we could write a bunch of platform specific code to build interface specific vtbls and method stubs. The method I choose was to use a single large vtbl with a lot of small generic stubs. This minimizes the platform specific code as much as possible. Again, you just can't write code in C to do all this. The varargs stuff goes part way, but is just not enough.

If anyone has credible ideas about how to get the required functionality in a cross platform way and/or without resorting to assembly code I'd love to hear about it.

Is <tt>xptcall</tt> a platform requirement for mozilla?

Yes. Mozilla will not run properly without a functioning port of <tt>xptcall</tt>. Non-functional stub code exists to allow building <tt>xptcall</tt> on non-supported platforms. But any browser feature that relies on <tt>xpconnect</tt> will fail. Any platform that does not do <tt>xptcall</tt> is in trouble. We need to get moving on getting <tt>xptcall</tt> working everywhere!

What platforms are supported?

The growing list:

Where can I find other resources?

The code is at: http://lxr.mozilla.org/seamonkey/source/xpcom/reflect/xptcall

A new porting guide is at: http://lxr.mozilla.org/seamonkey/source/xpcom/reflect/xptcall/porting.html

Pre-implementation proposals are {{mediawiki.external('zero-generated-code-proposal.html here')}} and {{mediawiki.external('zero-ASM-proposal.html here')}}.


Author: John Bandhauer <jband@netscape.com>

Originally Published: 02 September 1999

Revision Source

<h3 name="What_is_xptcall.3F"> What is <tt>xptcall</tt>? </h3>
<p><tt>xptcall</tt> is a small low level xpcom method call library. It is implemented using platform specific C/C and assembly language code. It is used to facilitate cross language and cross thread method calls. Porting this code is required in order to make mozilla run on any given platfrom.
</p>
<h3 name="Why_does_xptcall_exist.3F"> Why does <tt>xptcall</tt> exist? </h3>
<p><tt>xptcall</tt> exists for two reasons:
</p>
<ol><li> To support invoking arbitrary methods on xpcom interfaces.
</li><li> To support dynamically impersonating any xpcom interface.
</li></ol>
<p>Both of these facilities are required by <a class="external" href="http://www.mozilla.org/scriptable/index.html">XPConnect</a>. These facilities are also used by <a class="external" href="http://www.mozilla.org/projects/xpcom/Proxies.html"><tt>xpcom/proxy</tt></a>. It may also be used by other subsystems in the future.
</p><p>The <tt>xptcall</tt> approach was chosen over an approach that would have required generating stub code for calling and implementing all interfaces. Though the chosen approach requires some core platform specific code, it has minimal footprint and is extendable to work with <b>any</b> valid XPCOM interface without requiring additional per platform compiled code to be distributed.
</p>
<h3 name="What_does_xptcall_really_do.3F"> What does <tt>xptcall</tt> really do? </h3>
<p>The core <i>invoke</i> function has the declaration:
</p>
<pre class="eval"> XPTC_PUBLIC_API(nsresult)
 XPTC_InvokeByIndex(nsISupports* that, PRUint32 methodIndex, PRUint32 paramCount, nsXPTCVariant* params);
</pre>
<p><tt>nsXPTCVariant</tt> is a discriminated union of the types that can be passed as parameters to the target function (including <tt>void*</tt> to represent arbitrary pointer types).
</p><p>Given the correct set of params, this function can call any method on any XPCOM interface. XPConnect uses information from {{mediawiki.external('typelib_file.html typelib')}} files to reflect arbitrary XPCOM interfaces into JavaScript and to make calls from JavaScript to XPCOM using <tt>XPTC_InvokeByIndex</tt>. The information in the typelibs allows XPConnect to convert function params and build the <tt>nsXPTCVariant</tt> array required to make this call.
</p><p>The <i>stubs</i> (or impersonation) facility of <tt>xptcall</tt> allows for implementing a class which can, at runtime, pretend to be <b>any</b> XPCOM interface. This is done by providing a vtbl full of generic function stubs in <tt>xptcall</tt>. These stubs forward calls to a shared function whose job it is to use the typelib information to extract the params from the platform specific calling convention to build an array of variants to hold the params and then call an inherited method which can then do whatever it wants with the call. This code also does the platform specific cleanup as the call returns.
</p><p><b>This all works and is being used in mozilla today on <a class="external" href="http://lxr.mozilla.org/seamonkey/source/xpcom/reflect/xptcall/status.html">numerous platforms</a>.</b>
</p>
<h3 name="Why_can.27t_xptcall_just_be_implemented_in_C_or_C_.3F"> Why can't <tt>xptcall</tt> just be implemented in C or C ? </h3>
<p>Neither of these two facilities can be done in a fully cross platform way. Nor can they generally be done fully in C or C . Let's take them one at a time to see why.
</p><p>The <i>invoke</i> facility requires code that can build and invoke an arbitrary call frame. The C compiler builds such call frames all the time. But the compiler builds frames customized <i>at compile time</i> for the specific signature of the callee. <tt>xptcall</tt> needs to be able to call <b>any</b> valid XPCOM method signature and it needs to specify this at runtime.
</p><p>The <i>stubs</i> facility needs to impersonate the full vtbl full of methods for any given valid XPCOM interface (including ancestor methods). There are a few ways to do this. We could run the compiler at runtime and dynamically build and load stubs. Or, we could write a bunch of platform specific code to build interface specific vtbls and method stubs. The method I choose was to use a single large vtbl with a lot of small generic stubs. This minimizes the platform specific code as much as possible. Again, you just can't write code in C to do all this. The varargs stuff goes part way, but is just not enough.
</p><p>If anyone has credible ideas about how to get the required functionality in a cross platform way and/or without resorting to assembly code I'd love to hear about it.
</p>
<h3 name="Is_xptcall_a_platform_requirement_for_mozilla.3F"> Is <tt>xptcall</tt> a platform requirement for mozilla? </h3>
<p>Yes. Mozilla will not run properly without a functioning port of <tt>xptcall</tt>. Non-functional stub code exists to allow building <tt>xptcall</tt> on non-supported platforms. But any browser feature that relies on <tt>xpconnect</tt> will fail. Any platform that does not do <tt>xptcall</tt> is in trouble. We need to get moving on getting <tt>xptcall</tt> working everywhere!
</p>
<h3 name="What_platforms_are_supported.3F"> What platforms are supported? </h3>
<p>The growing list:
</p>
<ul><li> <a class="external" href="http://lxr.mozilla.org/seamonkey/source/xpcom/reflect/xptcall/status.html">Porting Status</a>
</li></ul>
<h3 name="Where_can_I_find_other_resources.3F"> Where can I find other resources? </h3>
<p>The code is at: http://lxr.mozilla.org/seamonkey/source/xpcom/reflect/xptcall
</p><p>A new porting guide is at: http://lxr.mozilla.org/seamonkey/source/xpcom/reflect/xptcall/porting.html
</p><p>Pre-implementation proposals are {{mediawiki.external('zero-generated-code-proposal.html here')}} and {{mediawiki.external('zero-ASM-proposal.html here')}}.
</p>
<hr>
<p><b>Author:</b> <a class="external" href="mailto:jband@netscape.com">John Bandhauer &lt;jband@netscape.com&gt;</a>
</p><p><b>Originally Published:</b> 02 September 1999
</p>
Revert to this revision