diff --git a/crates/wasmtime/src/engine.rs b/crates/wasmtime/src/engine.rs index c367e9425a..f0c615fb2d 100644 --- a/crates/wasmtime/src/engine.rs +++ b/crates/wasmtime/src/engine.rs @@ -63,8 +63,23 @@ impl Engine { }) } - /// Eagerly initialize thread-local functionality shared by all [`Engine`]s. This - /// will be performed lazily by the runtime if users do not perform it eagerly. + /// Eagerly initialize thread-local functionality shared by all [`Engine`]s. + /// + /// Wasmtime's implementation on some platforms may involve per-thread + /// setup that needs to happen whenever WebAssembly is invoked. This setup + /// can take on the order of a few hundred microseconds, whereas the + /// overhead of calling WebAssembly is otherwise on the order of a few + /// nanoseconds. This setup cost is paid once per-OS-thread. If your + /// application is sensitive to the latencies of WebAssembly function + /// calls, even those that happen first on a thread, then this function + /// can be used to improve the consistency of each call into WebAssembly + /// by explicitly frontloading the cost of the one-time setup per-thread. + /// + /// Note that this function is not required to be called in any embedding. + /// Wasmtime will automatically initialize thread-local-state as necessary + /// on calls into WebAssembly. This is provided for use cases where the + /// latency of WebAssembly calls are extra-important, which is not + /// necessarily true of all embeddings. pub fn tls_eager_initialize() -> Result<(), Trap> { wasmtime_runtime::tls_eager_initialize().map_err(Trap::from_runtime) }