fluencelabs/wasm-bindgen
1
0
Fork 0
mirror of https://github.com/fluencelabs/wasm-bindgen synced 2025-05-02 00:52:16 +00:00
Code Issues Projects Releases Wiki Activity
wasm-bindgen/reference/attributes/on-js-imports/final.html

373 lines
32 KiB
HTML
Raw Normal View History

Deploy 64e53a5502d92143ff312d461c286cc22522c8ae to gh-pages
2020-06-11 14:25:32 +00:00
<!DOCTYPE HTML>
<html lang="en" class="sidebar-visible no-js">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>final - The `wasm-bindgen` Guide</title>
<meta content="text/html; charset=utf-8" http-equiv="Content-Type">
<meta name="description" content="">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="theme-color" content="#ffffff" />
<link rel="shortcut icon" href="../../../favicon.png">
<link rel="stylesheet" href="../../../css/variables.css">
<link rel="stylesheet" href="../../../css/general.css">
<link rel="stylesheet" href="../../../css/chrome.css">
<link rel="stylesheet" href="../../../css/print.css" media="print">
<!-- Fonts -->
<link rel="stylesheet" href="../../../FontAwesome/css/font-awesome.css">
<link href="https://fonts.googleapis.com/css?family=Open+Sans:300italic,400italic,600italic,700italic,800italic,400,300,600,700,800" rel="stylesheet" type="text/css">
<link href="https://fonts.googleapis.com/css?family=Source+Code+Pro:500" rel="stylesheet" type="text/css">
<!-- Highlight.js Stylesheets -->
<link rel="stylesheet" href="../../../highlight.css">
<link rel="stylesheet" href="../../../tomorrow-night.css">
<link rel="stylesheet" href="../../../ayu-highlight.css">
<!-- Custom theme stylesheets -->
</head>
<body class="light">
<!-- Provide site root to javascript -->
<script type="text/javascript">
var path_to_root = "../../../";
var default_theme = "light";
</script>
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script type="text/javascript">
try {
var theme = localStorage.getItem('mdbook-theme');
var sidebar = localStorage.getItem('mdbook-sidebar');
if (theme.startsWith('"') && theme.endsWith('"')) {
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
}
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
}
} catch (e) { }
</script>
<!-- Set the theme before any content is loaded, prevents flash -->
<script type="text/javascript">
var theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
document.body.className = theme;
document.querySelector('html').className = theme + ' js';
</script>
<!-- Hide / unhide sidebar before it is displayed -->
<script type="text/javascript">
var html = document.querySelector('html');
var sidebar = 'hidden';
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
}
html.classList.remove('sidebar-visible');
html.classList.add("sidebar-" + sidebar);
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<div class="sidebar-scrollbox">
<ol class="chapter"><li class="affix"><a href="../../../introduction.html">Introduction</a></li><li class="spacer"></li><li><a href="../../../examples/index.html"><strong aria-hidden="true">1.</strong> Examples</a></li><li><ol class="section"><li><a href="../../../examples/hello-world.html"><strong aria-hidden="true">1.1.</strong> Hello, World!</a></li><li><a href="../../../examples/console-log.html"><strong aria-hidden="true">1.2.</strong> Using console.log</a></li><li><a href="../../../examples/add.html"><strong aria-hidden="true">1.3.</strong> Small wasm files</a></li><li><a href="../../../examples/without-a-bundler.html"><strong aria-hidden="true">1.4.</strong> Without a Bundler</a></li><li><a href="../../../examples/wasm2js.html"><strong aria-hidden="true">1.5.</strong> Converting WebAssembly to JS</a></li><li><a href="../../../examples/import-js.html"><strong aria-hidden="true">1.6.</strong> Importing functions from JS</a></li><li><a href="../../../examples/char.html"><strong aria-hidden="true">1.7.</strong> Working with char</a></li><li><a href="../../../examples/wasm-in-wasm.html"><strong aria-hidden="true">1.8.</strong> js-sys: WebAssembly in WebAssembly</a></li><li><a href="../../../examples/dom.html"><strong aria-hidden="true">1.9.</strong> web-sys: DOM hello world</a></li><li><a href="../../../examples/closures.html"><strong aria-hidden="true">1.10.</strong> web-sys: Closures</a></li><li><a href="../../../examples/performance.html"><strong aria-hidden="true">1.11.</strong> web-sys: performance.now</a></li><li><a href="../../../examples/fetch.html"><strong aria-hidden="true">1.12.</strong> web-sys: using fetch</a></li><li><a href="../../../examples/2d-canvas.html"><strong aria-hidden="true">1.13.</strong> web-sys: canvas hello world</a></li><li><a href="../../../examples/julia.html"><strong aria-hidden="true">1.14.</strong> web-sys: canvas Julia set</a></li><li><a href="../../../examples/web-audio.html"><strong aria-hidden="true">1.15.</strong> web-sys: WebAudio</a></li><li><a href="../../../examples/webgl.html"><strong aria-hidden="true">1.16.</strong> web-sys: WebGL</a></li><li><a href="../../../examples/websockets.html"><strong aria-hidden="true">1.17.</strong> web-sys: WebSockets</a></li><li><a href="../../../examples/webrtc_datachannel.html"><strong aria-hidden="true">1.18.</strong> web-sys: WebRTC DataChannel</a></li><li><a href="../../../examples/request-animation-frame.html"><strong aria-hidden="true">1.19.</strong> web-sys: requestAnimationFrame</a></li><li><a href="../../../examples/paint.html"><strong aria-hidden="true">1.20.</strong> web-sys: A Simple Paint Program</a></li><li><a href="../../../examples/raytrace.html"><strong aria-hidden="true">1.21.</strong> Parallel Raytracing</a></li><li><a href="../../../examples/todomvc.html"><strong aria-hidden="true">1.22.</strong> web-sys: A TODO MVC App</a></li></ol></li><li><a href="../../../reference/index.html"><strong aria-hidden="true">2.</strong> Reference</a></li><li><ol class="section"><li><a href="../../../reference/deployment.html"><strong aria-hidden="true">2.1.</strong> Deployment</a></li><li><a href="../../../reference/js-snippets.html"><strong aria-hidden="true">2.2.</strong> JS snippets</a></li><li><a href="../../../reference/passing-rust-closures-to-js.html"><strong aria-hidden="true">2.3.</strong> Passing Rust Closures to JS</a></li><li><a href="../../../reference/receiving-js-closures-in-rust.html"><strong aria-hidden="true">2.4.</strong> Receiving JS Closures in Rust</a></li><li><a href="../../../reference/js-promises-and-rust-futures.html"><strong aria-hidden="true">2.5.</strong> Promises and Futures</a></li><li><a href="../../../reference/iterating-over-js-values.html"><strong aria-hidden="true">2.6.</strong> Iterating over JS Values</a></li><li><a href="../../../reference/arbitrary-data-with-serde.html"><strong aria-hidden="true">2.7.</strong> Arbitrary Data with Serde</a></li><li><a href="../../../reference/accessing-properties-of-untyped-js-values.html"><strong aria-hidden="true">2.8.</strong> Accessing Properties o
</div>
<div id="sidebar-resize-handle" class="sidebar-resize-handle"></div>
</nav>
<div id="page-wrapper" class="page-wrapper">
<div class="page">
<style>
header.warning {
background-color: rgb(242, 222, 222);
border-bottom-color: rgb(238, 211, 215);
border-bottom-left-radius: 4px;
border-bottom-right-radius: 4px;
border-bottom-style: solid;
border-bottom-width: 0.666667px;
border-image-outset: 0 0 0 0;
border-image-repeat: stretch stretch;
border-image-slice: 100% 100% 100% 100%;
border-image-source: none;
border-image-width: 1 1 1 1;
border-left-color: rgb(238, 211, 215);
border-left-style: solid;
border-left-width: 0.666667px;
border-right-color: rgb(238, 211, 215);
border-right-style: solid;
border-right-width: 0.666667px;
border-top-color: rgb(238, 211, 215);
border-top-left-radius: 4px;
border-top-right-radius: 4px;
border-top-style: solid;
border-top-width: 0.666667px;
color: rgb(185, 74, 72);
margin-bottom: 0px;
margin-left: 0px;
margin-right: 0px;
margin-top: 30px;
padding-bottom: 8px;
padding-left: 14px;
padding-right: 35px;
padding-top: 8px;
text-align: center;
}
</style>
<header class='warning'>
This is the <strong>unpublished</strong> documentation of
<code>wasm-bindgen</code>, the published documentation is available
<a href="https://rustwasm.github.io/docs/wasm-bindgen/">
on the main Rust and WebAssembly documentation site
</a>. Features documented here may not be available in released versions of
<code>wasm-bindgen</code>.
</header>
<div id="menu-bar" class="menu-bar">
<div id="menu-bar-sticky-container">
<div class="left-buttons">
<button id="sidebar-toggle" class="icon-button" type="button" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</button>
<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
<i class="fa fa-paint-brush"></i>
</button>
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
<li role="none"><button role="menuitem" class="theme" id="light">Light (default)</button></li>
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
</ul>
<button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
<i class="fa fa-search"></i>
</button>
</div>
<h1 class="menu-title">The `wasm-bindgen` Guide</h1>
<div class="right-buttons">
<a href="../../../print.html" title="Print this book" aria-label="Print this book">
<i id="print-button" class="fa fa-print"></i>
</a>
</div>
</div>
</div>
<div id="search-wrapper" class="hidden">
<form id="searchbar-outer" class="searchbar-outer">
<input type="search" name="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
</form>
<div id="searchresults-outer" class="searchresults-outer hidden">
<div id="searchresults-header" class="searchresults-header"></div>
<ul id="searchresults">
</ul>
</div>
</div>
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
<script type="text/javascript">
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
});
</script>
<div id="content" class="content">
<main>
<h1><a class="header" href="#final" id="final"><code>final</code></a></h1>
<p>The <code>final</code> attribute is the converse of the <a href="structural.html"><code>structural</code>
attribute</a>. It configures how <code>wasm-bindgen</code> will generate JS
imports to call the imported function. Notably a function imported by <code>final</code>
never changes after it was imported, whereas a function imported by default (or
with <code>structural</code>) is subject to runtime lookup rules such as walking the
prototype chain of an object.</p>
<p>The <code>final</code> attribute is intended to be purely related to performance. It
ideally has no user-visible effect, and <code>structural</code> imports (the default)
should be able to transparently switch to <code>final</code> eventually.</p>
<p>The eventual performance aspect is that with the <a href="https://github.com/WebAssembly/host-bindings">host bindings
proposal</a> then <code>wasm-bindgen</code> will need to generate far fewer JS
function shims to import than it does today. For example, consider this import
today:</p>
<pre><pre class="playpen"><code class="language-rust">
# #![allow(unused_variables)]
#fn main() {
#[wasm_bindgen]
extern &quot;C&quot; {
type Foo;
#[wasm_bindgen(method)]
fn bar(this: &amp;Foo, argument: &amp;str) -&gt; JsValue;
}
#}</code></pre></pre>
<p><strong>Without the <code>final</code> attribute</strong> the generated JS looks like this:</p>
<pre><code class="language-js">// without `final`
export function __wbg_bar_a81456386e6b526f(arg0, arg1, arg2) {
let varg1 = getStringFromWasm(arg1, arg2);
return addHeapObject(getObject(arg0).bar(varg1));
}
</code></pre>
<p>We can see here that this JS function shim is required, but it's all relatively
self-contained. It does, however, execute the <code>bar</code> method in a duck-type-y
fashion in the sense that it never validates <code>getObject(arg0)</code> is of type <code>Foo</code>
to actually call the <code>Foo.prototype.bar</code> method.</p>
<p>If we instead, however, write this:</p>
<pre><pre class="playpen"><code class="language-rust">
# #![allow(unused_variables)]
#fn main() {
#[wasm_bindgen]
extern &quot;C&quot; {
type Foo;
#[wasm_bindgen(method, final)] // note the change here
fn bar(this: &amp;Foo, argument: &amp;str) -&gt; JsValue;
}
#}</code></pre></pre>
<p>it generates this JS glue (roughly):</p>
<pre><code class="language-js">const __wbg_bar_target = Foo.prototype.bar;
export function __wbg_bar_a81456386e6b526f(arg0, arg1, arg2) {
let varg1 = getStringFromWasm(arg1, arg2);
return addHeapObject(__wbg_bar_target.call(getObject(arg0), varg1));
}
</code></pre>
<p>The difference here is pretty subtle, but we can see how the function being
called is hoisted out of the generated shim and is bound to always be
<code>Foo.prototype.bar</code>. This then uses the <code>Function.call</code> method to invoke that
function with <code>getObject(arg0)</code> as the receiver.</p>
<p>But wait, there's still a JS function shim here even with <code>final</code>! That's true,
and this is simply a fact of future WebAssembly proposals not being implemented
yet. The semantics, though, match the future <a href="https://github.com/WebAssembly/host-bindings">host bindings
proposal</a> because the method being called is determined exactly
once, and it's located on the prototype chain rather than being resolved at
runtime when the function is called.</p>
<h2><a class="header" href="#interaction-with-future-proposals" id="interaction-with-future-proposals">Interaction with future proposals</a></h2>
<p>If you're curious to see how our JS function shim will be eliminated entirely,
let's take a look at the generated bindings. We're starting off with this:</p>
<pre><code class="language-js">const __wbg_bar_target = Foo.prototype.bar;
export function __wbg_bar_a81456386e6b526f(arg0, arg1, arg2) {
let varg1 = getStringFromWasm(arg1, arg2);
return addHeapObject(__wbg_bar_target.call(getObject(arg0), varg1));
}
</code></pre>
<p>... and once the <a href="https://github.com/WebAssembly/reference-types">reference types proposal</a> is implemented then
we won't need some of these pesky functions. That'll transform our generated JS
shim to look like:</p>
<pre><code class="language-js">const __wbg_bar_target = Foo.prototype.bar;
export function __wbg_bar_a81456386e6b526f(arg0, arg1, arg2) {
let varg1 = getStringFromWasm(arg1, arg2);
return __wbg_bar_target.call(arg0, varg1);
}
</code></pre>
<p>Getting better! Next up we need the host bindings proposal. Note that the
proposal is undergoing some changes right now so it's tough to link to reference
documentation, but it suffices to say that it'll empower us with at least two
different features.</p>
<p>First, host bindings promises to provide the concept of &quot;argument conversions&quot;.
The <code>arg1</code> and <code>arg2</code> values here are actually a pointer and a length to a utf-8
encoded string, and with host bindings we'll be able to annotate that this
import should take those two arguments and convert them to a JS string (that is,
the <em>host</em> should do this, the WebAssembly engine). Using that feature we can
futher trim this down to:</p>
<pre><code class="language-js">const __wbg_bar_target = Foo.prototype.bar;
export function __wbg_bar_a81456386e6b526f(arg0, varg1) {
return __wbg_bar_target.call(arg0, varg1);
}
</code></pre>
<p>And finally, the second promise of the host bindings proposal is that we can
flag a function call to indicate the first argument is the <code>this</code> binding of the
function call. Today the <code>this</code> value of all called imported functions is
<code>undefined</code>, and this flag (configured with host bindings) will indicate the
first argument here is actually the <code>this</code>.</p>
<p>With that in mind we can further transform this to:</p>
<pre><code class="language-js">export const __wbg_bar_a81456386e6b526f = Foo.prototype.bar;
</code></pre>
<p>and voila! We, with <a href="https://github.com/WebAssembly/reference-types">reference types</a> and <a href="https://github.com/WebAssembly/host-bindings">host
bindings</a>, now have no JS function shim at all necessary to call
the imported function. Additionally future wasm proposals to the ES module
system may also mean that don't even need the <code>export const ...</code> here too.</p>
<p>It's also worth pointing out that with all these wasm proposals implemented the
default way to import the <code>bar</code> function (aka <code>structural</code>) would generate a JS
function shim that looks like:</p>
<pre><code class="language-js">export function __wbg_bar_a81456386e6b526f(varg1) {
return this.bar(varg1);
}
</code></pre>
<p>where this import is still subject to runtime prototype chain lookups and such.</p>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="../../../reference/attributes/on-js-imports/getter-and-setter.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
<i class="fa fa-angle-left"></i>
</a>
<a rel="next" href="../../../reference/attributes/on-js-imports/indexing-getter-setter-deleter.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<i class="fa fa-angle-right"></i>
</a>
<div style="clear: both"></div>
</nav>
</div>
</div>
<nav class="nav-wide-wrapper" aria-label="Page navigation">
<a href="../../../reference/attributes/on-js-imports/getter-and-setter.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
<i class="fa fa-angle-left"></i>
</a>
<a href="../../../reference/attributes/on-js-imports/indexing-getter-setter-deleter.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<i class="fa fa-angle-right"></i>
</a>
</nav>
</div>
<script src="../../../elasticlunr.min.js" type="text/javascript" charset="utf-8"></script>
<script src="../../../mark.min.js" type="text/javascript" charset="utf-8"></script>
<script src="../../../searcher.js" type="text/javascript" charset="utf-8"></script>
<script src="../../../clipboard.min.js" type="text/javascript" charset="utf-8"></script>
<script src="../../../highlight.js" type="text/javascript" charset="utf-8"></script>
<script src="../../../book.js" type="text/javascript" charset="utf-8"></script>
<!-- Custom JS scripts -->
</body>
</html>
Reference in New Issue Copy Permalink