Wasm marshaler API for user-defined types; migrate Uri and DateTime to new API

[kg]

This PR introduces a system for defining custom JS➔Managed and Managed➔JS marshaling primitives so that any* user-defined type can cross between environments seamlessly, and migrates our existing Uri and DateTime marshaling logic to use the new system.

First, some sample code:

    public static class DateTimeMarshaler
    {
        public static string JavaScriptToInterchangeTransform => "return value.toISOString()";
        public static string InterchangeToJavaScriptTransform => "return new Date(value)";

        public static DateTime FromJavaScript (string s)
        {
            return DateTime.Parse(s).ToUniversalTime();
        }

        public static string ToJavaScript (in DateTime dt)
        {
            return dt.ToString("o");
        }
    }

General overview:

• The author of the type exposes static methods with specific names and signatures on the type so that the wasm bindings layer can find them.
  • Right now there is a manual linker configuration to keep our built-in marshalers from being linked out. The user will need to do this themselves for any marshalers they define.
  • The runtime receives a table of type➔marshaler mappings at startup, and this table is generated by WasmAppBuilder.
  • The ideal form of this in the future will be a source generator that automatically finds marshalers and generates the linker configuration + table, but right now this is not possible (source generators can't do the things necessary for this yet).
• The required methods are a JS➔Managed mapping and a Managed➔JS mapping. The types used by these methods have to (at present) be basic types that can cross through the bindings layer without assistance, i.e. double or string. In the future I hope to expand on this to allow marshaling spans or arrays.
• In addition to the direct JS⬌Managed mapping, you can optionally define additional methods that return JS expression filters. Those expression filters will be evaluated on the JS side of the boundary to process the value - for example since neither JS Date or C# DateTime can cross the bindings boundary directly, you can marshal it as a string and then use a filter to map it to/from the JS Date type.
  • TODO: It would be ideal to expose these as const string instead of function getters, but right now the only straightforward way to get at managed values is through function calls.
• Alongside all this we add a new 'a' type specifier for method signatures (the strings you pass to call_static_method, bind_static_method etc) that basically means 'figure it out'. When you use this specifier, the bindings layer will examine the target method and identify the best fit for that parameter. This is meant for the purpose of passing user-defined types so you don't need to think about whether they're classes or structs, but it also can be useful in other cases.
  • The downside is that any signature using this type specifier ends up being method-specific, so you will end up with method-specific generated code instead of the existing generated code that is shared by all methods with a given signature. There's room for some improvement here.

More detailed notes:

• Before this PR we had zero support for passing structs across the JS⬌Managed boundary in any circumstances (other than DateTime).
• The JS➔Managed conversion has to box the resulting value (if it's a struct), which introduces some unpleasant overhead. This ends up being less inefficient than you'd think (because currently we have to box all values being passed to managed methods from JS - not really sure why) but it's still an opportunity for performance improvement between eliminating some copies and ensuring the GC isn't involved.
• The introduction of support for marshaling custom classes introduces a bit of overhead for classes without custom marshaling implementations, because of the additional check added to the existing Managed➔JS flow. However, the new check is extremely cheap and the existing flow was very slow 😊
• There are corner cases where this new system will not run (throwing a runtime exception) or will otherwise fail (for example if the signature of your methods is weird you can get garbage values). I think many of these can be tightened up if we write more test cases and add more error handling and checks to match.
• Many scenarios might call for an automated way to pass JSON blobs or raw byte data across the boundary. You can at least use filters (i.e. JSON.parse(value)) to simplify the former, but the latter really demands integrated support for passing Spans around and I have no idea how we'd do this in the existing setup.
• We could consider having some sort of default fallback marshaling implementation based on BinaryFormatter or something like that, but it seems out of scope. This system is at least relatively easy to extend to do that as a fallback.

Also in this PR:

• box_js_obj_with_converter API that allows you to request a specific managed type when boxing a JS value (this is how you create a type like Uri explicitly)
• Caching for the existing 'find class in assembly' APIs, so that they can be used efficiently at runtime when trying to box values of a specific type
• Caching for bind_method so that automated tests and benchmarks can safely bind methods at the start of each run without running out of runtime memory or incurring significant performance overhead (this was causing benchmarks to fail, because i had optimized the bindings so much that the run count in BDN was skyrocketing)
• Additional test coverage for some of the existing code, like being able to pass JS Dates. I think that was actually broken, but Blazor works so whatever...
• Miscellaneous performance improvements, producing around a ~4-6% performance gain on my benchmarks for existing call paths
• Miscellaneous bug fixes and additional assertions in runtime/driver code (for things that previously would have produced crashes)
• Better debug information for generated code so it's easier to examine in browser debuggers and profilers

[ghost]

Tagging subscribers to 'arch-wasm': @lewing
See info in area-owners.md if you want to be subscribed.

Issue Details

---

This PR introduces a system for defining custom JS➔Managed and Managed➔JS marshaling primitives so that any* user-defined type can cross between environments seamlessly. The ideal end goal is to use this new system for marshaling types like Uri, DateTime and Task so that they can be linked out if they are not used.

First, some sample code:

        public struct CustomDate {
            public DateTime Date;

            private static string JSToManaged_PreFilter () => "value.toISOString()";
            private static string ManagedToJS_PostFilter () => "new Date(value)";

            private static CustomDate JSToManaged (string s) {
                return new CustomDate { 
                    Date = DateTime.Parse(s).ToUniversalTime()
                };
            }

            private static string ManagedToJS (ref CustomDate cd) {
                return cd.Date.ToString("o");
            }
        }

General overview:

• The author of the type exposes static methods with specific names and signatures on the type so that the wasm bindings layer can find them.
  • TODO: We need some straightforward way to ensure that the linker doesn't remove these methods from wasm builds unless the type itself is not referenced
• The required methods are a JS➔Managed mapping and a Managed➔JS mapping. The types used by these methods have to (at present) be basic types that can cross through the bindings layer without assistance, i.e. double or string. In the future I hope to expand on this to allow marshaling spans or arrays.
• In addition to the direct JS⬌Managed mapping, you can optionally define additional methods that return JS expression filters. Those expression filters will be evaluated on the JS side of the boundary to process the value - for example since neither JS Date or C# DateTime can cross the bindings boundary directly, you can marshal it as a string and then use a filter to map it to/from the JS Date type.
  • TODO: It would be ideal to expose these as const string instead of function getters, but right now the only straightforward way to get at managed values is through function calls.
• Alongside all this we add a new 'a' type specifier for method signatures (the strings you pass to call_static_method, bind_static_method etc) that basically means 'figure it out'. When you use this specifier, the bindings layer will examine the target method and identify the best fit for that parameter. This is meant for the purpose of passing user-defined types so you don't need to think about whether they're classes or structs, but it also can be useful in other cases.
  • The downside is that any signature using this type specifier ends up being method-specific, so you will end up with method-specific generated code instead of the existing generated code that is shared by all methods with a given signature. There's room for some improvement here.

More detailed notes:

• Before this PR we had zero support for passing structs across the JS⬌Managed boundary in any circumstances (other than DateTime).
• The JS➔Managed conversion has to box the resulting value (if it's a struct), which introduces some unpleasant overhead. This ends up being less inefficient than you'd think (because currently we have to box all values being passed to managed methods from JS - not really sure why) but it's still an opportunity for performance improvement between eliminating some copies and ensuring the GC isn't involved.
• The introduction of support for marshaling custom classes introduces a bit of overhead for classes without custom marshaling implementations, because of the additional check added to the existing Managed➔JS flow. However, the new check is extremely cheap and the existing flow was very slow 😊
• There are corner cases where this new system will not run (throwing a runtime exception) or will otherwise fail (for example if the signature of your methods is weird you can get garbage values). I think many of these can be tightened up if we write more test cases and add more error handling and checks to match.
• Many scenarios might call for an automated way to pass JSON blobs or raw byte data across the boundary. You can at least use filters (i.e. JSON.parse(value)) to simplify the former, but the latter really demands integrated support for passing Spans around and I have no idea how we'd do this in the existing setup.
• We could consider having some sort of default fallback marshaling implementation based on BinaryFormatter or something like that, but it seems out of scope. This system is at least relatively easy to extend to do that as a fallback.

Also in this PR:

• Additional test coverage for some of the existing code, like being able to pass JS Dates. I think that was actually broken, but Blazor works so whatever...

Author:	kg
Assignees:	-
Labels:	* NO MERGE *, arch-wasm
Milestone:	-

[dotnet-issue-labeler]

I couldn't figure out the best area label to add to this PR. If you have write-permissions please help me learn by adding exactly one area label.

[kg]

To help with understanding some of what this machinery does, here's an example of some of the code generated by the bindings to facilitate calling C# from JS:
https://gist.github.com/kg/f2c350b007d8e783085124c5d03f508e

[lewing]

Failure is relevant

[radical]

This breaks debugger tests with * Assertion: should not be reached at /Users/radical/dev/runtime/src/mono/mono/metadata/class-accessors.c:86.
To reproduce: $ make -C src/mono/wasm run-debugger-tests TEST_FILTER=DebuggerTests.ArrayTests.InvalidArrayId

It fails at this.async_method = Module.mono_bind_static_method ("[debugger-test] Math/NestedInMath:AsyncTest");
(https://github.com/dotnet/runtime/blob/master/src/mono/wasm/debugger/tests/debugger-test/debugger-driver.html#L14)

The method in question: public static async System.Threading.Tasks.Task<bool> AsyncTest(string s, int i)
(https://github.com/dotnet/runtime/blob/master/src/mono/wasm/debugger/tests/debugger-test/debugger-test.cs#L139)

.. is in a nested class Math.NestedInMath.

[kg]

Thanks for digging in. I bet it's due to generics.

[kjpou1]

Not sure if it is generics or not but I had to add some code for handling generic signatures in the PR here: #47519

This allows for generic signatures.

[kjpou1]

Just running through the DRAFT PR:

info: class_is_task
  info: class_is_task
  info: creating signature info for method result
  info: creating signature info for method params
  fail: [out of order message from the browser]: http://127.0.0.1:61482/dotnet.wasm 0:1703801 Uncaught RuntimeError: divide by zero
  info: GC_MINOR: (Nursery full) time 2.40ms, stw 2.44ms promoted 259K major size: 1280K in use: 687K los size: 0K in use: 0K
  info: GC_MINOR: (Nursery full) time 2.41ms, stw 2.43ms promoted 0K major size: 1280K in use: 687K los size: 0K in use: 0K
  info: GC_MINOR: (Nursery full) time 3.01ms, stw 3.03ms promoted 0K major size: 1280K in use: 687K los size: 0K in use: 0K
  info: GC_MINOR: (Nursery full) time 2.30ms, stw 2.32ms promoted 0K major size: 1280K in use: 687K los size: 0K in use: 0K

[ghost]

Draft Pull Request was automatically closed for inactivity. It can be manually reopened in the next 30 days if the work resumes.

[lewing]

@kg are you still missing some changes?

[kg]

@kg are you still missing some changes?

I'm still working through the msbuild integration in a way that won't break tests

[kg]

Here are a set of generated marshaler functions, @pavelsavara

//# sourceURL=https://mono-wasm.invalid/System_DateTime$FromJavaScript
"use strict";
const Module = __closure__.Module;
const mono_wasm_new_root = __closure__.mono_wasm_new_root;
const _create_temp_frame = __closure__._create_temp_frame;
const _get_args_root_buffer_for_method_call = __closure__._get_args_root_buffer_for_method_call;
const _get_buffer_for_method_call = __closure__._get_buffer_for_method_call;
const _handle_exception_for_call = __closure__._handle_exception_for_call;
const _teardown_after_call = __closure__._teardown_after_call;
const mono_wasm_try_unbox_primitive_and_get_type = __closure__.mono_wasm_try_unbox_primitive_and_get_type;
const _unbox_mono_obj_root_with_known_nonprimitive_type = __closure__._unbox_mono_obj_root_with_known_nonprimitive_type;
const invoke_method = __closure__.invoke_method;
const method = __closure__.method;
const this_arg = __closure__.this_arg;
const token = __closure__.token;
const unbox_buffer = __closure__.unbox_buffer;
const unbox_buffer_size = __closure__.unbox_buffer_size;
const getI32 = __closure__.getI32;
const getU32 = __closure__.getU32;
const getF32 = __closure__.getF32;
const getF64 = __closure__.getF64;
const converter_d_result_unmarshaled = __closure__.converter_d_result_unmarshaled;

function System_DateTime$FromJavaScript(arg0) {
    _create_temp_frame();
    let resultRoot = token.scratchResultRoot, exceptionRoot = token.scratchExceptionRoot;
    token.scratchResultRoot = null;
    token.scratchExceptionRoot = null;
    if (resultRoot === null)
        resultRoot = mono_wasm_new_root();
    if (exceptionRoot === null)
        exceptionRoot = mono_wasm_new_root();

    let argsRootBuffer = _get_args_root_buffer_for_method_call(converter_d_result_unmarshaled, token);
    let scratchBuffer = _get_buffer_for_method_call(converter_d_result_unmarshaled, token);
    let buffer = converter_d_result_unmarshaled.compiled_function(
        scratchBuffer, argsRootBuffer, method,
        arg0
    );
    let is_result_marshaled = false;

    resultRoot.value = invoke_method(method, this_arg, buffer, exceptionRoot.get_address());
    _handle_exception_for_call(converter_d_result_unmarshaled, token, buffer, resultRoot, exceptionRoot, argsRootBuffer);

    let resultPtr = resultRoot.value, result = undefined;
        result = resultPtr;
    _teardown_after_call(converter_d_result_unmarshaled, token, buffer, resultRoot, exceptionRoot, argsRootBuffer);
    return result;
};
return System_DateTime$FromJavaScript;


//# sourceURL=https://mono-wasm.invalid/interchange_filter_for_type62173044
"use strict";
const Module = __closure__.Module;
const MONO = __closure__.MONO;
const BINDING = __closure__.BINDING;
const typePtr = __closure__.typePtr;
const alloca = __closure__.alloca;
const getI8 = __closure__.getI8;
const getI16 = __closure__.getI16;
const getI32 = __closure__.getI32;
const getI64 = __closure__.getI64;
const getU8 = __closure__.getU8;
const getU16 = __closure__.getU16;
const getU32 = __closure__.getU32;
const getF32 = __closure__.getF32;
const getF64 = __closure__.getF64;
const setI8 = __closure__.setI8;
const setI16 = __closure__.setI16;
const setI32 = __closure__.setI32;
const setI64 = __closure__.setI64;
const setU8 = __closure__.setU8;
const setU16 = __closure__.setU16;
const setU32 = __closure__.setU32;
const setF32 = __closure__.setF32;
const setF64 = __closure__.setF64;
const System_DateTime$FromJavaScript = __closure__.System_DateTime$FromJavaScript;

function interchange_filter_for_type62173044(value) {

    switch (typeof (value)) {
        case 'number':
            return value;
        default:
            if (value instanceof Date) {
                return value.valueOf();
            } else
                throw new Error('Value must be a number (msecs since unix epoch), or a Date');
    }

};
return interchange_filter_for_type62173044;


//# sourceURL=https://mono-wasm.invalid/js_to_interchange_for_type62173044
"use strict";
const Module = __closure__.Module;
const MONO = __closure__.MONO;
const BINDING = __closure__.BINDING;
const typePtr = __closure__.typePtr;
const alloca = __closure__.alloca;
const getI8 = __closure__.getI8;
const getI16 = __closure__.getI16;
const getI32 = __closure__.getI32;
const getI64 = __closure__.getI64;
const getU8 = __closure__.getU8;
const getU16 = __closure__.getU16;
const getU32 = __closure__.getU32;
const getF32 = __closure__.getF32;
const getF64 = __closure__.getF64;
const setI8 = __closure__.setI8;
const setI16 = __closure__.setI16;
const setI32 = __closure__.setI32;
const setI64 = __closure__.setI64;
const setU8 = __closure__.setU8;
const setU16 = __closure__.setU16;
const setU32 = __closure__.setU32;
const setF32 = __closure__.setF32;
const setF64 = __closure__.setF64;
const System_DateTime$FromJavaScript = __closure__.System_DateTime$FromJavaScript;
const filter = __closure__.filter;

function js_to_interchange_for_type62173044(value, method, parmIdx) {
    let filteredValue = filter(value);
    let convertedResult = System_DateTime$FromJavaScript(filteredValue, method, parmIdx);
    return convertedResult;
};

return js_to_interchange_for_type62173044;

[kg]

Vs code with default settings, not sure why On November 10, 2021 10:49:13 PM PST, Pavel Savara ***@***.***> wrote: ***@***.*** commented on this pull request.

> @@ -188,8 +193,8 @@ export function _handle_exception_for_call( function _handle_exception_and_produce_result_for_call( converter: Converter | undefined, token: BoundMethodToken | null, - buffer: VoidPtr, resultRoot: WasmRoot<MonoString>, - exceptionRoot: WasmRoot<MonoObject>, argsRootBuffer: WasmRootBuffer | undefined, + buffer: VoidPtr, resultRoot: WasmRoot<MonoString>, The whitespace at the end is something your editor does ? -- You are receiving this because you were mentioned. Reply to this email directly or view it on GitHub: #47640 (review)

- kg (mobile)

[kg]

PR updated with support for passing Span<byte> and ReadOnlySpan<byte> arguments to methods using the new 'b' signature character, and marshalers now explicitly request a scratch buffer instead of manually allocating it using alloca, which allows them to take Span arguments instead. Note that returning spans is not valid, since return values have to be boxed. I don't see this as a problem.

[azure-pipelines]

Pull request contains merge conflicts.

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).

[kg]

/azp run runtime-manual

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).

[kg]

/azp run runtime-manual

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).

[kg]

/azp run runtime-manual

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).