diff --git a/site/source/docs/porting/connecting_cpp_and_javascript/Interacting-with-code.rst b/site/source/docs/porting/connecting_cpp_and_javascript/Interacting-with-code.rst index a3f8287047e8..a94b04918f4a 100644 --- a/site/source/docs/porting/connecting_cpp_and_javascript/Interacting-with-code.rst +++ b/site/source/docs/porting/connecting_cpp_and_javascript/Interacting-with-code.rst @@ -613,30 +613,63 @@ Calling JavaScript functions as function pointers from C ======================================================== You can use ``addFunction`` to return an integer value that represents a -function pointer. Passing that integer to C code then lets it call that value as -a function pointer, and the JavaScript function you sent to ``addFunction`` will -be called. +function pointer. Passing that integer to C code then lets it call that value +as a function pointer, and the JavaScript function you sent to ``addFunction`` +will be called. See `test_add_function in test/test_core.py`_ for an example. You should build with ``-sALLOW_TABLE_GROWTH`` to allow new functions to be added to the table. Otherwise by default the table has a fixed size. -.. note:: When using ``addFunction`` on LLVM Wasm backend, you need to provide - an additional second argument, a Wasm function signature string. Each - character within a signature string represents a type. The first character - represents the return type of a function, and remaining characters are for - parameter types. +When using ``addFunction`` with a JavaScript function, you need to provide +an additional second argument, a Wasm function signature string, explained +below. See `test/interop/test_add_function_post.js `_ for an example. + + +.. _interacting-with-code-function-signatures: + +Function Signatures +=================== + +The LLVM Wasm backend requires a Wasm function signature string when using +``addFunction`` and in JavaScript libraries. Each character within a signature +string represents a type. The first character represents the return type of a +function, and remaining characters are for parameter types. - ``'v'``: void type - ``'i'``: 32-bit integer type - - ``'j'``: 64-bit integer type (currently does not exist in JavaScript) + - ``'j'``: 64-bit integer type (see note below) - ``'f'``: 32-bit float type - ``'d'``: 64-bit float type + - ``'p'``: 32-bit or 64-bit pointer (MEMORY64) + +For example, if you add a function that takes an integer and does not return +anything, the signature is ``'vi'``. + +When ``'j'`` is used there are several ways in which the parameter value will +be passed to JavaScript. By default, the value will either be passed as a +single BigInt or a pair of JavaScript numbers (double) depending on whether +the ``WASM_BIGINT`` settings is enabled. In addition, if you only require 53 +bits of precision you can add the ``__i53abi`` decorator, which will ignore +the upper bits and the value will be received as a single JavaScript number +(double). It cannot be used with ``addFunction``. Here is an example of a +library function that sets the size of a file using a 64-bit value passed as +a 53 bit (double) and returns an integer error code: + +.. code-block:: c + + extern "C" int _set_file_size(int handle, uint64_t size); + +.. code-block:: javascript - For example, if you add a function that takes an integer and does not return - anything, you can do ``addFunction(your_function, 'vi');``. See - `test/interop/test_add_function_post.js `_ for an example. + _set_file_size__i53abi: true, // Handle 64-bit + _set_file_size__sig: 'iij', // Function signature + _set_file_size: function(handle, size) { ... return error; } + +Using ``-sWASM_BIGINT`` when linking is an alternative method of handling +64-bit types in libraries. ```Number()``` may be needed on the JavaScript +side to convert it to a useable value. See `settings reference `_. .. _interacting-with-code-access-memory: