A lightweight WebAssembly runtime that is fast, secure, and standards-compliant
//! Static analysis of "thread transparency" for fused adapters.
//!
//! Every fused sync adapter normally brackets its callee with
//! `enter-sync-call`/`exit-sync-call`. That pair saves the caller's
//! component-model thread state (`current_thread`, the context slots, the "may
//! block" flag, etc...) and installs fresh state for the callee, restoring the
//! caller's state on the way back out.
//!
//! However, that bracketing is only necessary if the callee can observe that
//! thread state. If it cannot, the callee may simply run on top of whatever
//! thread state the caller left in place, and the adapter can skip the
//! save/restore entirely. We call such an adapter "thread transparent".
//!
//! Core Wasm state cannot be shared between components, so the only way core
//! Wasm can touch component-model thread state is by calling a `canon lower`ed
//! function or a canonical built-in. All of those are declared by a particular
//! component instance and are only reachable from core Wasm belonging to that
//! same component instance.
//!
//! Therefore this analysis works per component instance: an adapter whose
//! callee instance declares nothing capable of touching thread state is
//! transparent.
//!
//! Note that (lack of) transparency is not transitive across component
//! instances because a call into an opaque instance will itself save/restore
//! the thread state, even if none of its transparent callers needed to.
use crate::component::dfg::{
AdapterId, CanonicalOptionsDataModel, ComponentDfg, CoreDef, Export, Instance, SideEffect,
Trampoline,
};
use crate::component::{
ComponentTypesBuilder, DataModel, RuntimeComponentInstanceIndex, UnsafeIntrinsic,
};
use cranelift_entity::EntitySet;
/// Something a component instance makes callable by its core Wasm instances.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
enum CoreCallable {
/// A `canon lower` of a function imported from the host.
///
/// The host can do anything at all, including reading and writing the
/// current thread's context slots.
HostImport,
/// A `canon lower` of a guest function that was `canon lift`ed elsewhere.
Adapter {
/// Whether the function on the lifting side uses the `async` ABI.
async_lift: bool,
},
/// A `canon context.get` or `canon context.set`.
ContextAccess,
/// Any other canonical built-in that reads or writes thread state:
/// `resource.*`, `backpressure.*`, `task.*`, `waitable*.*`, `subtask.*`,
/// `stream.*`, `future.*`, `error-context.*`, or `thread.*`.
ThreadStateBuiltin,
/// Something that cannot touch thread state at all: a plain core function,
/// a string transcoder, a non-context Wasmtime intrinsic, and so on.
Inert,
}
impl CoreCallable {
/// Can calling this reach code that reads or writes component-model thread
/// state?
fn may_touch_thread_state(self) -> bool {
match self {
// The host is unconstrained.
CoreCallable::HostImport => true,
// A sync-lifted callee is reached through its own fused adapter,
// which saves and restores whatever it needs; nothing about that
// call is visible in this instance's thread state.
//
// An async-lifted callee is different: it may block, and if it
// does the scheduler has to find the sync-typed call in progress
// on this instance, which means this instance needs real thread
// state of its own.
CoreCallable::Adapter { async_lift } => async_lift,
CoreCallable::ContextAccess | CoreCallable::ThreadStateBuiltin => true,
CoreCallable::Inert => false,
}
}
}
/// Everything about one fused adapter that bears on whether it can skip its
/// `{enter,exit}-sync-call` window.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
struct AdapterFacts {
/// The component instance whose core Wasm this adapter calls into, i.e.
/// the instance that did the `canon lift`.
callee: RuntimeComponentInstanceIndex,
/// Whether either side of this adapter is `async` in either its canonical
/// options or function signature.
any_async: bool,
/// Whether either function signature mentions a handle.
any_handle: bool,
}
/// A builder for a `ThreadTransparency`.
///
/// Accumulates the observations that ultimately produce the
/// `ThreadTransparency` analysis.
#[derive(Default)]
struct ThreadTransparencyBuilder {
/// The component instances observed to be able to touch thread state.
opaque: EntitySet<RuntimeComponentInstanceIndex>,
}
impl ThreadTransparencyBuilder {
/// Record that `instance` makes `callable` available to its core Wasm.
fn observe(&mut self, instance: RuntimeComponentInstanceIndex, callable: CoreCallable) {
if callable.may_touch_thread_state() {
self.opaque.insert(instance);
}
}
/// Finish observing and produce the queryable analysis results.
fn finish(self) -> ThreadTransparency {
ThreadTransparency {
opaque: self.opaque,
}
}
}
/// A completed thread-transparency analysis, ready to be queried.
struct ThreadTransparency {
/// The component instances that can touch thread state.
opaque: EntitySet<RuntimeComponentInstanceIndex>,
}
impl ThreadTransparency {
/// May the adapter described by `facts` omit its `{enter,exit}-sync-call`
/// window?
fn adapter_is_transparent(&self, facts: AdapterFacts) -> bool {
// Async adapters genuinely need thread state of their own.
if facts.any_async {
return false;
}
// Transferring handles across an instance boundary unconditionally
// requires thread state for now.
if facts.any_handle {
return false;
}
!self.opaque.contains(facts.callee)
}
}
/// Run the thread-transparency analysis over `dfg`, returning the set of
/// adapters that may skip their `{enter,exit}-sync-call` window.
pub fn transparent_adapters(
dfg: &ComponentDfg,
types: &ComponentTypesBuilder,
) -> EntitySet<AdapterId> {
let mut builder = ThreadTransparencyBuilder::default();
// Observe canonical built-ins.
for (_, (_, trampoline)) in dfg.trampolines.iter() {
let (instance, callable) = trampoline_callable(dfg, trampoline);
builder.observe(instance, callable);
}
// Observe fused adapters.
for (_, adapter) in dfg.adapters.iter() {
let async_lift = types[adapter.lift_ty].async_;
builder.observe(
adapter.lower_options.instance,
CoreCallable::Adapter { async_lift },
);
}
// Observe `CoreDef`s.
for_each_core_def(dfg, |instance, def| {
builder.observe(instance, core_def_callable(def));
});
// Finish the analysis and query its results to determine the set of
// adapters that are transparent.
let analysis = builder.finish();
let mut transparent = EntitySet::new();
for (id, adapter) in dfg.adapters.iter() {
if analysis.adapter_is_transparent(facts(types, adapter)) {
transparent.insert(id);
}
}
transparent
}
fn facts(types: &ComponentTypesBuilder, adapter: &super::Adapter) -> AdapterFacts {
AdapterFacts {
callee: adapter.lift_options.instance,
any_async: adapter.lift_options.async_
|| adapter.lower_options.async_
|| types[adapter.lift_ty].async_
|| types[adapter.lower_ty].async_,
any_handle: types.func_contains_any_handle(adapter.lift_ty)
|| types.func_contains_any_handle(adapter.lower_ty),
}
}
/// Classify a `CoreDef` that some component instance references.
fn core_def_callable(def: &CoreDef) -> CoreCallable {
// NB: deliberately exhaustive so that new variants must be classified here.
match def {
CoreDef::UnsafeIntrinsic(_, intrinsic) => match intrinsic {
UnsafeIntrinsic::ContextGetI32_0
| UnsafeIntrinsic::ContextSetI32_0
| UnsafeIntrinsic::ContextGetI32_1
| UnsafeIntrinsic::ContextSetI32_1 => CoreCallable::ContextAccess,
// Unsafe intrinsics can't access thread state.
UnsafeIntrinsic::StoreDataAddress
| UnsafeIntrinsic::U8NativeLoad
| UnsafeIntrinsic::U8NativeStore
| UnsafeIntrinsic::U16NativeLoad
| UnsafeIntrinsic::U16NativeStore
| UnsafeIntrinsic::U32NativeLoad
| UnsafeIntrinsic::U32NativeStore
| UnsafeIntrinsic::U64NativeLoad
| UnsafeIntrinsic::U64NativeStore
| UnsafeIntrinsic::U8CheckedNativeLoad
| UnsafeIntrinsic::U8CheckedNativeStore
| UnsafeIntrinsic::U16CheckedNativeLoad
| UnsafeIntrinsic::U16CheckedNativeStore
| UnsafeIntrinsic::U32CheckedNativeLoad
| UnsafeIntrinsic::U32CheckedNativeStore
| UnsafeIntrinsic::U64CheckedNativeLoad
| UnsafeIntrinsic::U64CheckedNativeStore => CoreCallable::Inert,
},
// Trampolines and adapters are observed directly in
// `transparent_adapters`, so we don't need to worry about them here.
CoreDef::Trampoline(_) | CoreDef::Adapter(_) => CoreCallable::Inert,
// Plain core Wasm; can't introduce any state-access capability that
// isn't already there.
CoreDef::Export(_) | CoreDef::InstanceFlags(_) => CoreCallable::Inert,
}
}
/// Classify a trampoline, and identify the component instance that declared it.
fn trampoline_callable(
dfg: &ComponentDfg,
trampoline: &Trampoline,
) -> (RuntimeComponentInstanceIndex, CoreCallable) {
use Trampoline::*;
// NB: deliberately exhaustive so that new variants must be classified here.
match trampoline {
LowerImport { options, .. } => (dfg.options[*options].instance, CoreCallable::HostImport),
ResourceNew { instance, .. }
| ResourceRep { instance, .. }
| ResourceDrop { instance, .. }
| BackpressureInc { instance }
| BackpressureDec { instance }
| TaskReturn { instance, .. }
| TaskCancel { instance }
| WaitableSetNew { instance }
| WaitableSetWait { instance, .. }
| WaitableSetPoll { instance, .. }
| WaitableSetDrop { instance }
| WaitableJoin { instance }
| SubtaskDrop { instance }
| SubtaskCancel { instance, .. }
| StreamNew { instance, .. }
| StreamRead { instance, .. }
| StreamWrite { instance, .. }
| StreamCancelRead { instance, .. }
| StreamCancelWrite { instance, .. }
| StreamDropReadable { instance, .. }
| StreamDropWritable { instance, .. }
| FutureNew { instance, .. }
| FutureRead { instance, .. }
| FutureWrite { instance, .. }
| FutureCancelRead { instance, .. }
| FutureCancelWrite { instance, .. }
| FutureDropReadable { instance, .. }
| FutureDropWritable { instance, .. }
| ErrorContextNew { instance, .. }
| ErrorContextDebugMessage { instance, .. }
| ErrorContextDrop { instance, .. }
| ThreadIndex { instance }
| ThreadNewIndirect { instance, .. }
| ThreadResumeLater { instance }
| ThreadSuspend { instance, .. }
| ThreadYield { instance, .. }
| ThreadSuspendThenResume { instance, .. }
| ThreadYieldThenResume { instance, .. }
| ThreadSuspendThenPromote { instance, .. }
| ThreadYieldThenPromote { instance, .. } => (*instance, CoreCallable::ThreadStateBuiltin),
// These trampolines are only ever created in `translate::adapt`, which
// happens strictly after this analysis has run. Therefore none of them
// can exist yet.
Transcoder { .. }
| ResourceTransferOwn
| ResourceTransferBorrow
| ResourceTransferBorrowToOwner { .. }
| PrepareCall { .. }
| StartCall { .. }
| FutureTransfer
| StreamTransfer
| ErrorContextTransfer
| Trap(_)
| HostcallFuel
| EnterSyncCall
| ExitSyncCall => {
unreachable!("these trampolines do not exist yet")
}
}
}
/// Visit every `CoreDef` in `dfg` together with the component instance that
/// references it.
fn for_each_core_def(
dfg: &ComponentDfg,
mut f: impl FnMut(RuntimeComponentInstanceIndex, &CoreDef),
) {
for effect in dfg.side_effects.iter() {
let SideEffect::Instance(id, instance) = effect else {
continue;
};
match &dfg.instances[*id] {
Instance::Static(_, args) => {
for def in args.iter() {
f(*instance, def);
}
}
Instance::Import(_, args) => {
for (_, defs) in args {
for (_, def) in defs {
f(*instance, def);
}
}
}
}
}
for (_, adapter) in dfg.adapters.iter() {
f(adapter.lift_options.instance, &adapter.func);
for options in [&adapter.lift_options, &adapter.lower_options] {
for def in options
.callback
.iter()
.chain(options.post_return.iter())
.chain(match &options.data_model {
DataModel::LinearMemory { realloc, .. } => realloc.iter(),
DataModel::Gc {} => None.iter(),
})
{
f(options.instance, def);
}
}
}
for (_, options) in dfg.options.iter() {
if let Some(callback) = options.callback {
f(options.instance, &dfg.callbacks[callback]);
}
if let Some(post_return) = options.post_return {
f(options.instance, &dfg.post_returns[post_return]);
}
if let CanonicalOptionsDataModel::LinearMemory {
realloc: Some(realloc),
..
} = &options.data_model
{
f(options.instance, &dfg.reallocs[*realloc]);
}
}
for (_, resource) in dfg.resources.iter() {
if let Some(dtor) = &resource.dtor {
f(resource.instance, dtor);
}
}
for (_, (export, _)) in dfg.exports.iter() {
for_each_export_core_def(dfg, export, &mut f);
}
}
fn for_each_export_core_def(
dfg: &ComponentDfg,
export: &Export,
f: &mut impl FnMut(RuntimeComponentInstanceIndex, &CoreDef),
) {
match export {
Export::LiftedFunction { func, options, .. } => {
f(dfg.options[*options].instance, func);
}
Export::Instance { exports, .. } => {
for (_, (export, _)) in exports.iter() {
for_each_export_core_def(dfg, export, f);
}
}
Export::ModuleStatic { .. } | Export::ModuleImport { .. } | Export::Type(_) => {}
}
}
#[cfg(test)]
mod tests {
use super::*;
fn instance(i: u32) -> RuntimeComponentInstanceIndex {
RuntimeComponentInstanceIndex::from_u32(i)
}
/// Run the build phase over `observations`, given as `(instance, callable)`
/// pairs, and finish it into queryable results.
fn analyze(observations: &[(u32, CoreCallable)]) -> ThreadTransparency {
let mut builder = ThreadTransparencyBuilder::default();
for (i, callable) in observations {
builder.observe(instance(*i), *callable);
}
builder.finish()
}
/// An adapter calling into instance `callee` with a plain, handle-free,
/// sync signature.
fn facts(callee: u32) -> AdapterFacts {
AdapterFacts {
callee: instance(callee),
any_async: false,
any_handle: false,
}
}
#[test]
fn clean_instance_is_transparent() {
let t = analyze(&[]);
assert!(t.adapter_is_transparent(facts(0)));
}
#[test]
fn context_access_makes_instance_opaque() {
let t = analyze(&[(0, CoreCallable::ContextAccess)]);
assert!(!t.adapter_is_transparent(facts(0)));
}
#[test]
fn thread_state_builtin_makes_instance_opaque() {
let t = analyze(&[(0, CoreCallable::ThreadStateBuiltin)]);
assert!(!t.adapter_is_transparent(facts(0)));
}
#[test]
fn host_import_lowering_makes_instance_opaque() {
let t = analyze(&[(0, CoreCallable::HostImport)]);
assert!(!t.adapter_is_transparent(facts(0)));
}
#[test]
fn inert_callable_leaves_instance_transparent() {
let t = analyze(&[(0, CoreCallable::Inert), (0, CoreCallable::Inert)]);
assert!(t.adapter_is_transparent(facts(0)));
}
/// Lowering a sync-lifted guest function is just another adapter, and that
/// adapter does its own save/restore, so it does not taint the instance
/// doing the lowering.
#[test]
fn sync_adapter_lowering_leaves_instance_transparent() {
let t = analyze(&[(0, CoreCallable::Adapter { async_lift: false })]);
assert!(t.adapter_is_transparent(facts(0)));
}
/// Lowering an async-lifted guest function does taint the lowering
/// instance: the callee may block, and then the scheduler needs to find
/// this instance's sync call in progress.
#[test]
fn async_lift_makes_the_lowering_instance_opaque() {
let t = analyze(&[(0, CoreCallable::Adapter { async_lift: true })]);
assert!(!t.adapter_is_transparent(facts(0)));
}
/// Only the callee side is judged: an opaque caller calling into a clean
/// callee still gets a transparent adapter.
#[test]
fn only_the_callee_side_is_judged() {
let t = analyze(&[(0, CoreCallable::ContextAccess)]);
assert!(t.adapter_is_transparent(facts(1)));
}
/// Opacity does not propagate outward: in a chain `outer -> mid -> inner`
/// where only `inner` is opaque, the `outer -> mid` adapter is still
/// transparent because the `mid -> inner` call has its own adapter.
#[test]
fn opacity_does_not_propagate_outward() {
let t = analyze(&[(2, CoreCallable::ContextAccess)]);
assert!(t.adapter_is_transparent(facts(1)), "outer -> mid");
assert!(!t.adapter_is_transparent(facts(2)), "mid -> inner");
}
/// Nor inward: an opaque `outer` calling a clean `mid` calling a clean
/// `inner` leaves both adapters transparent.
#[test]
fn opacity_does_not_propagate_inward() {
let t = analyze(&[(0, CoreCallable::ContextAccess)]);
assert!(t.adapter_is_transparent(facts(1)), "outer -> mid");
assert!(t.adapter_is_transparent(facts(2)), "mid -> inner");
}
/// An unrelated sibling instance being opaque taints nobody else.
#[test]
fn siblings_are_judged_independently() {
let t = analyze(&[(0, CoreCallable::ContextAccess)]);
assert!(!t.adapter_is_transparent(facts(0)));
assert!(t.adapter_is_transparent(facts(1)));
}
#[test]
fn async_signature_is_never_transparent() {
let t = analyze(&[]);
assert!(!t.adapter_is_transparent(AdapterFacts {
any_async: true,
..facts(0)
}));
}
#[test]
fn handle_in_signature_is_never_transparent() {
let t = analyze(&[]);
assert!(!t.adapter_is_transparent(AdapterFacts {
any_handle: true,
..facts(0)
}));
}
/// The build phase is monotone, so observations may arrive in any order and
/// a clean observation can never undo an opaque one.
#[test]
fn observations_are_monotone_and_order_independent() {
let dirty_first = analyze(&[
(0, CoreCallable::ContextAccess),
(0, CoreCallable::Inert),
(0, CoreCallable::Adapter { async_lift: false }),
]);
let dirty_last = analyze(&[
(0, CoreCallable::Adapter { async_lift: false }),
(0, CoreCallable::Inert),
(0, CoreCallable::ContextAccess),
]);
assert!(!dirty_first.adapter_is_transparent(facts(0)));
assert!(!dirty_last.adapter_is_transparent(facts(0)));
}
}