Document WebAssembly support

README.md

@@ -102,9 +102,9 @@ registered at the time that dlopen occurs.
 
 [`ctor`]: https://github.com/mmastrac/rust-ctor
 
-Platform support includes Linux, macOS, iOS, FreeBSD, Android, Windows, and a
-few others. Beyond this, other platforms will simply find that no plugins have
-been registered.
+Platform support includes Linux, macOS, iOS, FreeBSD, Android, Windows,
+WebAssembly, and a few others. Beyond this, other platforms will simply find
+that no plugins have been registered.
 
 For a different approach to plugin registration that *does not* involve
 life-before-main, see the [`linkme`] crate.

src/lib.rs

@@ -101,6 +101,37 @@
 //!
 //! There is no guarantee about the order that plugins of the same type are
 //! visited by the iterator. They may be visited in any order.
+//!
+//! ## WebAssembly and constructors
+//!
+//! `inventory` supports all WebAssembly targets, including
+//! `wasm*-unknown-unknown`. However, in unusual circumstances, ensuring that
+//! constructors run may require some extra effort. The WASM linker will
+//! generate a function `extern "C" unsafe fn __wasm_call_ctors()` which calls
+//! all constructors when invoked; this function will *not* be exported from the
+//! module unless you do so explicitly. Depending on the result of a heuristic,
+//! the linker may or may not insert a call to this function from the beginning
+//! of every function that your module exports. Specifically, it regards a
+//! module as having "command-style linkage" if:
+//!
+//! * it is not relocatable;
+//! * it is not a position-independent executable;
+//! * and it does not call `__wasm_call_ctors`, directly or indirectly, from any
+//!   exported function.
+//!
+//! The linker expects that the embedder will call into a command-style module
+//! only once per instantiation. Violation of this expectation can result in
+//! `__wasm_call_ctors` being called multiple times. This is dangerous in
+//! general, but safe and mostly harmless in the case of constructors generated
+//! by `inventory`, which ensure their own idempotence.
+//!
+//! If you are building a module which relies on constructors and may be called
+//! into multiple times per instance, you should export `__wasm_call_ctors` (or
+//! a wrapper around it) and ensure that the embedder calls it immediately after
+//! instantiation. Even though `inventory` may work fine without this, it is
+//! still good practice, because it avoids unnecessary overhead from repeated
+//! constructor invocation. It also can prevent unsoundness if some of your
+//! constructors are generated by other crates or other programming languages.
 
 #![doc(html_root_url = "https://docs.rs/inventory/0.3.16")]
 #![no_std]