~ubuntu-branches/ubuntu/gutsy/virtualbox-ose/gutsy

following on each platform (from <a href="http://lxr.mozilla.org/mozilla/source/xpcom/reflect/xptcall/public/xptcall.h#131">xptcall/public/xptcall.h</a>):

<pre>

XPTC_PUBLIC_API(nsresult)

XPTC_InvokeByIndex(nsISupports* that, PRUint32 methodIndex,

PRUint32 paramCount, nsXPTCVariant* params);

</pre>

Calling code is expected to supply an array of <code>nsXPTCVariant</code>

structs. These are discriminated unions describing the type and value of each

parameter of the target function. The platform specific code then builds a call

frame and invokes the method indicated by the index <code>methodIndex</code> on

the xpcom interface <code>that</code>.

Here are examples of this implementation for

and

<a href="http://lxr.mozilla.org/mozilla/source/xpcom/reflect/xptcall/src/md/unix/xptcinvoke_unixish_x86.cpp">Linux x86, NetBSD x86, and FreeBSD</a>.

Both of these implementations use the basic strategy of: figure out how much

stack space is needed for the params, make the space in a new frame, copy the

params to that space, invoke the method, cleanup and return. C++ is used where

appropriate, Assembly language is used where necessary. Inline assembly language is used here,

but it is equally valid to use separate assembly language source files. Porters

can decide how best to do this for their platforms.

The stubs functionality is more complex. The goal here is a class

whose vtbl can look like the vtbl of any arbitrary xpcom interface. Objects of

this class can then be built to impersonate any xpcom object. The base interface

for this is (from <a href="http://lxr.mozilla.org/mozilla/source/xpcom/reflect/xptcall/public/xptcall.h#109">xptcall/public/xptcall.h</a>):

<pre>

class nsXPTCStubBase : public nsISupports

{

public:

// Include generated vtbl stub declarations.

// These are virtual and *also* implemented by this class..

#include "xptcstubsdecl.inc"

// The following methods must be provided by inheritor of this class.

// return a refcounted pointer to the InterfaceInfo for this object

// NOTE: on some platforms this MUST not fail or we crash!

NS_IMETHOD GetInterfaceInfo(nsIInterfaceInfo** info) = 0;

// call this method and return result

100

NS_IMETHOD CallMethod(PRUint16 methodIndex,

101

const nsXPTMethodInfo* info,

102

nsXPTCMiniVariant* params) = 0;

103

};

104

</pre>

105

106

Code that wishes to make use of this stubs functionality (such as

107

<a href="http://www.mozilla.org/scriptable/">XPConnect</a>) implement a class

108

which inherits from <code>nsXPTCStubBase</code> and implements the

109

<code>GetInterfaceInfo</code> and <code>CallMethod</code> to let the

110

platform specific code know how to get interface information and how to dispatch methods

111

once their parameters have been pulled out of the platform specific calling

112

frame.

113

114

115

116

Porters of this functionality implement the platform specific code for the

117

stub methods that fill the vtbl for this class. The idea here is that the

118

class has a vtbl full of a large number of generic stubs. All instances of this

119

class share that vtbl and the same stubs. The stubs forward calls to a platform

120

specific method that uses the interface information supplied by

121

the overridden <code>GetInterfaceInfo</code> to extract the parameters and build

122

an array of platform independent <code>nsXPTCMiniVariant</code> structs which

123

are in turn passed on to the overridden <code>CallMethod</code>. The

124

platform dependent code is responsible for doing any cleanup and returning.

125

126

127

128

The stub methods are declared in <a

129

href="http://lxr.mozilla.org/mozilla/source/xpcom/reflect/xptcall/public/xptcstubsdecl.inc">xptcall/public/xptcstubsdecl.inc</a>.

130

These are '#included' into the declaration of <code>nsXPTCStubBase</code>. A

131

similar include file (<a

132

href="http://lxr.mozilla.org/mozilla/source/xpcom/reflect/xptcall/public/xptcstubsdef.inc">xptcall/public/xptcstubsdef.inc</a>)

133

is expanded using platform specific macros to define the stub functions. These

134

'.inc' files are checked into cvs. However, they can be regenerated as necessary

135

(i.e. to change the number of stubs or to change their specific declaration)

136

using the Perl script <a

137

href="http://lxr.mozilla.org/mozilla/source/xpcom/reflect/xptcall/public/genstubs.pl">xptcall/public/genstubs.pl</a>.

138

139

140

141

Here are examples of this implementation for <a

142

href="http://lxr.mozilla.org/mozilla/source/xpcom/reflect/xptcall/src/md/win32/xptcstubs.cpp">Win32</a>

143

and <a

144

href="http://lxr.mozilla.org/mozilla/source/xpcom/reflect/xptcall/src/md/unix/xptcstubs_unixish_x86.cpp">Linux x86, NetBSD x86, and FreeBSD</a>.

145

Both of these examples use inline assembly language. That is just how I

146

decided to do it. You can do it as you choose.

147

148

149

150

The Win32 version is somewhat tighter because the __declspec(naked) feature

151

allows for very small stubs. However, the __stdcall requires the callee to clean

152

up the stack, so it is imperative that the interface information scheme allow

153

the code to determine the correct stack pointer fixup for return without fail,

154

else the process will crash.

155

156

157

158

I opted to use inline assembler for the gcc Linux x86 port. I ended up with

159

larger stubs than I would have preferred rather than battle the compiler over

160

what would happen to the stack before my asm code began running.

161

162

163

164

I believe that the non-assembly parts of these files can be copied and reused

165

with minimal (but not zero) platform specific tweaks. Feel free to copy and

166

paste as necessary. Please remember that safety and reliability are more

167

important than speed optimizations. This code is primarily used to connect XPCOM

168

components with JavaScript; function call overhead is a tiny part of the

169

time involved.

170

171

172

173

I put together

174

175

href="http://lxr.mozilla.org/mozilla/source/xpcom/reflect/xptcall/src/md/test">xptcall/src/md/test

176

</a> as a place to evolve the basic functionality as a port is coming together.

177

Not all of the functionality is exercised, but it is a place to get started.

178

179

href="http://lxr.mozilla.org/mozilla/source/xpcom/reflect/xptcall/tests">xptcall/tests

180

</a> has an api level test for <code>XPTC_InvokeByIndex</code>, but no tests for

181

the stubs functionality. Such a test ought to be written, but this has not

182

yet been done.

183

184

185

186

A full 'test' at this point requires building the client and running the

187

XPConnect test called TestXPC in

188

189

href="http://lxr.mozilla.org/mozilla/source/js/src/xpconnect/tests">mozilla/js/src/xpconnect/tests

190

</a>.

191

192

193

194

Getting these ports done is very important. Please let <a

195

href="mailto:jband@netscape.com">me</a> know if you are interested in doing one.

196

I'll answer any questions as I get them.

197

198

199

200

201

href="http://lxr.mozilla.org/mozilla/source/xpcom/reflect/xptcall/status.html">

202

Porting Status

203

</a>

204

205

</blockquote>

206

207

<hr>

208

Author: <a href="mailto:jband@netscape.com">John Bandhauer <jband@netscape.com></a>

209

Last modified: 31 May 1999

210

211

</body>

212

</html>

Older »