Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
67 changes: 63 additions & 4 deletions docs/cpp-classes.md
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,8 @@ virtual only as in C++:

| Method | What it is |
| --- | --- |
| `@virtual name(...): T;` | a C++ virtual method, whose slot the compiler numbers for the target (see "One binding for every target") |
| `@destructor name(): void;` | the C++ virtual destructor: one slot under MSVC, two under the Itanium ABI; it can't be called |
| `@slot(N) name(...): T;` | a C++ virtual method: slot N of the vtable, counted from 0 with the base classes' slots |
| `name(...): T;` overriding a base class's `@slot` method | the same slot, as in C++ (`@slot` may be repeated, with the same number) |
| `@linkname("symbol") name(...): T;` | a C++ non-virtual method, called by its (mangled) symbol as `symbol(this, args...)` |
Expand All @@ -61,6 +63,55 @@ reads the same. (A class whose virtual methods have bodies is the other way roun
Fields declared on the class are the C++ object's fields after the vtable pointer, laid out like
a tuple's.

## One binding for every target: `@virtual`

`@slot(N)` numbers are the target's: MSVC and the Itanium ABI (g++, clang on Linux, macOS,
MinGW) lay out the same C++ class differently. With `@virtual`, the compiler numbers the slots
itself, as the target's C++ compiler does, so one `.ts` file serves every target:

```ts
@cpp
class Shape { // class Shape {
@destructor destroy(): void; // virtual ~Shape();
@virtual area(): s32; // virtual int area() = 0;
@virtual scale(by: s32): void; // virtual void scale(int by) = 0;
@virtual scale(by: f64): void; // virtual void scale(double by) = 0;
} // };

@cpp
class Circle extends Shape { // class Circle : public Shape {
@virtual radius(): s32; // virtual int radius();
@virtual area(): s32; // int area() override;
} // };
```

| | MSVC | Itanium |
| --- | --- | --- |
| a base class's slots | first | first |
| a virtual destructor | one slot (the scalar deleting destructor) | two slots (the complete and the deleting destructor) |
| overloads of one name | together, where the first is declared, in reverse declaration order | in declaration order |
| a method with the name and parameter types of a base class's virtual method | that method's slot (an override) | the same |

Above, MSVC gives `Shape` the slots `~Shape` 0, `area` 1, `scale(double)` 2, `scale(int)` 3, and
the Itanium ABI `~Shape` 0 and 1, `area` 2, `scale(int)` 3, `scale(double)` 4. `Circle.radius` is
4 under MSVC and 5 under Itanium, and `Circle.area` keeps `Shape.area`'s slot on both.

So a class using `@virtual` declares **every** virtual method it adds, in the C++ header's order,
the protected and private ones too (a slot left out shifts the next ones); `tsbindgen
--virtual-slots` writes it that way. The rules:

- a class numbers its new virtual methods with `@virtual` or with `@slot(N)`, not both (an
override may still name its base class's slot with `@slot(N)`);
- the base class's slots must all be known: its own virtual methods are `@virtual`, or it says
how many slots it has with `@vtablesize(N)` on the class (for a base bound by hand with
`@slot(N)`, which may leave slots out);
- `@slot(N)` still works as before, and wins over `@virtual` on the same method: the escape for a
vtable no rule above describes.

A `@cpp` class exported from a module carries its slots, its `@destructor` and its
`@vtablesize(N)` in its declarations, so an importing module can extend it with `@virtual`
methods of its own.

## Rules

The compiler rejects anything that would add a slot, run code of its own, or ask the object what
Expand All @@ -69,9 +120,12 @@ errors and not warnings.

| Not allowed | Why |
| --- | --- |
| a method without a body and without `@slot`, `@linkname` or `@cppname`, overriding nothing | it's neither a slot nor a symbol: a forgotten `@slot` |
| an `abstract` method without `@slot` | it is virtual, so it needs its slot |
| `@slot` on a method of an ordinary class | an ordinary class's vtable is tslang's own |
| a method without a body and without `@virtual`, `@slot`, `@linkname` or `@cppname`, overriding nothing | it's neither a slot nor a symbol: a forgotten `@virtual` |
| an `abstract` method without `@virtual` or `@slot` | it is virtual, so it needs its slot |
| `@virtual`, `@destructor` or `@slot` on a method of an ordinary class, `@vtablesize` on one | an ordinary class's vtable is tslang's own |
| new virtual methods with both `@virtual` and `@slot(N)` in one class | `@virtual` numbers every new slot of the class |
| `@virtual` in a class extending one whose size isn't known (its slots are `@slot(N)`, without `@vtablesize(N)`) | the new slots would start at an unknown slot |
| a call of a `@destructor` method | MSVC's slot is the deleting destructor, taking flags; the Itanium ABI's first destroys without freeing |
| a constructor or a field initializer, in a class none of whose virtual methods has a body | the objects and their code are C++'s (see "Implementing C++ methods") |
| static members, `get`/`set` accessors, `accessor` fields | they would take vtable slots |
| `implements` | an implemented interface takes a slot |
Expand Down Expand Up @@ -106,9 +160,14 @@ counts it:
clang computes for the target, and each non-virtual method's `@cppname` declaration (its
`@linkname` symbol when `@cppname` can't spell it or mangles it otherwise) (README, "C++ classes"):
`tsbindgen nvrhi.hpp --target x86_64-pc-windows-msvc --filter 'nvrhi::I*' -- -std=c++17`.
With `--virtual-slots` it writes `@virtual` and `@destructor` instead of this target's `@slot(N)`,
declaring the virtual methods that aren't public too: one binding for every target. A class with
a virtual method it can't declare (a variadic one, one taking a type it can't map), and every class
extending it, keeps this target's `@slot(N)`, with a comment saying why.
Writing one by hand:

- **Slot numbers.** Take them from the compiler, not by counting: MSVC prints a class's vtable
- **Slot numbers.** Prefer `@virtual` (above), declaring every virtual method in the header's
order. For `@slot(N)`, take them from the compiler, not by counting: MSVC prints a class's vtable
with `cl /c /Zs /d1reportSingleClassLayout<Name> file.cpp`; clang (Itanium) with
`clang++ -S -emit-llvm -o /dev/null -Xclang -fdump-vtable-layouts file.cpp`, for a class whose
vtable the file emits (it defines the first virtual method that isn't inline), where slot N is
Expand Down
10 changes: 10 additions & 0 deletions tslang/include/TsClangImporter/BindingModel.h
Original file line number Diff line number Diff line change
Expand Up @@ -100,6 +100,13 @@ struct Method
TsType result;
bool nonTrivialReturn = false; // returns a record with a destructor or a copy constructor
std::string skipReason; // non-empty: left out, with a `// skipped:` line in its place
// a virtual method that adds a slot: printed @virtual with --virtual-slots (slot is the target's)
bool isVirtual = false;
// the virtual destructor that adds its slots, printed @destructor with --virtual-slots only
bool destructor = false;
// `protected` or `private`: a virtual method that isn't public, which only --virtual-slots
// declares (its slot shifts the next ones); empty for a public one
std::string access;
};

struct Decl
Expand All @@ -125,6 +132,9 @@ struct Decl
std::string base; // CppClass: the key of the base class, or empty
std::vector<Method> methods; // CppClass: the methods it introduces, in declaration order
std::string fieldsSkipReason; // CppClass: non-empty when its fields aren't declared
// CppClass: why its slots can't be numbered with @virtual - a virtual method that adds a slot
// and can't be declared; empty when every one is in `methods`
std::string virtualSlotsReason;
};

struct HeaderModel
Expand Down
4 changes: 4 additions & 0 deletions tslang/include/TsClangImporter/BindingPrinter.h
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,10 @@ struct PrintOptions
std::string namespaceName; // --namespace: wrap in `namespace N { export ... }`, with @linkname
std::string stripPrefix; // --strip-prefix: removed from the TS names (needs a namespace)
std::vector<std::string> headerLines; // printed first, each as a `//` comment
// --virtual-slots: a C++ class's virtual methods @virtual, its destructor @destructor, which
// tslang numbers for the target compiled for: one binding for every target. A class with a
// virtual method that can't be declared (or extending one) keeps this target's @slot(N).
bool virtualSlots = false;
};

struct PrintResult
Expand Down
10 changes: 10 additions & 0 deletions tslang/include/TypeScript/Defines.h
Original file line number Diff line number Diff line change
Expand Up @@ -474,6 +474,16 @@
// @slot(N) on a method of a @cpp class: a C++ virtual method, slot N of the vtable (counted
// from 0, a base class's slots included); a method without it isn't virtual (see MethodInfo::cppSlot)
#define CPP_SLOT "slot"
// @virtual on a method of a @cpp class: a C++ virtual method whose slot the compiler numbers for the
// target's C++ ABI from the declaration order, as the C++ compiler does (mlirGenClassCppVirtualSlots).
// Its class declares every virtual method of its own, in the C++ header's order.
#define CPP_VIRTUAL "virtual"
// @destructor on a method of a @cpp class: the C++ virtual destructor - one slot under MSVC, two under
// the Itanium ABI. It can't be called: the two ABIs call it differently.
#define CPP_DESTRUCTOR "destructor"
// @vtablesize(N) on a @cpp class: its vtable has N slots, a base class's included, so a class extending
// it numbers its @virtual methods from N. Written into __decls for a class whose size is known.
#define CPP_VTABLE_SIZE "vtablesize"
// The name of a C++ overload after the first one declared, `write#1` (see mlirGenClassCppOverloadNames)
#define CPP_OVERLOAD_SEPARATOR "#"
// On a call (CallIndirect, then CallInternal or Invoke): the index of the argument that is the hidden
Expand Down
7 changes: 7 additions & 0 deletions tslang/include/TypeScript/MLIRLogic/MLIRGenStore.h
Original file line number Diff line number Diff line change
Expand Up @@ -172,6 +172,8 @@ struct MethodInfo
// @slot(N): the vtable slot of a @cpp method, -1 without @slot (a non-virtual method, or
// one overriding a base class's slot by name)
int cppSlot = -1;
// @destructor: the C++ virtual destructor of a @cpp class, which can't be called
bool isCppDestructor = false;
// a slot of a @cpp class's vtable that no method names (ClassInfo::getVirtualTable)
bool isCppSlotGap = false;
// `@keeps`, `@borrows`, `@lends` (OWN_DECLARED_KEEPS_ATTR_NAME): argument indices, `this` 0, for
Expand Down Expand Up @@ -893,6 +895,11 @@ struct ClassInfo
// two @cpp methods in one slot, or an override's @slot not its base's: found by
// getVirtualTable, which can't report it, and reported by its caller
std::string cppSlotConflict;
// a @cpp class's vtable: its number of slots, a base class's included, when every one is known
// (its virtual methods are @virtual, or it says @vtablesize(N)), else -1; and the slot of its
// virtual destructor, its own or a base class's, -1 without one (mlirGenClassCppVirtualSlots)
int cppVTableSize = -1;
int cppDestructorSlot = -1;
ProcessingStages processingAtEvaluation;
ProcessingStages processing;
// the module `processing` was reached in: a discovery module is thrown away with what it holds
Expand Down
4 changes: 4 additions & 0 deletions tslang/include/TypeScript/TargetInfo.h
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,9 @@ struct TargetInfo
// MSVC C++ member functions are __thiscall on 32-bit x86 (`this` in ECX), not the plain C
// convention a class method is called with, so a @cpp class can't call them.
bool memberCallsUseThiscall = false;
// C++ vtables are laid out as MSVC lays them out (overloads grouped, one destructor slot), not as
// the Itanium ABI does (mlirGenClassCppVirtualSlots)
bool msvcVTableLayout = false;

// MSVC returns a C++ record (struct, class) from an instance method through a hidden pointer,
// passed after `this` and returned in turn (clang's MicrosoftCXXABI::classifyReturnType): the
Expand Down Expand Up @@ -80,6 +83,7 @@ struct TargetInfo
info.supportsInProcessJit =
target.getArch() == host.getArch() && target.getOS() == host.getOS();
info.memberCallsUseThiscall = msvc && x86_32;
info.msvcVTableLayout = msvc;
info.hiddenReturnPointerAfterThis = msvc;
info.hiddenReturnPointerBeforeThis =
!msvc && (target.getArch() == llvm::Triple::x86_64 || target.getArch() == llvm::Triple::aarch64);
Expand Down
49 changes: 46 additions & 3 deletions tslang/lib/TsClangImporter/BindingPrinter.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -239,6 +239,7 @@ llvm::Expected<PrintResult> printBindings(const HeaderModel &model, const PrintO
};

auto hasCppClass = false;
auto targetSlots = false; // a @cpp class printed with this target's @slot(N)
for (int pass = 0; pass < groups; ++pass)
{
for (size_t index = 0; index < model.decls.size(); ++index)
Expand Down Expand Up @@ -270,6 +271,30 @@ llvm::Expected<PrintResult> printBindings(const HeaderModel &model, const PrintO
break;
case DeclKind::CppClass: {
hasCppClass = true;
// @virtual needs every slot of the class and of its bases declared
std::string slotsReason;
for (auto *current = &decl; current && slotsReason.empty();)
{
slotsReason = current->virtualSlotsReason;
auto base = current->base;
current = nullptr;
for (auto &other : model.decls)
{
if (!base.empty() && other.key == base)
{
current = &other;
}
}
}

auto virtualSlots = options.virtualSlots && slotsReason.empty();
targetSlots |= !virtualSlots;
if (options.virtualSlots && !virtualSlots)
{
line("// @slot numbers for this target only: " + slotsReason);
result.warnings.push_back(decl.qualifiedName + " keeps this target's slots: " + slotsReason);
}

line("@cpp");
line(exported + "class " + tsName + (decl.base.empty() ? "" : " extends " + nameOf(decl.base)) +
" { // " + decl.qualifiedName);
Expand All @@ -286,6 +311,19 @@ llvm::Expected<PrintResult> printBindings(const HeaderModel &model, const PrintO

for (auto &method : decl.methods)
{
// the destructor and the virtual methods that aren't public are slots, which
// only @virtual has to declare
if (!virtualSlots && (method.destructor || !method.access.empty()))
{
continue;
}

if (method.destructor)
{
member("@destructor " + method.name + "(): void;");
continue;
}

if (!method.skipReason.empty())
{
member("// skipped: " + method.cppName + " \xE2\x80\x94 " + method.skipReason);
Expand All @@ -307,7 +345,9 @@ llvm::Expected<PrintResult> printBindings(const HeaderModel &model, const PrintO

// a non-virtual method by its C++ declaration, which @cppname mangles for the
// target compiled for; by this target's symbol when it can't be spelled so
auto decorator = method.slot >= 0 ? "@slot(" + std::to_string(method.slot) + ") "
auto access = method.access.empty() ? std::string() : method.access + " ";
auto decorator = virtualSlots && method.isVirtual ? "@virtual " + access
: method.slot >= 0 ? "@slot(" + std::to_string(method.slot) + ") "
: method.cppDeclaration.empty()
? "@linkname(\"" + method.symbol + "\") "
: "@cppname(\"" + method.cppDeclaration + "\") ";
Expand Down Expand Up @@ -402,8 +442,11 @@ llvm::Expected<PrintResult> printBindings(const HeaderModel &model, const PrintO

if (hasCppClass)
{
result.text += "// The @cpp classes are this target's C++ ABI (generate them again for another); compile with "
"-mm=gc or -mm=none.\n";
result.text += targetSlots
? "// The @cpp classes are this target's C++ ABI (generate them again for another); compile with "
"-mm=gc or -mm=none.\n"
: "// tslang numbers the @cpp classes' slots for the target compiled for (@virtual); their fields "
"are this target's layout. Compile with -mm=gc or -mm=none.\n";
}

if (!result.text.empty())
Expand Down
53 changes: 47 additions & 6 deletions tslang/lib/TsClangImporter/HeaderParser.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -759,12 +759,49 @@ class Collector : public clang::RecursiveASTVisitor<Collector>
usedNames.insert(field.name);
}

auto uniqueName = [&](const std::string &cppName) {
auto name = escapeReserved(cppName);
for (auto suffix = 2; usedNames.count(name) && !methodNames.count(name); ++suffix)
{
name = escapeReserved(cppName) + "_" + std::to_string(suffix);
}

usedNames.insert(name);
methodNames.insert(name);
return name;
};

for (auto *method : definition->methods())
{
// a virtual method adding a slot: --virtual-slots numbers the class's slots from them all
auto addsSlot = method->isVirtual() && method->size_overridden_methods() == 0;
if (addsSlot && llvm::isa<clang::CXXDestructorDecl>(method))
{
Method bound;
bound.cppName = "~" + decl.name;
bound.name = uniqueName("destructor");
bound.isVirtual = true;
bound.destructor = true;
bound.result.name = "void";
decl.methods.push_back(std::move(bound));
continue;
}

if (addsSlot && (method->isImplicit() || method->isDeleted() ||
llvm::isa<clang::CXXConversionDecl>(method) || method->isOverloadedOperator()))
{
if (decl.virtualSlotsReason.empty())
{
decl.virtualSlotsReason = "the virtual '" + method->getNameAsString() + "' can't be declared";
}

continue;
}

if (method->isImplicit() || method->isDeleted() || method->isStatic() ||
llvm::isa<clang::CXXConstructorDecl, clang::CXXDestructorDecl, clang::CXXConversionDecl>(method) ||
method->isOverloadedOperator() || method->getDescribedFunctionTemplate() ||
method->getAccess() != clang::AS_public ||
(method->getAccess() != clang::AS_public && !addsSlot) ||
(method->isVirtual() && method->size_overridden_methods() > 0))
{
continue;
Expand All @@ -774,15 +811,19 @@ class Collector : public clang::RecursiveASTVisitor<Collector>
// by the arguments. A field of the name makes it `_2`, `_3`, ...
Method bound;
bound.cppName = method->getName().str();
bound.name = escapeReserved(bound.cppName);
for (auto suffix = 2; usedNames.count(bound.name) && !methodNames.count(bound.name); ++suffix)
bound.name = uniqueName(bound.cppName);
bound.isVirtual = addsSlot;
if (method->getAccess() != clang::AS_public)
{
bound.name = escapeReserved(bound.cppName) + "_" + std::to_string(suffix);
bound.access = method->getAccess() == clang::AS_protected ? "protected" : "private";
}

usedNames.insert(bound.name);
methodNames.insert(bound.name);
mapMethod(bound, method);
if (addsSlot && !bound.skipReason.empty() && decl.virtualSlotsReason.empty())
{
decl.virtualSlotsReason = "the virtual '" + bound.cppName + "' is skipped";
}

decl.methods.push_back(std::move(bound));
}

Expand Down
Loading
Loading