This commit adds a new attribute to `#[wasm_bindgen]`: `start`. The
`start` attribute can be used to indicate that a function should be
executed when the module is loaded, configuring the `start` function of
the wasm executable. While this doesn't necessarily literally configure
the `start` section, it does its best!
Only one crate in a crate graph may indicate `#[wasm_bindgen(start)]`,
so it's not recommended to be used in libraries but only end-user
applications. Currently this still must be used with the `crate-type =
["cdylib"]` annotation in `Cargo.toml`.
The implementation here is somewhat tricky because of the circular
dependency between our generated JS and the wasm file that we emit. This
circular dependency makes running initialization routines (like the
`start` shim) particularly fraught with complications because one may
need to run before the other but bundlers may not necessarily respect
it. Workarounds have been implemented for various emission strategies,
for example calling the start function directly after exports are wired
up with `--no-modules` and otherwise working around what appears to be
a Webpack bug with initializers running in a different order than we'd
like. In any case, this in theory doesn't show up to the end user!
Closes#74
This commit implements a system that will assert that all
`#[wasm_bindgen]` attributes are actually used during compilation. This
should help ensure that we don't sneak in stray attributes that don't
actually end up having any meaning, and hopefully make it a bit easier
to learn `#[wasm_bindgen]`!
This commit adds an optimization to `wasm-bindgen` to directly import
and invoke other modules' functions from the wasm module, rather than
going through a shim in the imported bindings. This will be an important
optimization in the future for the host bindings proposal, but for now
it's largely just a proof-of-concept to show that we can do it and is
unlikely to bring about many performance benefits.
The implementation in this commit is largely refactoring to reorganize a
bit how functions are imported, but the implementation happens in
`generate_import_function`.
With this commit, 71/287 imports in the `tests/wasm/main.rs` suite get
hooked up directly to the ES modules, no shims needed!
This commit switches all imports of JS methods to `structural` by
default. Proposed in [RFC 5] this should increase the performance of
bindings today while also providing future-proofing for possible
confusion with the recent addition of the `Deref` trait for all imported
types by default as well.
A new attribute, `host_binding`, is introduced in this PR as well to
recover the old behavior of binding directly to an imported function
which will one day be the precise function on the prototype. Eventually
`web-sys` will switcsh over entirely to being driven via `host_binding`
methods, but for now it's been measured to be not quite as fast so we're
not making that switch yet.
Note that `host_binding` differs from the proposed name of `final` due
to the controversy, and its hoped that `host_binding` is a good
middle-ground!
[RFC 5]: https://rustwasm.github.io/rfcs/005-structural-and-deref.html
This commit fixes instantiation of the wasm module even if some of the
improted APIs don't exist. This extends the functionality initially
added in #409 to attempt to gracefully allow importing values from the
environment which don't actually exist in all contexts. In addition to
nonexistent methods being handled now entire nonexistent types are now
also handled.
I suspect that eventually we'll add a CLI flag to `wasm-bindgen` to say
"I assert everything exists, don't check it" to trim out the extra JS
glue generated here. In the meantime though this'll pave the way for a
wasm-bindgen shim to be instantiated in both a web worker and the main
thread, while using DOM-like APIs only on the main thread.
The bindings generation for a class would accidentally omit the `__wrap`
function if it was only discovered very late in the process that
`__wrap` was needed, after we'd already passed the point where we needed
to have decided that.
This commit moves struct field generation of bindings much earlier in
the binding generation process which should ensure everything is all
hooked up by the time we generate the classes themselves.
Closes#949
These compiler bugs have now been fixed on nightly, so we just need to
wait for the bug fixes to ride the trains to be available to everyone!
Closes#201
This commit improves the codegen for `Closure<T>`, primarily for ZST
where the closure doesn't actually capture anything. Previously
`wasm-bindgen` would unconditionally allocate an `Rc` for a fat pointer,
meaning that it would always hit the allocator even when the `Box<T>`
didn't actually contain an allocation. Now the reference count for the
closure is stored on the JS object rather than in Rust.
Some more advanced tests were added along the way to ensure that
functionality didn't regress, and otherwise the calling convention for
`Closure` changed a good deal but should still be the same user-facing.
The primary change was that the reference count reaching zero may cause
JS to need to run the destructor. It simply returns this information in
`Drop for Closure` and otherwise when calling it now also retains a
function pointer that runs the destructor.
Closes#874
This commit implements support for binding APIs that take
`Uint8ClampedArray` in JS. This is pretty rare but comes up in a
`web-sys` binding or two, and we're now able to bind these APIs instead
of having to omit the bindings.
The `Uint8ClampedArray` type is bound by using the `Clamped` marker
struct in Rust. For example this is declaring a JS API that takes
`Uint8ClampedArray`:
use wasm_bindgen::Clamped;
#[wasm_bindgen]
extern {
fn takes_clamped(a: Clamped<&[u8]>);
}
The `Clamped` type currently only works when wrapping the `&[u8]`, `&mut
[u8]`, and `Vec<u8>` types. Everything else will produce an error at
`wasm-bindgen` time.
Closes#421
This commit removes the need for an injected `ConstructorToken` type and
also cleans up the story we have for generating constructors a bit.
After this commit a `constructor()` is omitted entirely if we're in
non-debug mode and there's no actual listed constructor. Additionally we
don't deal with splat arguments and rerouting constructors, Nick was
kind enough to enlighten me about `Object.create` which is creating an
instance without running the constructor!
Instances of an exported type are now created through one of two
methods:
* If `#[wasm_bindgen(constructor)]` is present, then a `constructor` is
generated with the appropriate signature. If a constructor is not
present and we're in debug mode, a throwing constructor is generated.
If we're in release mode and there's no constructor, no constructor is
generated.
* Otherwise if a binding returns an instance of a type (or otherwise
needs to manfuacture an instance, then it will cause an internal
`__wrap` function to be generated. This function will use
`Object.create` to create an instance without running the constructor.
This should ideally clean up our generated JS for classes quite a bit,
making it much more lean-and-mean!
This commit is a large-ish scale reorganization of our examples. The
main goal here is to have a dedicated section of the guide for example,
and all examples will be listed there. Each example's `README` is now
just boilerplate pointing at the guide along with a blurb about how to
run it.
Some examples like `math` and `smorgasboard` have been deleted as they
didn't really serve much purpose, and others like `closures` have been
rewritten with `web-sys` instead of hand-bound bindings.
Overall it's hoped that this puts us in a good and consistent state for
our examples, with all of them being described in the guide, excerpts
are in the guide, and they're all relatively idiomatically using
`web-sys`.
This commit adds support for exporting a function defined in Rust that returns a
`Result`, translating the `Ok` variant to the actual return value and the `Err`
variant to an exception that's thrown in JS.
The support for return types and descriptors was rejiggered a bit to be a bit
more abstract and more well suited for this purpose. We no longer distinguish
between functions with a return value and those without a return value.
Additionally a new trait, `ReturnWasmAbi`, is used for converting return values.
This trait is an internal implementation detail, however, and shouldn't surface
itself to users much (if at all).
Closes#841
In addition to closing #495 this'll be useful eventually when instantiating
multiple wasm modules from Rust as you'd now be able to acquire a reference to
the current module in Rust itself.
This commit fixes annotations that include both the `constructor` and `catch`
attributes on imported types, ensuring that we infer the right type being
returned after extracting the first type parameter of the `Result`.
Closes#735
This commit implements the `extends` attribute for `#[wasm_bindgen]` to
statically draw the inheritance hierarchy in the generated bindings, generating
appropriate `AsRef`, `AsMut`, and `From` implementations.
This commit implements the `JsCast` trait automatically for all imported types
in `#[wasm_bindgen] extern { ... }` blocks. The main change here was to generate
an `instanceof` shim for all imported types in case it's needed.
All imported types now also implement `AsRef<JsValue>` and `AsMut<JsValue>`
We'll soon no longer have a great way to test this in the repository, but the
support has effectively never regressed so far. Let's rely on user-facing bug
reports for now and otherwise we can add this back in later if necessary.
First added in #161 this never ended up panning out, so let's remove the
experimental suport which isn't actually used by anything today and hold off on
any other changes until an RFC happens.
This commit starts migrating the `wasm_bindgen` tests to the `wasm_bindgen_test`
framework, starting to assemble the coffin for
`wasm-bindgen-test-project-builder`. Over time all of the tests in
`tests/all/*.rs` should be migrated to `wasm_bindgen_test`, although they may
not all want to go into a monolithic test suite so we can continue to test for
some more subtle situations with `#[wasm_bindgen]`.
In the meantime those, the `tests/all/api.rs` tests can certainly migrate!
* Fix importing the same identifier from two modules
This needed a fix in two locations:
* First the generated descriptor function needed its hash to include the module
that the import came from in order to generate unique descriptor functions.
* Second the generation of the JS shim needed to handle duplicate identifiers in
a more uniform fashion, ensuring that imported names didn't clash.
* Fix importing the same name in two modules
Previously two descriptor functions with duplicate symbols were emitted, and now
only one function is emitted by using a global table to keep track of state
across macro invocations.
* Shard the `convert.rs` module into sub-modules
Hopefully this'll make the organization a little nicer over time!
* Start adding support for optional types
This commit starts adding support for optional types to wasm-bindgen as
arguments/return values to functions. The strategy here is to add two new
traits, `OptionIntoWasmAbi` and `OptionFromWasmAbi`. These two traits are used
as a blanket impl to implement `IntoWasmAbi` and `FromWasmAbi` for `Option<T>`.
Some consequences of this design:
* It should be possible to ensure `Option<SomeForeignType>` implements to/from
wasm traits. This is because the option-based traits can be implemented for
foreign types.
* A specialized implementation is possible for all types, so there's no need for
`Option<T>` to introduce unnecessary overhead.
* Two new traits is a bit unforutnate but I can't currently think of an
alternative design that works for the above two constraints, although it
doesn't mean one doesn't exist!
* The error messages for "can't use this type here" is actually halfway decent
because it says these new traits need to be implemented, which provides a good
place to document and talk about what's going on here!
* Nested references like `Option<&T>` can't implement `FromWasmAbi`. This means
that you can't define a function in Rust which takes `Option<&str>`. It may be
possible to do this one day but it'll likely require more trait trickery than
I'm capable of right now.
* Add support for optional slices
This commit adds support for optional slice types, things like strings and
arrays. The null representation of these has a pointer value of 0, which should
never happen in normal Rust. Otherwise the various plumbing is done throughout
the tooling to enable these types in all locations.
* Fix `takeObject` on global sentinels
These don't have a reference count as they're always expected to work, so avoid
actually dropping a reference on them.
* Remove some no longer needed bindings
* Add support for optional anyref types
This commit adds support for optional imported class types. Each type imported
with `#[wasm_bindgen]` automatically implements the relevant traits and now
supports `Option<Foo>` in various argument/return positions.
* Fix building without the `std` feature
* Actually fix the build...
* Add support for optional types to WebIDL
Closes#502
* Move the `js` module to a `js_sys` crate
* Update js-sys tests to pass again
* Update binding_to_unimplemented_apis_doesnt_break_everything
Remove its dependency on the `js` module
* Update metadata for js-sys
* Fix the `closures` example
Not a lot of attention has been paid to dealing with conflicts of symbols
between crates and different `#[wasm_bindgen]` blocks. This commit starts to fix
this issue by unblocking #486 which first ran into this. Currently there's a bug
where if two independent crates bind the same JS API they'll generate the same
symbol which causes conflicts for things like LTO or linking in general.
This commit starts to add a "salt" to all symbols generated by `wasm-bindgen`
(these are all transparent to the user) to ensure that each crate's invocations
are kept apart from one another and using the correct bindings.
