Allow Kotlin coroutines This method allows clients to use coroutines for async methods by supplying a helper suspend method for each function. This provides (IMHO) the ideal API for Kotlin apps and retains the option to switch to an alternative method using Futures at a later date. Bug: 330292651 Change-Id: Iaf9b464e80ea7f3fcf2dfae8c211c722e4a0e311 Reviewed-on: https://dawn-review.googlesource.com/c/dawn/+/191380 Reviewed-by: Corentin Wallez <cwallez@chromium.org> Reviewed-by: dan sinclair <dsinclair@google.com> Commit-Queue: Jim Blackler <jimblackler@google.com>
diff --git a/generator/dawn_json_generator.py b/generator/dawn_json_generator.py index 90bf762..eb5d614 100644 --- a/generator/dawn_json_generator.py +++ b/generator/dawn_json_generator.py
@@ -837,6 +837,17 @@ def jni_name(type): return kt_file_path + '/' + type.name.CamelCase() + # We assume that if the final two parameters are named 'userdata' and 'callback' respectively + # that this is an async method that uses function pointer based callbacks. + def is_async_method(method): + if len(method.arguments) < 3: + return False # Not enough parameters to be an async method. + if method.arguments[-1].name.get() != 'userdata': + return False + if method.arguments[-2].name.get() != 'callback': + return False + return True + # A structure may need to know which other structures listed it as a chain root, e.g. # to know whether to mark the generated class 'open'. chain_children = defaultdict(list) @@ -847,6 +858,7 @@ params_kotlin['include_structure_member'] = include_structure_member params_kotlin['include_method'] = include_method params_kotlin['jni_name'] = jni_name + params_kotlin['is_async_method'] = is_async_method return params_kotlin @@ -1504,6 +1516,10 @@ 'java/' + kt_file_path + '/Functions.kt', [RENDER_PARAMS_BASE, params_kotlin])) renders.append( + FileRender('art/api_kotlin_async_helpers.kt', + 'java/' + kt_file_path + '/AsyncHelpers.kt', + [RENDER_PARAMS_BASE, params_kotlin])) + renders.append( FileRender('art/structures.h', 'cpp/structures.h', [RENDER_PARAMS_BASE, params_kotlin])) renders.append(
diff --git a/generator/templates/art/api_kotlin_async_helpers.kt b/generator/templates/art/api_kotlin_async_helpers.kt new file mode 100644 index 0000000..1e1ad89 --- /dev/null +++ b/generator/templates/art/api_kotlin_async_helpers.kt
@@ -0,0 +1,70 @@ +//* Copyright 2024 The Dawn & Tint Authors +//* +//* Redistribution and use in source and binary forms, with or without +//* modification, are permitted provided that the following conditions are met: +//* +//* 1. Redistributions of source code must retain the above copyright notice, this +//* list of conditions and the following disclaimer. +//* +//* 2. Redistributions in binary form must reproduce the above copyright notice, +//* this list of conditions and the following disclaimer in the documentation +//* and/or other materials provided with the distribution. +//* +//* 3. Neither the name of the copyright holder nor the names of its +//* contributors may be used to endorse or promote products derived from +//* this software without specific prior written permission. +//* +//* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +//* AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +//* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +//* DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE +//* FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +//* DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR +//* SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER +//* CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +//* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +//* OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +package {{ kotlin_package }} + +import kotlin.coroutines.resume +import kotlin.coroutines.suspendCoroutine +{% from 'art/api_kotlin_types.kt' import kotlin_declaration, kotlin_definition with context %} + +//* We make a return class for every function pointer so that usage of callback-using methods can be +// replaced with suspend (async) function that returns the same data. +{% for function_pointer + in by_category['function pointer'] if len(function_pointer.name.chunks) > 1 %} + //* Function pointers generally end in Callback which we replace with Return. + {% set return_name = function_pointer.name.chunks[:-1] | map('title') | join + 'Return' %} + data class {{ return_name }}( + //* Kotlin doesn't need userdata because of captures, so we omit it. + {% for arg in function_pointer.arguments if arg.name.get() != 'userdata' %} + val {{ as_varName(arg.name) }}: {{ kotlin_declaration(arg) }}, + {% endfor %}) +{% endfor %} + +//* Every method that is identified as using callbacks is given a helper method that wraps the +//* call with a suspend function. +{% for obj in by_category['object'] %} + {% for method in obj.methods if is_async_method(method) %} + {% set function_pointer = method.arguments[-2].type %} + {% set return_name = function_pointer.name.chunks[:-1] | map('title') | join + 'Return' %} + suspend fun {{ obj.name.CamelCase() }}.{{ method.name.camelCase() }}( + {%- for arg in method.arguments[:-2] %} + {{- as_varName(arg.name) }}: {{ kotlin_definition(arg) }}, + {%- endfor %}) = suspendCoroutine { + {{ method.name.camelCase() }}( + {%- for arg in method.arguments[:-2] %} + {{- as_varName(arg.name) }}, + {% endfor %}) { + {%- for arg in function_pointer.arguments if arg.name.get() != 'userdata' %} + {{- as_varName(arg.name) }}, + {%- endfor %} -> it.resume({{ return_name }}( + {%- for arg in function_pointer.arguments if arg.name.get() != 'userdata' %} + {{- as_varName(arg.name) }}, + {%- endfor %}) + ) + } + } + {% endfor %} +{% endfor %}
diff --git a/tools/android/BUILD.gn b/tools/android/BUILD.gn index b7caaae..05fb81c 100644 --- a/tools/android/BUILD.gn +++ b/tools/android/BUILD.gn
@@ -38,6 +38,7 @@ "java/android/dawn/AdapterProperties.kt", "java/android/dawn/AdapterType.kt", "java/android/dawn/AddressMode.kt", + "java/android/dawn/AsyncHelpers.kt", "java/android/dawn/BackendType.kt", "java/android/dawn/BindGroup.kt", "java/android/dawn/BindGroupDescriptor.kt",