Merge pull request #2946 from bytecodealliance/pch/eager_per_thread_init

expose eager thread-local resource initialization on Engine

crates/runtime/src/lib.rs

@@ -49,8 +49,8 @@ pub use crate::memory::{Memory, RuntimeLinearMemory, RuntimeMemoryCreator};
 pub use crate::mmap::Mmap;
 pub use crate::table::{Table, TableElement};
 pub use crate::traphandlers::{
-    catch_traps, init_traps, raise_lib_trap, raise_user_trap, resume_panic, SignalHandler,
-    TlsRestore, Trap,
+    catch_traps, init_traps, raise_lib_trap, raise_user_trap, resume_panic, tls_eager_initialize,
+    SignalHandler, TlsRestore, Trap,
 };
 pub use crate::vmcontext::{
     VMCallerCheckedAnyfunc, VMContext, VMFunctionBody, VMFunctionImport, VMGlobalDefinition,

crates/runtime/src/traphandlers.rs

@@ -12,7 +12,7 @@ use std::sync::atomic::Ordering::SeqCst;
 use std::sync::Once;
 use wasmtime_environ::ir;
 
-pub use self::tls::TlsRestore;
+pub use self::tls::{tls_eager_initialize, TlsRestore};
 
 extern "C" {
     #[allow(improper_ctypes)]
@@ -386,12 +386,29 @@ mod tls {
             })
         }
 
+        #[inline(never)]
+        /// Eagerly initialize thread-local runtime functionality. This will be performed
+        /// lazily by the runtime if users do not perform it eagerly.
+        pub fn initialize() -> Result<(), Trap> {
+            PTR.with(|p| {
+                let (state, initialized) = p.get();
+                if initialized {
+                    return Ok(());
+                }
+                super::super::sys::lazy_per_thread_init()?;
+                p.set((state, true));
+                Ok(())
+            })
+        }
+
         #[inline(never)] // see module docs for why this is here
         pub fn get() -> Ptr {
             PTR.with(|p| p.get().0)
         }
     }
 
+    pub use raw::initialize as tls_eager_initialize;
+
     /// Opaque state used to help control TLS state across stack switches for
     /// async support.
     pub struct TlsRestore(raw::Ptr);

crates/wasmtime/src/engine.rs

@@ -1,5 +1,5 @@
 use crate::signatures::SignatureRegistry;
-use crate::Config;
+use crate::{Config, Trap};
 use anyhow::Result;
 use std::sync::Arc;
 #[cfg(feature = "cache")]
@@ -63,6 +63,27 @@ impl Engine {
         })
     }
 
+    /// 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)
+    }
+
     /// Returns the configuration settings that this engine is using.
     #[inline]
     pub fn config(&self) -> &Config {