feat: implement basic async

add ability for host functions to suspend vm and yield values to host,
and then to resume, potentially receiving value from host

Author: WhaleKit

crates/tinywasm/src/coro.rs

@@ -0,0 +1,151 @@
+use core::fmt::Debug;
+
+use crate::Result;
+// use alloc::boxed::Box;
+pub(crate) use tinywasm_types::{ResumeArgument, YieldedValue};
+
+#[derive(Debug)]
+pub enum SuspendReason {
+    /// host function yielded
+    /// potentially some host functions might expect resume argument when calling resume
+    Yield(YieldedValue),
+    // /// timer ran out (not implemented),
+    // /// host shouldn't provide resume argument when calling resume
+    // SuspendedEpoch,
+
+    // /// async should_suspend flag was set (not implemented)
+    // /// host shouldn't provide resume argument when calling resume
+    // SuspendedFlag,
+}
+
+/// result of a function that might pause in the middle and yield
+/// to be resumed later
+#[derive(Debug)]
+pub enum PotentialCoroCallResult<R, State>
+//where for<Ctx>
+//    State: CoroState<R, Ctx>, // can't in stable rust
+{
+    /// function returns normally
+    Return(R),
+    /// interpreter will be suspended and execution will return to host along with SuspendReason
+    Suspended(SuspendReason, State),
+}
+
+/// result of resuming coroutine state. Unlike [`PotentialCoroCallResult`]
+/// doesn't need to have state, since it's contained in self
+#[derive(Debug)]
+pub enum CoroStateResumeResult<R> {
+    /// after this CoroState::resume can't be called again on that CoroState
+    Return(R),
+
+    /// host function yielded
+    /// execution returns to host along with yielded value
+    Suspended(SuspendReason),
+}
+
+impl<R, State> PotentialCoroCallResult<R, State> {
+    /// true if coro is finished
+    pub fn finished(&self) -> bool {
+        if let Self::Return(_) = self {
+            true
+        } else {
+            false
+        }
+    }
+    /// separates state from PotentialCoroCallResult, leaving CoroStateResumeResult (one without state)
+    pub fn split_state(self) -> (CoroStateResumeResult<R>, Option<State>) {
+        match self {
+            Self::Return(val) => (CoroStateResumeResult::Return(val), None),
+            Self::Suspended(suspend, state) => (CoroStateResumeResult::Suspended(suspend), Some(state)),
+        }
+    }
+    /// separates result from PotentialCoroCallResult, leaving unit type in it's place
+    pub fn split_result(self) -> (PotentialCoroCallResult<(), State>, Option<R>) {
+        match self {
+            Self::Return(result) => (PotentialCoroCallResult::Return(()), Some(result)),
+            Self::Suspended(suspend, state) => (PotentialCoroCallResult::Suspended(suspend, state), None),
+        }
+    }
+
+    /// transforms state
+    pub fn map_state<OutS>(self, mapper: impl FnOnce(State) -> OutS) -> PotentialCoroCallResult<R, OutS> {
+        match self {
+            Self::Return(val) => PotentialCoroCallResult::Return(val),
+            Self::Suspended(suspend, state) => PotentialCoroCallResult::Suspended(suspend, mapper(state)),
+        }
+    }
+    /// transform result with mapper if there is none - calls "otherwise" arg. user_val
+    pub fn map_result_or_else<OutR, Usr>(
+        self,
+        user_val: Usr,
+        mapper: impl FnOnce(R, Usr) -> OutR,
+        otherwise: impl FnOnce(Usr) -> (),
+    ) -> PotentialCoroCallResult<OutR, State> {
+        match self {
+            Self::Return(res) => PotentialCoroCallResult::Return(mapper(res, user_val)),
+            Self::Suspended(suspend, state) => {
+                otherwise(user_val);
+                PotentialCoroCallResult::Suspended(suspend, state)
+            }
+        }
+    }
+    /// transforms result
+    pub fn map_result<OutR>(self, mapper: impl FnOnce(R) -> OutR) -> PotentialCoroCallResult<OutR, State> {
+        self.map_result_or_else((), |val, _| mapper(val), |_| {})
+    }
+}
+
+impl<R> CoroStateResumeResult<R> {
+    /// true if coro is finished
+    pub fn finished(&self) -> bool {
+        if let Self::Return(_) = self {
+            true
+        } else {
+            false
+        }
+    }
+    /// separates result from CoroStateResumeResult, leaving unit type in it's place
+    pub fn split_result(self) -> (CoroStateResumeResult<()>, Option<R>) {
+        let (a, r) = PotentialCoroCallResult::<R, ()>::from(self).split_result();
+        (a.into(), r)
+    }
+    /// transforms result
+    pub fn map_result<OutR>(self, mapper: impl FnOnce(R) -> OutR) -> CoroStateResumeResult<OutR> {
+        PotentialCoroCallResult::<R, ()>::from(self).map_result(mapper).into()
+    }
+    /// transform result with mapper if there is none - calls "otherwise" arg. user_val called
+    pub fn map_result_or_else<OutR, Usr>(
+        self,
+        user_val: Usr,
+        mapper: impl FnOnce(R, Usr) -> OutR,
+        otherwise: impl FnOnce(Usr) -> (),
+    ) -> CoroStateResumeResult<OutR> {
+        PotentialCoroCallResult::<R, ()>::from(self).map_result_or_else(user_val, mapper, otherwise).into()
+    }
+}
+
+impl<DstR, SrcR> From<PotentialCoroCallResult<SrcR, ()>> for CoroStateResumeResult<DstR>
+where
+    DstR: From<SrcR>,
+{
+    fn from(value: PotentialCoroCallResult<SrcR, ()>) -> Self {
+        match value {
+            PotentialCoroCallResult::Return(val) => Self::Return(val.into()),
+            PotentialCoroCallResult::Suspended(suspend, ()) => Self::Suspended(suspend),
+        }
+    }
+}
+impl<SrcR> From<CoroStateResumeResult<SrcR>> for PotentialCoroCallResult<SrcR, ()> {
+    fn from(value: CoroStateResumeResult<SrcR>) -> Self {
+        match value {
+            CoroStateResumeResult::Return(val) => PotentialCoroCallResult::Return(val),
+            CoroStateResumeResult::Suspended(suspend) => PotentialCoroCallResult::Suspended(suspend, ()),
+        }
+    }
+}
+
+///"coroutine statse", "coroutine instance", "resumable". Stores info to continue a function that was paused
+pub trait CoroState<Ret, ResumeContext>: Debug {
+    /// resumes the execution of the coroutine
+    fn resume(&mut self, ctx: ResumeContext, arg: ResumeArgument) -> Result<CoroStateResumeResult<Ret>>;
+}

crates/tinywasm/src/error.rs

@@ -5,6 +5,8 @@ use tinywasm_types::FuncType;
 #[cfg(feature = "parser")]
 pub use tinywasm_parser::ParseError;
 
+use crate::{coro::SuspendReason, interpreter};
+
 /// Errors that can occur for `TinyWasm` operations
 #[derive(Debug)]
 pub enum Error {
@@ -23,12 +25,25 @@ pub enum Error {
     /// A function did not return a value
     FuncDidNotReturn,
 
+    /// A host function returned results that don't match it's signature
+    HostFuncInvalidReturn,
+
     /// An invalid label type was encountered
     InvalidLabelType,
 
     /// The store is not the one that the module instance was instantiated in
     InvalidStore,
 
+    /// ResumeArgument of wrong type was provided
+    InvalidResumeArgument,
+
+    /// Tried to resume on runtime when it's not suspended
+    InvalidResume,
+
+    /// Function unexpectedly yielded instead of returning
+    /// (for backwards compatibility with old api)
+    UnexpectedSuspend(SuspendReason),
+
     #[cfg(feature = "std")]
     /// An I/O error occurred
     Io(crate::std::io::Error),
@@ -184,7 +199,13 @@ impl Display for Error {
             Self::Other(message) => write!(f, "unknown error: {message}"),
             Self::UnsupportedFeature(feature) => write!(f, "unsupported feature: {feature}"),
             Self::FuncDidNotReturn => write!(f, "function did not return"),
+            Self::HostFuncInvalidReturn => write!(f, "host function returned invalid types"),
+
             Self::InvalidStore => write!(f, "invalid store"),
+
+            Self::UnexpectedSuspend(_) => write!(f, "funtion yielded instead of returning"),
+            Self::InvalidResumeArgument => write!(f, "invalid resume argument supplied to suspended function"),
+            Self::InvalidResume => write!(f, "attempt to resume coroutine that has already finished"),
         }
     }
 }
@@ -238,14 +259,14 @@ impl From<tinywasm_parser::ParseError> for Error {
 pub type Result<T, E = Error> = crate::std::result::Result<T, E>;
 
 pub(crate) trait Controlify<T> {
-    fn to_cf(self) -> ControlFlow<Option<Error>, T>;
+    fn to_cf(self) -> ControlFlow<interpreter::executor::ReasonToBreak, T>;
 }
 
 impl<T> Controlify<T> for Result<T, Error> {
-    fn to_cf(self) -> ControlFlow<Option<Error>, T> {
+    fn to_cf(self) -> ControlFlow<interpreter::executor::ReasonToBreak, T> {
         match self {
             Ok(value) => ControlFlow::Continue(value),
-            Err(err) => ControlFlow::Break(Some(err)),
+            Err(err) => ControlFlow::Break(interpreter::executor::ReasonToBreak::Errored(err)),
         }
     }
 }

crates/tinywasm/src/func.rs

@@ -1,8 +1,11 @@
+use crate::coro::CoroState;
+use crate::interpreter;
+use crate::interpreter::executor::SuspendedHostCoroState;
 use crate::interpreter::stack::{CallFrame, Stack};
 use crate::{log, unlikely, Function};
 use crate::{Error, FuncContext, Result, Store};
 use alloc::{boxed::Box, format, string::String, string::ToString, vec, vec::Vec};
-use tinywasm_types::{FuncType, ModuleInstanceAddr, ValType, WasmValue};
+use tinywasm_types::{FuncType, ModuleInstanceAddr, ResumeArgument, ValType, WasmValue};
 
 #[derive(Debug)]
 /// A function handle
@@ -15,12 +18,60 @@ pub struct FuncHandle {
     pub name: Option<String>,
 }
 
+pub(crate) type FuncHandleResumeOutcome = crate::coro::CoroStateResumeResult<Vec<WasmValue>>;
+
+#[derive(Debug)]
+struct SuspendedWasmFunc {
+    runtime: interpreter::SuspendedRuntime,
+    result_types: Box<[ValType]>,
+}
+impl SuspendedWasmFunc {
+    fn resume(&mut self, ctx: FuncContext<'_>, arg: ResumeArgument) -> Result<FuncHandleResumeOutcome> {
+        Ok(self.runtime.resume(ctx, arg)?.map_result(|mut stack| stack.values.pop_results(&self.result_types)))
+    }
+}
+
+#[derive(Debug)]
+pub(self) enum SuspendFuncInner {
+    Wasm(SuspendedWasmFunc),
+    Host(SuspendedHostCoroState),
+}
+
+#[derive(Debug)]
+pub struct SuspendFunc {
+    pub(self) func: SuspendFuncInner,
+    pub(crate) module_addr: ModuleInstanceAddr,
+}
+
+impl<'a> crate::coro::CoroState<Vec<WasmValue>, &mut Store> for SuspendFunc {
+    fn resume(&mut self, store: &mut Store, arg: ResumeArgument) -> Result<FuncHandleResumeOutcome> {
+        let ctx = FuncContext { store, module_addr: self.module_addr };
+        match &mut self.func {
+            SuspendFuncInner::Wasm(wasm) => wasm.resume(ctx, arg),
+            SuspendFuncInner::Host(host) => Ok(host.coro_state.resume(ctx, arg)?),
+        }
+    }
+}
+
+type FuncHandleCallOutcome = crate::coro::PotentialCoroCallResult<Vec<WasmValue>, SuspendFunc>;
+
 impl FuncHandle {
     /// Call a function (Invocation)
     ///
     /// See <https://webassembly.github.io/spec/core/exec/modules.html#invocation>
+    ///
+
     #[inline]
     pub fn call(&self, store: &mut Store, params: &[WasmValue]) -> Result<Vec<WasmValue>> {
+        match self.call_coro(store, params)? {
+            crate::coro::PotentialCoroCallResult::Return(res) => Ok(res),
+            crate::coro::PotentialCoroCallResult::Suspended(suspend, _state) => Err(Error::UnexpectedSuspend(suspend)),
+        }
+    }
+
+    /// Call a function (Invocation) and anticipate possible yield instead as well as return
+    #[inline]
+    pub fn call_coro(&self, store: &mut Store, params: &[WasmValue]) -> Result<FuncHandleCallOutcome> {
         // Comments are ordered by the steps in the spec
         // In this implementation, some steps are combined and ordered differently for performance reasons
 
@@ -53,7 +104,13 @@ impl FuncHandle {
             Function::Host(host_func) => {
                 let func = &host_func.clone().func;
                 let ctx = FuncContext { store, module_addr: self.module_addr };
-                return (func)(ctx, params);
+                return Ok((func)(ctx, params)?.map_state(|state| SuspendFunc {
+                    func: SuspendFuncInner::Host(SuspendedHostCoroState {
+                        coro_state: state,
+                        coro_orig_function: self.addr,
+                    }),
+                    module_addr: self.module_addr,
+                }));
             }
             Function::Wasm(wasm_func) => wasm_func,
         };
@@ -63,23 +120,33 @@ impl FuncHandle {
 
         // 7. Push the frame f to the call stack
         // & 8. Push the values to the stack (Not needed since the call frame owns the values)
-        let mut stack = Stack::new(call_frame);
+        let stack = Stack::new(call_frame);
 
         // 9. Invoke the function instance
         let runtime = store.runtime();
-        runtime.exec(store, &mut stack)?;
-
-        // Once the function returns:
-        // let result_m = func_ty.results.len();
-
-        // 1. Assert: m values are on the top of the stack (Ensured by validation)
-        // assert!(stack.values.len() >= result_m);
-
-        // 2. Pop m values from the stack
-        let res = stack.values.pop_results(&func_ty.results);
-
-        // The values are returned as the results of the invocation.
-        Ok(res)
+        let exec_outcome = runtime.exec(store, stack)?;
+        Ok(exec_outcome
+            .map_result(|mut stack| {
+                // Once the function returns:
+                // let result_m = func_ty.results.len();
+
+                // 1. Assert: m values are on the top of the stack (Ensured by validation)
+                // assert!(stack.values.len() >= result_m);
+
+                // 2. Pop m values from the stack
+                let res = stack.values.pop_results(&func_ty.results);
+                // The values are returned as the results of the invocation.
+                return res;
+            })
+            .map_state(|coro_state| -> SuspendFunc {
+                SuspendFunc {
+                    func: SuspendFuncInner::Wasm(SuspendedWasmFunc {
+                        runtime: coro_state,
+                        result_types: func_ty.results.clone(),
+                    }),
+                    module_addr: self.module_addr,
+                }
+            }))
     }
 }