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
24 changes: 23 additions & 1 deletion docs/cpp-classes.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,7 @@ virtual only as in C++:
| `@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...)` |
| `@cppname("T name(...)") name(...): T;` | the same, by its C++ declaration: the compiler mangles it for the target (see below) |
| `name(...): T { ... }` with no `@slot`, overriding nothing | a method of TypeScript's own, called directly; not in the vtable |

The slots may be given in any order, and a slot no method names is skipped: declare only the
Expand All @@ -68,7 +69,7 @@ errors and not warnings.

| Not allowed | Why |
| --- | --- |
| a method without a body and without `@slot` or `@linkname`, overriding nothing | it's neither a slot nor a symbol: a forgotten `@slot` |
| 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 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") |
Expand Down Expand Up @@ -134,6 +135,27 @@ Writing one by hand:
- **Non-virtual methods** are bound by their mangled symbol: `@linkname("?scaled@Methods@@QEAAHH@Z")`
under MSVC, `@linkname("_ZN7Methods6scaledEi")` under the Itanium ABI. The symbol has to be
exported by the C++ library (`__declspec(dllexport)` on the method or the class).

`@cppname` takes the C++ declaration instead and mangles it for the target: MSVC's scheme on
`windows-msvc`, the Itanium one (g++, clang) everywhere else, MinGW included. That way one class
works on every OS:

```ts
@cppname("int scaled(int)") scaled(x: s32): s32; // ?scaled@Methods@@QEAAHH@Z, _ZN7Methods6scaledEi
@cppname("int scaled(double)") scaled(x: f64): s32;
@cppname("int get() const") get(): s32; // a const method
@cppname("size_t length(const char* text)") length(text: string): u64;
```

An unqualified name is a member of the class. A qualified one is taken as written
(`ns::Methods::scaled`). On a `declare function`, `@cppname("int ns::sum(int, int)")` binds a
free function. The types are C++'s builtin ones; the `<stdint.h>`/`<stddef.h>` typedefs as the
target defines them (`int64_t` is `long` on 64-bit Linux and `long long` on Windows and macOS, and
each mangles differently); and records by qualified name (`ns::Pt*`, `const Pair&`), all with
`const`, `*`, `&`, `&&`. A bare record name is a `struct`: write `class Obj`, `union U`
or `enum E` when it isn't, because MSVC encodes which one it is. Names aren't looked up, so write
a record in another namespace with its full name. Templates, operators, constructors,
destructors, function pointers and arrays aren't supported: use `@linkname` for those.
- **Struct returned by value.** A C++ virtual method that returns a class or struct by value (for
example `nvrhi::RefCountPtr<T>` or `nvrhi::Object`) returns a record. Declare its return type
as a tuple with the record's layout:
Expand Down
37 changes: 37 additions & 0 deletions tslang/include/TypeScript/CppMangler.h
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
#ifndef TYPESCRIPT_CPPMANGLER_H_
#define TYPESCRIPT_CPPMANGLER_H_

#include "llvm/ADT/StringRef.h"
#include "llvm/TargetParser/Triple.h"

#include <string>

// @cppname("int Methods::scaled(int)"): a C++ declaration, turned into the symbol the target's C++
// compiler gives it - MSVC's scheme on windows-msvc, the Itanium one of g++ and clang everywhere
// else (MinGW included) - so one declaration binds the same C++ function on every OS, where
// @linkname needs each OS's symbol spelled out.
//
// The declaration is a return type, a name, and parameter types, and `const` after them for a
// const method. Types: the builtin ones (`unsigned long long`, `char16_t`, ...), the <stdint.h>
// and <stddef.h> typedefs (`int64_t`, `size_t`, ...) as the target defines them - `int64_t` is
// `long` on 64-bit Linux and `long long` on Windows and macOS, which mangle differently - and a
// struct, class, union or enum by its qualified name (`ns::Pt`, `class Obj`; a bare name is a
// struct), with `const`/`volatile`, `*`, `&` and `&&`. Templates, operators, constructors,
// destructors and function pointers are not supported.
struct CppMangleContext
{
// the class an unqualified name is a member of (`int scaled(int)` in a @cpp class `Methods` is
// `Methods::scaled`); empty outside a class
llvm::StringRef className;
// a method with `this` (MSVC encodes it, and its `const`); a static method or a free function
// has none
bool isInstanceMethod = false;
// a static method: MSVC tells it from a free function in a namespace of that name
bool isStaticMethod = false;
};

// The symbol, or false with `error` saying what is wrong with the declaration.
bool mangleCppName(llvm::StringRef declaration, const llvm::Triple &triple, const CppMangleContext &context,
std::string &symbol, std::string &error);

#endif // TYPESCRIPT_CPPMANGLER_H_
3 changes: 3 additions & 0 deletions tslang/include/TypeScript/Defines.h
Original file line number Diff line number Diff line change
Expand Up @@ -352,6 +352,9 @@
#define DLL_IMPORT "dllimport"
#define DLL_NAME "dllname"
#define LINK_NAME "linkname"
// @cppname("int Methods::scaled(int)"): @linkname under the symbol the target's C++ compiler gives
// that declaration (see CppMangler.h)
#define CPP_NAME "cppname"
// A class laid over an existing C++ object: its vtable is the C++ one (see ClassInfo::isCppVTable)
#define CPP_VTABLE "cpp"
// `@final class C`: no class may extend C, so a call on a value of type C is a direct call to the
Expand Down
1 change: 1 addition & 0 deletions tslang/lib/TypeScript/CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@ add_mlir_dialect_library(MLIRTypeScript
TypeScriptDialectTranslation.cpp
AsyncDialectTranslation.cpp
DiagnosticHelper.cpp
CppMangler.cpp
MLIRGen.cpp
MLIRGenAccessCall.cpp
MLIRGenCast.cpp
Expand Down
Loading
Loading