Add yielding support.

Author: radiantgurl

src/error.rs

@@ -1,3 +1,4 @@
+use super::MultiValue;
 use std::error::Error as StdError;
 use std::fmt;
 use std::io::Error as IoError;
@@ -205,6 +206,12 @@ pub enum Error {
         /// Underlying error.
         cause: Arc<Error>,
     },
+    /// Yield.
+    ///
+    /// Not an error.
+    /// Returning `Err(Yielding(...))` from a Rust callback will yield the value as a Lua value.
+    /// If it cannot yield, it will raise an error.
+    Yielding(MultiValue),
 }
 
 /// A specialized `Result` type used by `mlua`'s API.
@@ -321,6 +328,9 @@ impl fmt::Display for Error {
             Error::WithContext { context, cause } => {
                 writeln!(fmt, "{context}")?;
                 write!(fmt, "{cause}")
+            },
+            Error::Yielding(_) => {
+                write!(fmt, "yield across Rust/Lua boundary")
             }
         }
     }

src/state/util.rs

@@ -6,6 +6,7 @@ use std::sync::Arc;
 use crate::error::{Error, Result};
 use crate::state::{ExtraData, RawLua};
 use crate::util::{self, get_internal_metatable, WrappedFailure};
+use crate::IntoLuaMulti;
 
 pub(super) struct StateGuard<'a>(&'a RawLua, *mut ffi::lua_State);
 
@@ -107,7 +108,19 @@ where
             prealloc_failure.release(state, extra);
             r
         }
-        Ok(Err(err)) => {
+        Ok(Err(mut err)) => {
+            if let Error::Yielding(tuple) = err {
+                let raw = extra.as_ref().unwrap_unchecked().raw_lua();
+                match tuple.push_into_stack_multi(raw) {
+                    Ok(nargs) => {
+                        ffi::lua_yield(state, nargs);
+                        unreachable!();
+                    }
+                    Err(new_err) => {
+                        err = new_err;
+                    }
+                }
+            }
             let wrapped_error = prealloc_failure.r#use(state, extra);
 
             // Build `CallbackError` with traceback