A lightweight WebAssembly runtime that is fast, secure, and standards-compliant
//! Exception tables: catch handlers on `try_call` instructions.
//!
//! An exception table describes where execution flows after returning
//! from `try_call`. It contains both the "normal" destination -- the
//! block to branch to when the function returns without throwing an
//! exception -- and any "catch" destinations associated with
//! particular exception tags. Each target indicates the arguments to
//! pass to the block that receives control.
//!
//! Like other side-tables (e.g., jump tables), each exception table
//! must be used by only one instruction. Sharing is not permitted
//! because it can complicate transforms (how does one change the
//! table used by only one instruction if others also use it?).
//!
//! In order to allow the `try_call` instruction itself to remain
//! small, the exception table also contains the signature ID of the
//! called function.
use crate::ir::entities::{ExceptionTag, SigRef};
use crate::ir::instructions::ValueListPool;
use crate::ir::{BlockCall, Value};
use alloc::vec::Vec;
use core::fmt::{self, Display, Formatter};
#[cfg(feature = "enable-serde")]
use serde_derive::{Deserialize, Serialize};
/// Contents of an exception table.
///
/// An exception table consists of a "no exception" ("normal")
/// destination block-call, and a series of exceptional destination
/// block-calls associated with tags.
///
/// The exceptional tags can also be interspersed with "dynamic
/// context" entries, which result in a particular value being stored
/// in the stack frame and accessible at an offset given in the
/// compiled exception-table metadata. This is needed for some kinds
/// of tag-matching where different dynamic instances of tags may
/// exist (e.g., in the WebAssembly exception-handling proposal).
///
/// The sequence of targets is semantically a list of
/// context-or-tagged-blockcall; e.g., `[context v0, tag1: block1(v1,
/// v2), context v2, tag2: block2(), tag3: block3()]`.
///
/// The "no exception" target can be accessed through the
/// `normal_return` and `normal_return_mut` functions. Exceptional
/// catch clauses may be iterated using the `catches` and
/// `catches_mut` functions. All targets may be iterated over using
/// the `all_targets` and `all_targets_mut` functions.
#[derive(Debug, Clone, PartialEq, Hash)]
#[cfg_attr(feature = "enable-serde", derive(Serialize, Deserialize))]
pub struct ExceptionTableData {
/// All BlockCalls packed together. This is necessary because the
/// rest of the compiler expects to be able to grab a slice of
/// branch targets for any branch instruction. The last BlockCall
/// is the normal-return destination, and the rest are referred to
/// by index by the `items` below.
targets: Vec<BlockCall>,
/// Exception-table items.
///
/// This internal representation for items is like
/// `ExceptionTableItem` except that it has indices that refer to
/// `targets` above.
///
/// A tag value of `None` indicates a catch-all handler. The
/// catch-all handler matches only if no other handler matches,
/// regardless of the order in this vector.
///
/// `tags[i]` corresponds to `targets[i]`. Note that there will be
/// one more `targets` element than `tags` because the last
/// element in `targets` is the normal-return path.
items: Vec<InternalExceptionTableItem>,
/// The signature of the function whose invocation is associated
/// with this handler table.
sig: SigRef,
}
/// A single item in the match-list of an exception table.
#[derive(Clone, Debug)]
pub enum ExceptionTableItem {
/// A tag match, taking the specified block-call destination if
/// the tag matches the one in the thrown exception. (The match
/// predicate is up to the runtime; Cranelift only emits metadata
/// containing this tag.)
Tag(ExceptionTag, BlockCall),
/// A default match, always taking the specified block-call
/// destination.
Default(BlockCall),
/// A dynamic context update, applying to all tags until the next
/// update. (Cranelift does not interpret this context, but only
/// provides information to the runtime regarding where to find
/// it.)
Context(Value),
}
/// Our internal representation of exception-table items.
///
/// This is a version of `ExceptionTableItem` with block-calls
/// out-of-lined so that we can provide the slice externally. Each
/// block-call is referenced via an index.
#[derive(Clone, Debug, PartialEq, Hash)]
#[cfg_attr(feature = "enable-serde", derive(Serialize, Deserialize))]
enum InternalExceptionTableItem {
Tag(ExceptionTag, u32),
Default(u32),
Context(Value),
}
impl ExceptionTableData {
/// Create new exception-table data.
///
/// This data represents the destinations upon return from
/// `try_call` or `try_call_indirect` instruction. There are two
/// possibilities: "normal return" (no exception thrown), or an
/// exceptional return corresponding to one of the listed
/// exception tags.
///
/// The given tags are passed through to the metadata provided
/// alongside the provided function body, and Cranelift itself
/// does not implement an unwinder; thus, the meaning of the tags
/// is ultimately up to the embedder of Cranelift. The tags are
/// wrapped in `Option` to allow encoding a "catch-all" handler.
///
/// The BlockCalls must have signatures that match the targeted
/// blocks, as usual. These calls are allowed to use
/// `BlockArg::TryCallRet` in the normal-return case, with types
/// corresponding to the signature's return values, and
/// `BlockArg::TryCallExn` in the exceptional-return cases, with
/// types corresponding to native machine words and an arity
/// corresponding to the number of payload values that the calling
/// convention and platform support. (See [`CallConv`](crate::isa::CallConv) for
/// more details.)
pub fn new(
sig: SigRef,
normal_return: BlockCall,
matches: impl IntoIterator<Item = ExceptionTableItem>,
) -> Self {
let mut targets = vec![];
let mut items = vec![];
for item in matches {
let target_idx = u32::try_from(targets.len()).unwrap();
match item {
ExceptionTableItem::Tag(tag, target) => {
items.push(InternalExceptionTableItem::Tag(tag, target_idx));
targets.push(target);
}
ExceptionTableItem::Default(target) => {
items.push(InternalExceptionTableItem::Default(target_idx));
targets.push(target);
}
ExceptionTableItem::Context(ctx) => {
items.push(InternalExceptionTableItem::Context(ctx));
}
}
}
targets.push(normal_return);
ExceptionTableData {
targets,
items,
sig,
}
}
/// Return a value that can display the contents of this exception
/// table.
pub fn display<'a>(&'a self, pool: &'a ValueListPool) -> DisplayExceptionTable<'a> {
DisplayExceptionTable { table: self, pool }
}
/// Deep-clone this exception table.
pub fn deep_clone(&self, pool: &mut ValueListPool) -> Self {
Self {
targets: self.targets.iter().map(|b| b.deep_clone(pool)).collect(),
items: self.items.clone(),
sig: self.sig,
}
}
/// Get the default target for the non-exceptional return case.
pub fn normal_return(&self) -> &BlockCall {
self.targets.last().unwrap()
}
/// Get the default target for the non-exceptional return case.
pub fn normal_return_mut(&mut self) -> &mut BlockCall {
self.targets.last_mut().unwrap()
}
/// Get the exception-catch items: dynamic context updates for
/// interpreting tags, tag-associated targets, and catch-all
/// targets.
pub fn items(&self) -> impl Iterator<Item = ExceptionTableItem> + '_ {
self.items.iter().map(|item| match item {
InternalExceptionTableItem::Tag(tag, target_idx) => {
ExceptionTableItem::Tag(*tag, self.targets[usize::try_from(*target_idx).unwrap()])
}
InternalExceptionTableItem::Default(target_idx) => {
ExceptionTableItem::Default(self.targets[usize::try_from(*target_idx).unwrap()])
}
InternalExceptionTableItem::Context(ctx) => ExceptionTableItem::Context(*ctx),
})
}
/// Get all branch targets.
pub fn all_branches(&self) -> &[BlockCall] {
&self.targets[..]
}
/// Get all branch targets.
pub fn all_branches_mut(&mut self) -> &mut [BlockCall] {
&mut self.targets[..]
}
/// Get the signature of the function called with this exception
/// table.
pub fn signature(&self) -> SigRef {
self.sig
}
/// Get a mutable handle to this exception table's signature.
pub(crate) fn signature_mut(&mut self) -> &mut SigRef {
&mut self.sig
}
/// Get an iterator over context values.
pub(crate) fn contexts(&self) -> impl DoubleEndedIterator<Item = Value> {
self.items.iter().filter_map(|item| match item {
InternalExceptionTableItem::Context(ctx) => Some(*ctx),
_ => None,
})
}
/// Get a mutable iterator over context values.
pub(crate) fn contexts_mut(&mut self) -> impl DoubleEndedIterator<Item = &mut Value> {
self.items.iter_mut().filter_map(|item| match item {
InternalExceptionTableItem::Context(ctx) => Some(ctx),
_ => None,
})
}
/// Clears all entries in this exception table, but leaves the function signature.
pub fn clear(&mut self) {
self.items.clear();
self.targets.clear();
}
}
/// A wrapper for the context required to display a
/// [ExceptionTableData].
pub struct DisplayExceptionTable<'a> {
table: &'a ExceptionTableData,
pool: &'a ValueListPool,
}
impl<'a> Display for DisplayExceptionTable<'a> {
fn fmt(&self, fmt: &mut Formatter<'_>) -> fmt::Result {
write!(
fmt,
"{}, {}, [",
self.table.sig,
self.table.normal_return().display(self.pool)
)?;
let mut first = true;
for item in self.table.items() {
if first {
write!(fmt, " ")?;
first = false;
} else {
write!(fmt, ", ")?;
}
match item {
ExceptionTableItem::Tag(tag, block_call) => {
write!(fmt, "{}: {}", tag, block_call.display(self.pool))?;
}
ExceptionTableItem::Default(block_call) => {
write!(fmt, "default: {}", block_call.display(self.pool))?;
}
ExceptionTableItem::Context(ctx) => {
write!(fmt, "context {ctx}")?;
}
}
}
let space = if first { "" } else { " " };
write!(fmt, "{space}]")?;
Ok(())
}
}