Virtual method dispatch through the vtable
Status: implemented in tools/gen-bindings/ (vtable.js, clang.js,
ir.js, emit/classes.js). Scope: the C++ classes that
tools/gen-bindings.js emits (see classesCode() and
TODO.md, "gen-bindings C++ gaps" item 1). Tests:
tests/test-gen-bindings-virtual.js on tests/cxx/virt.{hpp,cpp}.
1. Problem
Binding a method's own symbol makes every call a non-virtual
(Class::method()-qualified) call:
const s = new geo_Shape(3, 2.0);
geo_Base.from(s.ptr).area(); // would call Base::area, not Shape::areaC++ would call Shape::area here. Any wrapper whose static type is a base
class (at()/from() on a pointer returned by a factory, or an inherited
method) would run the wrong code, and .delete() through a base wrapper the
wrong destructor. A pure virtual has no symbol at all, and a virtual that is
inline or never instantiated has no exported symbol, so binding it fails with
"symbol not found". Calling through the vtable fixes all three.
2. ABI facts (Itanium, x86-64 Linux)
Checked against tests/cxx/shapes.{hpp,cpp} compiled with clang++ -std=c++17
(a small C++ program that dlsyms the symbols and reads the vptr):
| Fact | Evidence |
|---|---|
| The vptr is the first 8 bytes of a polymorphic object (offset 0) | *(void***)&shape is the vptr |
vptr == &_ZTV<class> + 16 (skips offset-to-top and RTTI) | printed vptr - _ZTV = 16 |
vptr[n] is the n-th virtual slot; a destructor takes two consecutive slots, [complete] then [deleting] | Shape: vptr[0] = D1, vptr[1] = D0, vptr[2] = area |
| A slot holds the final overrider's function | vptr[2] of a Shape is Shape::area, and calling it on the object returned 6 |
A pure virtual's slot holds __cxa_pure_virtual | Base's vptr[2] equals dlsym("__cxa_pure_virtual") |
| A subclass's slots start with the base's, so a base-class index is valid for every subclass | PC : C : B : A: f, g(int), g(double) keep their indices |
clang's JSON AST does not reliably say which methods are virtual: an
overrider carries only an OverrideAttr child and no "virtual": true, and one
written without virtual/override has no marker at all. So the slot numbers
come from the compiler's own vtable dump, not from the AST.
3. Where the slot index comes from
clang lays a class's vtable out, and prints it with `-Xclang
-fdump-vtable-layouts, only once code needs it. runLayoutDump() (clang.js`)
already compiles a probe translation unit for the record layouts; for every
polymorphic class it adds code that makes clang lay the vtable out, and the
compile then goes to LLVM IR (-S -emit-llvm -o /dev/null) instead of
-fsyntax-only, only if there is such a class. The dump goes to stdout, with
the layouts.
Each polymorphic class gets, tried in this order of need:
p->~C()in a function, when the destructor is public: lays the vtable out if the destructor is virtual (declared so or inherited).auto m = &C::f;for a method the AST flagsvirtualor pure whose name is not overloaded.A key-function probe, only when neither of those can work (overloaded virtuals only, and a destructor that is not virtual or not public):
typedef class ns::C __gbc0; struct __gbk0 : __gbc0 { virtual void __gb_key(); }; void __gbk0::__gb_key() {}The out-of-line
__gb_keyis the class's key function, so clang emits the whole vtable. This works for abstract classes and protected destructors. Afinalclass cannot be derived from, and the error would lose the whole dump, so it gets no key probe (the AST condenser keepsFinalAttrfor this) and keeps binding its own symbols.
parseVtableIndices() (vtable.js) reads the VTable indices for 'C' blocks
that 1 and 2 give: the methods the class itself declares, overriders included,
each with its index relative to the vptr. parseVtableBlocks() reads the
Vtable for '__gbkN' block of 3, which lists every slot, inherited ones too, as
<row> | <return type> <Qualifier::name>(<params>)[ const]; the index is **row
- 2** (rows 0 and 1 are offset-to-top and RTTI), and rows naming another class
are ignored when the methods are matched.
The result is layouts[...].vtableIndices, cached with the AST
(AST_CACHE_VERSION).
3.1 Matching entries to methods
assignVtableSlots() gives a method of the class vtableSlot when its entry is
found by name, number of parameters and constness. Overloads of one arity (a
f(int) and an f(double)) are told apart by their parameter types: the
entry's, normalized, against the AST's ParmVarDecl types (as written, and with
typedefs resolved). A method without exactly one match keeps its own symbol:
a wrong slot would call the wrong function. The complete-object destructor entry
becomes destructor.vtableSlot.
3.2 IR
vtableSlot: n (vptr[n]) on each virtual method, whether the AST flags it or
not; destructor.vtableSlot (the [complete] slot). virtual and pure stay
as the AST has them. A class without a vtable dump (final, or a failed probe)
has none, and binds as before.
4. Generated JS
A virtual method's overload entry calls through
__virtual(slot, spec) instead of a CFunction on its symbol:
function __virtual(slot, spec) {
const cache = new Map();
return (self, ...args) => {
const vptr = new DataView(self).getBigUint64(0, true);
// fp = vptr[slot]
// cache.get(fp) or a new CFunction({ ptr: fp, ...spec }); f(self, ...args)
};
}- Cost. One small
toArrayBufferview per call and a cachedCFunctionper distinct overrider. A native fast path (CFunction({ vtableIndex })inffi.c, readingthis->vptr[index]per call) would remove the view; it is not done, and only worth it if a benchmark shows the JS path matters. - No symbol needed. A virtual method is never
dlsymed, so pure, inline and uninstantiated virtuals work, and an abstract class's methods are callable on instances of its subclasses. - Destructor.
.delete()callsvptr[destructor.vtableSlot]when there is one, so deleting through a base wrapper runs the derived destructor. The[deleting]slot (+ 1) is never used: it would also free the memory, which an ownedArrayBuffermust not do. - Single inheritance. Slots of a primary base share
this, so no adjustment is needed. A secondary base's slots point atthis-adjusting thunks and need the subobject pointer: part of multiple inheritance, still out of scope. - Objects without a vptr.
newalready refuses to zero-fill a polymorphic class.at(ptr)on memory that is not a live object reads a garbage vptr; that is not guarded. A zero vptr throws. - Explicitly qualified calls (
Base::f()from a subclass) are the old behavior and are not exposed; if wanted, asClass.prototype.f.nonVirtualrather than the default.
5. Tests
tests/test-gen-bindings-virtual.js, with tests/cxx/virt.{hpp,cpp}:
| Test | Asserts |
|---|---|
| IR slots | an overrider has its base's slot, overloads have two, a plain or static method none, the implicit destructor of Bird has one |
| override through a base wrapper, a pure virtual, a native caller, an object made in JS | Animal.at(make_animal(1)).legs() === 4, Bird gives 2 |
three levels, an override without virtual/override | Puppy::sound() through Animal |
| inline virtual | inline_only() works, with no exported symbol |
| overloads of one arity, protected destructor | Guarded::f(int) / f(double), found by the key-function probe |
final class | no probe, own symbols, the other classes unaffected |
| non-virtual stays static | describe() is bound to its symbol, legs() is not |
| destructors | deleting through Animal runs Dog's; Bird's inherited one runs; a deleted object cannot be called |
6. Remaining work
Not done, in the order worth doing them. Each is independent.
| # | Step | Verify |
|---|---|---|
| 1 | Say when a virtual method is left on its symbol (done: a warning, as planned, not an error). unslottedVirtuals() in vtable.js lists the virtual or pure methods of a class that is not final and has no slot, with why (no dump, or the dump cannot tell it from another method of the same name, count and constness); they go to ir.warnings, are printed by main.js and noted at the end of the module. A final class has none. The check on real input is that virt.hpp gives none | tests/test-gen-bindings-virtual.js: a class entry with a virtual method and no slot gives the warning and a slotted one does not |
| 2 | IR slots equal the compiler's. A test that compiles virt.cpp with -fdump-vtable-layouts itself and compares every vtableSlot in the IR with the row the dump gives (the check the original plan wanted, so a change in clang's output or in methodOf() fails loudly) | the test fails if assignVtableSlots() is made to add 1 |
| 3 | Native fast path. CFunction({ vtableIndex: n, args, returns }) in ffi.c reads this->vptr[n] on every call and reuses one cif, dropping the per-call toArrayBuffer view and the Map. Needs a benchmark first (10^6 calls of legs() through __virtual() against a plain CFunction); a change to the C module, so its own review and tests in tests/test-c-function.js | the benchmark shows a difference worth the extra API |
| 4 | Multiple inheritance. A secondary base's slots point at this-adjusting thunks and need the subobject pointer (BaseOffsets, TODO.md "gen-bindings C++ gaps" item 1). The vtable dump already lists those slots | out of scope until the base offsets are captured |
Not planned: calling Base::f() explicitly from a subclass wrapper (the old,
non-virtual behavior); if it is wanted, as Class.prototype.f.nonVirtual.