xptcall FAQ

What is xptcall?

xptcall 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 platform.

Why does xptcall exist?

xptcall 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 xpcom/proxy. It may also be used by other subsystems in the future.

The xptcall 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 xptcall really do?

The core invoke function has the declaration:

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

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

Given the correct set of parameters, this function can call any method on any XPCOM interface. XPConnect uses information from typelib files to reflect arbitrary XPCOM interfaces into JavaScript and to make calls from JavaScript to XPCOM using XPTC_InvokeByIndex. The information in the typelibs allows XPConnect to convert function parameters and build the nsXPTCVariant array required to make this call.

The stubs (or impersonation) facility of xptcall 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 xptcall. These stubs forward calls to a shared function whose job it is to use the typelib information to extract the parameters from the platform specific calling convention to build an array of variants to hold the parameters 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 xptcall 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. xptcall 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 xptcall a platform requirement for Mozilla?

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

What platforms are supported?

The growing list:

• Porting status

Where can I find other resources?

The code is at: xpcom/reflect/xptcall

A new porting guide is at: https://developer.mozilla.org/En/Xptcall_Porting_Guide 

Pre-implementation proposals are here and here.