[stack-switching] Support the resume_throw_ref instruction (#2423)

This patch adds support for the `resume_throw_ref` instruction, which
is similar to the `resume_throw` instruction, but rather than
injecting a fresh exception into the continuation, the
`resume_throw_ref` instruction injects an exception reference into the
continuation.

Note: the new instruction is, at the time of writing, assigned the
opcode `0xE5` conflicting with the `switch` instruction, which has
been assigned `0xE6` as its opcode instead (c.f. [the work-in-progress
specification](https://github.com/WebAssembly/stack-switching/blob/main/proposals/stack-switching/Explainer.md#binary-format)).

Author: dhil

crates/wasm-encoder/src/core/code.rs

@@ -1308,6 +1308,10 @@ pub enum Instruction<'a> {
         tag_index: u32,
         resume_table: Cow<'a, [Handle]>,
     },
+    ResumeThrowRef {
+        cont_type_index: u32,
+        resume_table: Cow<'a, [Handle]>,
+    },
     Switch {
         cont_type_index: u32,
         tag_index: u32,
@@ -2156,6 +2160,10 @@ impl Encode for Instruction<'_> {
                 tag_index,
                 ref resume_table,
             } => sink.resume_throw(cont_type_index, tag_index, resume_table.iter().cloned()),
+            Instruction::ResumeThrowRef {
+                cont_type_index,
+                ref resume_table,
+            } => sink.resume_throw_ref(cont_type_index, resume_table.iter().cloned()),
             Instruction::Switch {
                 cont_type_index,
                 tag_index,

crates/wasm-encoder/src/core/instructions.rs

@@ -4588,9 +4588,24 @@ impl<'a> InstructionSink<'a> {
         self
     }
 
+    /// Encode [`Instruction::ResumeThrowRef`].
+    pub fn resume_throw_ref<V: IntoIterator<Item = Handle>>(
+        &mut self,
+        cont_type_index: u32,
+        resume_table: V,
+    ) -> &mut Self
+    where
+        V::IntoIter: ExactSizeIterator,
+    {
+        self.sink.push(0xE5);
+        cont_type_index.encode(self.sink);
+        encode_vec(resume_table, self.sink);
+        self
+    }
+
     /// Encode [`Instruction::Switch`].
     pub fn switch(&mut self, cont_type_index: u32, tag_index: u32) -> &mut Self {
-        self.sink.push(0xE5);
+        self.sink.push(0xE6);
         cont_type_index.encode(self.sink);
         tag_index.encode(self.sink);
         self

crates/wasmparser/src/arity.rs

@@ -285,6 +285,16 @@ fn visit_resume_throw(
     Some((params + 1, results))
 }
 
+fn visit_resume_throw_ref(
+    module: &dyn ModuleArity,
+    cont: u32,
+    _table: ResumeTable,
+) -> Option<(u32, u32)> {
+    let (_, results) = module.sub_type_arity(module.sub_type_at(cont)?)?;
+    // in: [exnref, cont], out: [result(cont)]
+    Some((2, results))
+}
+
 fn visit_switch(module: &dyn ModuleArity, cont: u32, _tag: u32) -> Option<(u32, u32)> {
     let (params, _) = module.sub_type_arity(module.sub_type_at(cont)?)?;
     let st = &module.sub_type_at(cont)?.composite_type.inner;

crates/wasmparser/src/binary_reader.rs

@@ -1187,7 +1187,8 @@ impl<'a> BinaryReader<'a> {
             0xe4 => {
                 visitor.visit_resume_throw(self.read_var_u32()?, self.read_var_u32()?, self.read()?)
             }
-            0xe5 => visitor.visit_switch(self.read_var_u32()?, self.read_var_u32()?),
+            0xe5 => visitor.visit_resume_throw_ref(self.read_var_u32()?, self.read()?),
+            0xe6 => visitor.visit_switch(self.read_var_u32()?, self.read_var_u32()?),
 
             0xfb => self.visit_0xfb_operator(pos, visitor)?,
             0xfc => self.visit_0xfc_operator(pos, visitor)?,

crates/wasmparser/src/lib.rs

@@ -788,6 +788,7 @@ macro_rules! _for_each_operator_group {
                 Suspend { tag_index: u32 } => visit_suspend (arity custom)
                 Resume { cont_type_index: u32, resume_table: $crate::ResumeTable } => visit_resume (arity custom)
                 ResumeThrow { cont_type_index: u32, tag_index: u32, resume_table: $crate::ResumeTable } => visit_resume_throw (arity custom)
+                ResumeThrowRef { cont_type_index: u32, resume_table: $crate::ResumeTable } => visit_resume_throw_ref (arity custom)
                 Switch { cont_type_index: u32, tag_index: u32 } => visit_switch (arity custom)
             }
 

crates/wasmparser/src/validator/operators.rs

@@ -4368,6 +4368,16 @@ where
         }
         Ok(())
     }
+    fn visit_resume_throw_ref(&mut self, type_index: u32, table: ResumeTable) -> Self::Output {
+        let ft = self.check_resume_table(table, type_index)?;
+        self.pop_concrete_ref(true, type_index)?;
+        self.pop_operand(Some(ValType::EXNREF))?;
+
+        for &ty in ft.results() {
+            self.push_operand(ty)?
+        }
+        Ok(())
+    }
     fn visit_switch(&mut self, type_index: u32, tag_index: u32) -> Self::Output {
         // [t1* (ref null $ct2)] -> [te1*]
         let cont_ty = self.cont_type_at(type_index)?;

crates/wasmprinter/src/operator.rs

@@ -1402,6 +1402,7 @@ macro_rules! define_visit {
     (name Suspend) => ("suspend");
     (name Resume) => ("resume");
     (name ResumeThrow) => ("resume_throw");
+    (name ResumeThrowRef) => ("resume_throw_ref");
     (name Switch) => ("switch");
     (name I64Add128) => ("i64.add128");
     (name I64Sub128) => ("i64.sub128");

crates/wast/src/core/binary.rs

@@ -1334,6 +1334,13 @@ impl<'a> Encode for ResumeThrow<'a> {
     }
 }
 
+impl<'a> Encode for ResumeThrowRef<'a> {
+    fn encode(&self, dst: &mut Vec<u8>) {
+        self.type_index.encode(dst);
+        self.table.encode(dst);
+    }
+}
+
 impl<'a> Encode for ResumeTable<'a> {
     fn encode(&self, dst: &mut Vec<u8>) {
         self.handlers.encode(dst);

crates/wast/src/core/expr.rs

@@ -1195,7 +1195,8 @@ instructions! {
         Suspend(Index<'a>)             : [0xe2] : "suspend",
         Resume(Resume<'a>)             : [0xe3] : "resume",
         ResumeThrow(ResumeThrow<'a>)   : [0xe4] : "resume_throw",
-        Switch(Switch<'a>)             : [0xe5] : "switch",
+        ResumeThrowRef(ResumeThrowRef<'a>) : [0xe5] : "resume_throw_ref",
+        Switch(Switch<'a>)             : [0xe6] : "switch",
 
         // Wide arithmetic proposal
         I64Add128   : [0xfc, 19] : "i64.add128",
@@ -1313,6 +1314,23 @@ impl<'a> Parse<'a> for ResumeThrow<'a> {
     }
 }
 
+/// Extra information associated with the resume_throw_ref instruction
+#[derive(Debug, Clone)]
+#[allow(missing_docs)]
+pub struct ResumeThrowRef<'a> {
+    pub type_index: Index<'a>,
+    pub table: ResumeTable<'a>,
+}
+
+impl<'a> Parse<'a> for ResumeThrowRef<'a> {
+    fn parse(parser: Parser<'a>) -> Result<Self> {
+        Ok(ResumeThrowRef {
+            type_index: parser.parse()?,
+            table: parser.parse()?,
+        })
+    }
+}
+
 /// Extra information associated with the switch instruction
 #[derive(Debug, Clone)]
 #[allow(missing_docs)]

crates/wast/src/core/resolve/names.rs

@@ -677,6 +677,10 @@ impl<'a, 'b> ExprResolver<'a, 'b> {
                 self.resolver.resolve(&mut rt.tag_index, Ns::Tag)?;
                 self.resolve_resume_table(&mut rt.table)?;
             }
+            ResumeThrowRef(rt) => {
+                self.resolver.resolve(&mut rt.type_index, Ns::Type)?;
+                self.resolve_resume_table(&mut rt.table)?;
+            }
             Switch(s) => {
                 self.resolver.resolve(&mut s.type_index, Ns::Type)?;
                 self.resolver.resolve(&mut s.tag_index, Ns::Tag)?;