Struct mlua::Thread

source ·

pub struct Thread<'lua>(_);

Expand description

Handle to an internal Lua thread (or coroutine).

Implementations

source

impl<'lua> Thread<'lua>

source

pub fn resume<A, R>(&self, args: A) -> Result<R>where
A: ToLuaMulti<'lua>,
R: FromLuaMulti<'lua>,

Resumes execution of this thread.

Equivalent to coroutine.resume.

Passes args as arguments to the thread. If the coroutine has called coroutine.yield, it will return these arguments. Otherwise, the coroutine wasn’t yet started, so the arguments are passed to its main function.

If the thread is no longer in Active state (meaning it has finished execution or encountered an error), this will return Err(CoroutineInactive), otherwise will return Ok as follows:

If the thread calls coroutine.yield, returns the values passed to yield. If the thread returns values from its main function, returns those.

Examples

let thread: Thread = lua.load(r#"
    coroutine.create(function(arg)
        assert(arg == 42)
        local yieldarg = coroutine.yield(123)
        assert(yieldarg == 43)
        return 987
    end)
"#).eval()?;

assert_eq!(thread.resume::<_, u32>(42)?, 123);
assert_eq!(thread.resume::<_, u32>(43)?, 987);

// The coroutine has now returned, so `resume` will fail
match thread.resume::<_, u32>(()) {
    Err(Error::CoroutineInactive) => {},
    unexpected => panic!("unexpected result {:?}", unexpected),
}

source

pub fn status(&self) -> ThreadStatus

Gets the status of the thread.

source

pub fn reset(&self, func: Function<'lua>) -> Result<()>

Resets a thread

In Lua 5.4: cleans its call stack and closes all pending to-be-closed variables. Returns a error in case of either the original error that stopped the thread or errors in closing methods.

In LuaJIT and Luau: resets to the initial state of a newly created Lua thread. Lua threads in arbitrary states (like yielded or errored) can be reset properly.

Sets a Lua function for the thread afterwards.

Requires feature = "lua54" OR feature = "luajit,vendored" OR feature = "luau"

source

pub fn into_async<A, R>(self, args: A) -> AsyncThread<'lua, R>ⓘNotable traits for AsyncThread<'lua, R>`impl<'lua, R> Future for AsyncThread<'lua, R>where R: FromLuaMulti<'lua>, type Output = Result<R>;`where
 A: ToLuaMulti<'lua>,
 R: FromLuaMulti<'lua>,

Available on crate feature async only.

Converts Thread to an AsyncThread which implements Future and Stream traits.

args are passed as arguments to the thread function for first call. The object calls resume() while polling and also allows to run rust futures to completion using an executor.

Using AsyncThread as a Stream allows to iterate through coroutine.yield() values whereas Future version discards that values and poll until the final one (returned from the thread function).

Requires feature = "async"

Examples

use futures::stream::TryStreamExt;
let thread: Thread = lua.load(r#"
    coroutine.create(function (sum)
        for i = 1,10 do
            sum = sum + i
            coroutine.yield(sum)
        end
        return sum
    end)
"#).eval()?;

let mut stream = thread.into_async::<_, i64>(1);
let mut sum = 0;
while let Some(n) = stream.try_next().await? {
    sum += n;
}

assert_eq!(sum, 286);