minor: clippy, names, qol function

Author: WhaleKit

crates/tinywasm/src/coro.rs

@@ -4,6 +4,11 @@ use crate::Result;
 // use alloc::boxed::Box;
 pub(crate) use tinywasm_types::{ResumeArgument, YieldedValue};
 
+///"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>>;
+}
 
 /// explains why did execution suspend, and carries payload if needed
 #[derive(Debug)]
@@ -24,7 +29,6 @@ pub enum SuspendReason {
     /// async should_suspend flag was set
     /// host shouldn't provide resume argument when calling resume
     SuspendedFlag,
-
     // possible others: delimited continuations proposal, debugger breakpoint, out of fuel
 }
 
@@ -55,13 +59,19 @@ pub enum CoroStateResumeResult<R> {
 }
 
 impl<R, State> PotentialCoroCallResult<R, State> {
+
+    /// in case you expect function only to return
+    /// you can make Suspend into [crate::Error::UnexpectedSuspend] error
+    pub fn suspend_to_err(self) -> Result<R> {
+        match self {
+            PotentialCoroCallResult::Return(r) => Ok(r),
+            PotentialCoroCallResult::Suspended(r, _) => Err(crate::Error::UnexpectedSuspend(r)),
+        }
+    }
+
     /// true if coro is finished
     pub fn finished(&self) -> bool {
-        if let Self::Return(_) = self {
-            true
-        } else {
-            false
-        }
+        matches!(self, Self::Return(_))
     }
     /// separates state from PotentialCoroCallResult, leaving CoroStateResumeResult (one without state)
     pub fn split_state(self) -> (CoroStateResumeResult<R>, Option<State>) {
@@ -90,7 +100,7 @@ impl<R, State> PotentialCoroCallResult<R, State> {
         self,
         user_val: Usr,
         mapper: impl FnOnce(R, Usr) -> OutR,
-        otherwise: impl FnOnce(Usr) -> (),
+        otherwise: impl FnOnce(Usr),
     ) -> PotentialCoroCallResult<OutR, State> {
         match self {
             Self::Return(res) => PotentialCoroCallResult::Return(mapper(res, user_val)),
@@ -109,11 +119,7 @@ impl<R, State> PotentialCoroCallResult<R, State> {
 impl<R> CoroStateResumeResult<R> {
     /// true if coro is finished
     pub fn finished(&self) -> bool {
-        if let Self::Return(_) = self {
-            true
-        } else {
-            false
-        }
+        matches!(self, Self::Return(_))
     }
     /// separates result from CoroStateResumeResult, leaving unit type in it's place
     pub fn split_result(self) -> (CoroStateResumeResult<()>, Option<R>) {
@@ -129,7 +135,7 @@ impl<R> CoroStateResumeResult<R> {
         self,
         user_val: Usr,
         mapper: impl FnOnce(R, Usr) -> OutR,
-        otherwise: impl FnOnce(Usr) -> (),
+        otherwise: impl FnOnce(Usr),
     ) -> CoroStateResumeResult<OutR> {
         PotentialCoroCallResult::<R, ()>::from(self).map_result_or_else(user_val, mapper, otherwise).into()
     }
@@ -154,9 +160,3 @@ impl<SrcR> From<CoroStateResumeResult<SrcR>> for PotentialCoroCallResult<SrcR, (
         }
     }
 }
-
-///"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

@@ -30,7 +30,7 @@ pub enum Error {
         /// The actual value
         actual: Vec<tinywasm_types::WasmValue>,
     },
-    
+
     /// An invalid label type was encountered
     InvalidLabelType,
 

crates/tinywasm/src/func.rs

@@ -32,47 +32,44 @@ impl SuspendedWasmFunc {
 }
 
 #[derive(Debug)]
-pub(self) enum SuspendFuncInner {
+#[allow(clippy::large_enum_variant)] // Wasm is bigger, but also much more common variant
+enum SuspendedFuncInner {
     Wasm(SuspendedWasmFunc),
     Host(SuspendedHostCoroState),
 }
 
 /// handle to function that was suspended and can be resumed
 #[derive(Debug)]
-pub struct SuspendFunc {
-    func: SuspendFuncInner,
+pub struct SuspendedFunc {
+    func: SuspendedFuncInner,
     module_addr: ModuleInstanceAddr,
     store_id: usize,
 }
 
-impl<'a> crate::coro::CoroState<Vec<WasmValue>, &mut Store> for SuspendFunc {
+impl crate::coro::CoroState<Vec<WasmValue>, &mut Store> for SuspendedFunc {
     fn resume(&mut self, store: &mut Store, arg: ResumeArgument) -> Result<FuncHandleResumeOutcome> {
         if store.id() != self.store_id {
             return Err(Error::InvalidStore);
         }
 
         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)?),
+            SuspendedFuncInner::Wasm(wasm) => wasm.resume(ctx, arg),
+            SuspendedFuncInner::Host(host) => Ok(host.coro_state.resume(ctx, arg)?),
         }
     }
 }
 
-type FuncHandleCallOutcome = crate::coro::PotentialCoroCallResult<Vec<WasmValue>, SuspendFunc>;
+type FuncHandleCallOutcome = crate::coro::PotentialCoroCallResult<Vec<WasmValue>, SuspendedFunc>;
 
 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)),
-        }
+        self.call_coro(store, params)?.suspend_to_err()
     }
 
     /// Call a function (Invocation) and anticipate possible yield instead as well as return
@@ -110,8 +107,8 @@ impl FuncHandle {
             Function::Host(host_func) => {
                 let host_func = host_func.clone();
                 let ctx = FuncContext { store, module_addr: self.module_addr };
-                return Ok(host_func.call(ctx, params)?.map_state(|state| SuspendFunc {
-                    func: SuspendFuncInner::Host(SuspendedHostCoroState {
+                return Ok(host_func.call(ctx, params)?.map_state(|state| SuspendedFunc {
+                    func: SuspendedFuncInner::Host(SuspendedHostCoroState {
                         coro_state: state,
                         coro_orig_function: self.addr,
                     }),
@@ -133,21 +130,20 @@ impl FuncHandle {
         let runtime = store.runtime();
         let exec_outcome = runtime.exec(store, stack)?;
         Ok(exec_outcome
-            .map_result(|mut stack| {
+            .map_result(|mut stack|->Vec<WasmValue> {
                 // 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);
+                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 {
+            .map_state(|coro_state| -> SuspendedFunc {
+                SuspendedFunc {
+                    func: SuspendedFuncInner::Wasm(SuspendedWasmFunc {
                         runtime: coro_state,
                         result_types: func_ty.results.clone(),
                     }),

crates/tinywasm/src/instance.rs

@@ -2,7 +2,10 @@ use alloc::{boxed::Box, format, rc::Rc, string::ToString};
 use tinywasm_types::*;
 
 use crate::func::{FromWasmValueTuple, IntoWasmValueTuple};
-use crate::{Error, FuncHandle, FuncHandleTyped, Imports, MemoryRef, MemoryRefMut, Module, PotentialCoroCallResult, Result, Store, SuspendFunc};
+use crate::{
+    Error, FuncHandle, FuncHandleTyped, Imports, MemoryRef, MemoryRefMut, Module, PotentialCoroCallResult, Result,
+    Store, SuspendedFunc,
+};
 
 /// An instanciated WebAssembly module
 ///
@@ -265,16 +268,16 @@ impl ModuleInstance {
     }
 
     /// Invoke the start function of the module
-    /// 
+    ///
     /// Returns None if the module has no start function
     /// If start function suspends, returns SuspededFunc.
     /// Only when it finishes can this module instance be considered instantiated
-    pub fn start_coro(&self, store: &mut Store) -> Result<Option<PotentialCoroCallResult<(), SuspendFunc>>> {
+    pub fn start_coro(&self, store: &mut Store) -> Result<Option<PotentialCoroCallResult<(), SuspendedFunc>>> {
         let Some(func) = self.start_func(store)? else {
             return Ok(None);
         };
 
         let res = func.call_coro(store, &[])?;
-        Ok(Some(res.map_result(|_|{()})))
+        Ok(Some(res.map_result(|_| {})))
     }
 }

crates/tinywasm/src/interpreter/executor.rs

@@ -70,7 +70,7 @@ impl<'store, 'stack> Executor<'store, 'stack> {
     #[inline(always)]
     pub(crate) fn resume(&mut self, res_arg: ResumeArgument) -> Result<ExecOutcome> {
         if let Some(coro_state) = self.suspended_host_coro.as_mut() {
-            let ctx = FuncContext { store: &mut self.store, module_addr: self.module.id() };
+            let ctx = FuncContext { store: self.store, module_addr: self.module.id() };
             let host_res = coro_state.coro_state.resume(ctx, res_arg)?;
             let res = match host_res {
                 CoroStateResumeResult::Return(res) => res,
@@ -120,7 +120,7 @@ impl<'store, 'stack> Executor<'store, 'stack> {
         }
 
         if let Some(mut cb) = self.store.suspend_cond.suspend_cb.take() {
-            let should_suspend = matches!(cb(&self.store), ControlFlow::Break(()));
+            let should_suspend = matches!(cb(self.store), ControlFlow::Break(()));
             self.store.suspend_cond.suspend_cb = Some(cb); // put it back
             if should_suspend {
                 return ReasonToBreak::Suspended(SuspendReason::SuspendedCallback).into();
@@ -416,20 +416,19 @@ impl<'store, 'stack> Executor<'store, 'stack> {
     }
     fn exec_call_host(&mut self, host_func: Rc<HostFunction>, func_ref: u32) -> ControlFlow<ReasonToBreak> {
         let params = self.stack.values.pop_params(&host_func.ty.params);
-        let res =
-            host_func.call(FuncContext { store: self.store, module_addr: self.module.id() }, &params).to_cf()?;
+        let res = host_func.call(FuncContext { store: self.store, module_addr: self.module.id() }, &params).to_cf()?;
         match res {
             PotentialCoroCallResult::Return(res) => {
                 self.stack.values.extend_from_wasmvalues(&res);
                 self.cf.incr_instr_ptr();
                 self.check_should_suspend()?; // who knows how long we've spent in host function
-                return ControlFlow::Continue(());
+                ControlFlow::Continue(())
             }
             PotentialCoroCallResult::Suspended(suspend_reason, state) => {
                 self.suspended_host_coro =
                     Some(SuspendedHostCoroState { coro_state: state, coro_orig_function: func_ref });
                 self.cf.incr_instr_ptr();
-                return ReasonToBreak::Suspended(suspend_reason).into();
+                ReasonToBreak::Suspended(suspend_reason).into()
             }
         }
     }
@@ -527,10 +526,10 @@ impl<'store, 'stack> Executor<'store, 'stack> {
         if block_ty.is_none() {
             return self.exec_return();
         }
-        
+
         self.cf.incr_instr_ptr();
 
-        if matches!(block_ty, Some(BlockType::Loop)){
+        if matches!(block_ty, Some(BlockType::Loop)) {
             self.check_should_suspend()?;
         }
         ControlFlow::Continue(())
@@ -581,7 +580,7 @@ impl<'store, 'stack> Executor<'store, 'stack> {
 
         self.cf.incr_instr_ptr();
 
-        if matches!(block_ty, Some(BlockType::Loop)){
+        if matches!(block_ty, Some(BlockType::Loop)) {
             self.check_should_suspend()?;
         }
         ControlFlow::Continue(())

crates/tinywasm/src/lib.rs

@@ -93,7 +93,7 @@ pub(crate) mod log {
 mod error;
 pub use coro::{CoroState, CoroStateResumeResult, PotentialCoroCallResult, SuspendReason};
 pub use error::*;
-pub use func::{FuncHandle, FuncHandleTyped, SuspendFunc};
+pub use func::{FuncHandle, FuncHandleTyped, SuspendedFunc};
 pub use imports::*;
 pub use instance::ModuleInstance;
 pub use module::{IncompleteModule, Module};

crates/tinywasm/src/module.rs

@@ -1,4 +1,4 @@
-use crate::{CoroState, Imports, ModuleInstance, PotentialCoroCallResult, Result, Store, SuspendFunc};
+use crate::{CoroState, Imports, ModuleInstance, PotentialCoroCallResult, Result, Store, SuspendedFunc};
 use tinywasm_types::{ResumeArgument, TinyWasmModule};
 
 /// A WebAssembly Module
@@ -69,15 +69,12 @@ impl Module {
             Some(res) => res,
             None => return Ok(PotentialCoroCallResult::Return(instance)),
         };
-        match core_res {
-            crate::PotentialCoroCallResult::Return(_) => return Ok(PotentialCoroCallResult::Return(instance)),
+        Ok(match core_res {
+            crate::PotentialCoroCallResult::Return(_) => PotentialCoroCallResult::Return(instance),
             crate::PotentialCoroCallResult::Suspended(suspend_reason, state) => {
-                return Ok(PotentialCoroCallResult::Suspended(
-                    suspend_reason,
-                    IncompleteModule(Some(HitTheFloor(instance, state))),
-                ))
+                PotentialCoroCallResult::Suspended(suspend_reason, IncompleteModule(Some(HitTheFloor(instance, state))))
             }
-        }
+        })
     }
 }
 
@@ -86,9 +83,9 @@ impl Module {
 pub struct IncompleteModule(Option<HitTheFloor>);
 
 #[derive(Debug)]
-struct HitTheFloor(ModuleInstance, SuspendFunc);
+struct HitTheFloor(ModuleInstance, SuspendedFunc);
 
-impl<'a> CoroState<ModuleInstance, &'a mut Store> for IncompleteModule {
+impl CoroState<ModuleInstance, &mut Store> for IncompleteModule {
     fn resume(&mut self, ctx: &mut Store, arg: ResumeArgument) -> Result<crate::CoroStateResumeResult<ModuleInstance>> {
         let mut body: HitTheFloor = match self.0.take() {
             Some(body) => body,

crates/tinywasm/src/store/mod.rs

@@ -486,10 +486,13 @@ fn get_pair_mut<T>(slice: &mut [T], i: usize, j: usize) -> Option<(&mut T, &mut
     Some(pair)
 }
 
+/// user callback for use in [SuspendConditions::suspend_cb]
+pub type ShouldSuspendCb = Box<dyn FnMut(&Store) -> ControlFlow<(), ()>>;
+
 // idk where really to put it, but it should be accessible to host environment (obviously)
-// and, less obviously, to host functions called from it, for calling wasm callbacks and propagating this config to them
-// or just complying with suspend conditions
-/// used to limit when how much cpu time wasm code should take
+// and (less obviously) to host functions called from it - for calling wasm callbacks and propagating this config to them
+// (or just complying with suspend conditions themselves)
+/// used to limit execution time wasm code takes
 #[derive(Default)]
 pub struct SuspendConditions {
     /// atomic flag. when set to true it means execution should suspend
@@ -499,13 +502,14 @@ pub struct SuspendConditions {
     /// instant at which execution should suspend
     /// can be used to control how much time will be spent in wasm without requiring other threads
     /// such as for time-slice multitasking
+    /// uses rust standard library for checking time - so not available in no-std
     #[cfg(feature = "std")]
     pub timeout_instant: Option<crate::std::time::Instant>,
 
     /// callback that returns [`ControlFlow::Break`]` when execution should suspend
     /// can be used when above methods are insufficient or
-    /// instead of [`timeout_instant`] in no-std builds if you have a clock function
-    pub suspend_cb: Option<Box<dyn FnMut(&Store) -> ControlFlow<(), ()>>>,
+    /// instead of [`timeout_instant`] in no-std builds, if you have your own clock function
+    pub suspend_cb: Option<ShouldSuspendCb>,
 }
 
 impl Debug for SuspendConditions {
@@ -521,6 +525,14 @@ impl Debug for SuspendConditions {
     }
 }
 
+impl SuspendConditions {
+    /// sets timeout_instant to `how_long` from now
+    #[cfg(feature = "std")]
+    pub fn set_timeout_in(&mut self, how_long: crate::std::time::Duration) {
+        self.timeout_instant = Some(crate::std::time::Instant::now() + how_long);
+    }
+}
+
 impl Store {
     /// sets suspend conditions for store
     pub fn set_suspend_conditions(&mut self, val: SuspendConditions) {
@@ -532,7 +544,7 @@ impl Store {
     }
     /// transforms suspend conditions for store using user-provided function
     pub fn update_suspend_conditions(&mut self, replacer: impl FnOnce(SuspendConditions) -> SuspendConditions) {
-        let temp = core::mem::replace(&mut self.suspend_cond, SuspendConditions::default());
+        let temp = core::mem::take(&mut self.suspend_cond);
         self.suspend_cond = replacer(temp);
     }
 }

tests/wasm_resume.rs

@@ -330,7 +330,7 @@ fn overflow_detect_snippet(var: &str) -> String {
 struct TestedModule {
     store: Store,
     instance: ModuleInstance,
-    resumable: Option<tinywasm::SuspendFunc>,
+    resumable: Option<tinywasm::SuspendedFunc>,
 }
 
 impl TestedModule {